Query routing decisions

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

Routing decision tree

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

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 a Composite database, then the context type is Composite.

    This also allows the query to target multiple databases.

  • If the target database is a Remote Alias, then the context type is External.

Step 4: Determine the location of execution

  • If context type is Internal

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

    • and the transaction mode is READ

    • if the transaction mode is WRITE

  • If context type is Composite, 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 server.

  • 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