Query routing decisions

Introduction

A query that arrives at a Neo4j server, over the bolt protocol from a driver, undergoes query routing. Query routing is the process of deciding with which Cypher executor (database) and at which physical location the query should be executed.

Routing decision tree

Before the query is executed, these are the decisions taken during query routing:

Step 1: Determine the name of the target database

Pick the first of these that has a value:

  1. Cypher USE clause

  2. Driver session database

  3. Home or default database

Step 2: Reuse open transaction

  • If there is an already open transaction to the target database, local or remote, then proceed to step 6.

  • If not, then proceed to step 3.

Step 3: Determine the type of the target database (execution context type)

  • If the target database is a database in this DBMS, then the context type is Internal.

  • If the target database is the Fabric virtual database, then the context type is Fabric.

    • This also allows the query to target multiple databases.

  • If the target database is a Fabric graph, then the context type is External.

Step 4: Determine the location of execution

  • If context type is Internal, then …​

    • if the URI scheme is bolt:// (routing disabled), then location is Local.

    • if transaction mode is READ, then location is Local.

    • if transaction mode is WRITE, then …​

      • if the local member is the leader for the database, then location is Local.

      • if the another member is the leader for the database, then …​

  • If context type is Fabric, then location is Local (for this part of the query).

  • If context type is External, then location is Remote (using the URI and database given in the configuration).

Step 5: Open a transaction

  • If location is Local, then open a transaction to the database on this member.

  • If location is Remote, then open a driver transaction to the database using the URI determined in step 4.

Step 6: Execute query

  • Execute the query in the open transaction.

Illustrated routing decision tree

routing decisions
Figure 1. Illustrated routing decision tree