Query routing decisions
Enterprise Edition

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, or over the HTTP protocol from a client, is routed to a database for execution. The routing decision process is illustrated in the following decision tree:

routing decisions
Figure 1. Illustrated routing decision tree

  1. The query router determines the name of the target database (execution context) by picking the first from the following that has a value:

  2. If there is an already open transaction to the target database, local or remote, it proceeds to step 6. Otherwise, it proceeds to step 3.

  3. Determines the type of the target database (execution context type) depending on the type of database determined in step 1:

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

    • If the target database is a composite database, the context type is Composite. This also allows the query to target multiple databases.

    • If the target database is a remote alias, the context type is External.

  4. Determines the location of execution:

    Internal

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

    • If the transaction mode is READ and the database is hosted on this server, the location is Local.

    • If the transaction mode is READ and the database is hosted on another server with server-side routing enabled, the location is Remote (using the routing advertised address of that server). If server-side routing is not enabled, then the operation fails.

    • If the transaction mode is WRITE and the database on this server is the leader for that database, the location is Local.

    • If the transaction mode is WRITE and the database on this server is not the leader for that database, but server-side routing is enabled, then the location is Remote (using the routing advertised address of that server). If server-side routing is not enabled, then the process fails.

    Composite type

    Location is Local (for this part of the query).

    External type

    Location is Remote (using the URI and database given in the configuration).

  5. Opens a transaction depending on the determined location:

    • For Local, opens a transaction to the database on this server.

    • For Remote, opens a driver transaction to the database using the URI determined in step 4.

  6. Executes the query in the opened transaction.