Cypher query options

Query execution can be fine-tuned through the use of query options.

In order to use one or more of these options, the query must be prepended with CYPHER, followed by the query option(s), as exemplified thus:

CYPHER query-option [further-query-options] query

Cypher runtime

The Cypher runtime runs queries and returns records based on an execution plan. Depending on the Neo4j edition, there are two different runtimes available:

Slotted

In the slotted runtime, the operators in the execution plan are chained together in a tree, where each non-leaf operator feeds from one or two child operators. The tree comprises nested iterators, which stream records from the top iterator, which pulls from the next iterator, and so on. Each variable in the query gets a dedicated "slot" or offset, which the runtime uses for accessing (e.g., slotRow[0]).
The slotted runtime covers all operators and queries.
In Neo4j 5, it is the default for Community Edition.

Pipelined

In the pipelined runtime, the operators are grouped into pipelines in the execution plan to generate new combinations and orders of execution, which are optimized for performance and memory usage.
The pipelined runtime covers most operators and queries. If the pipelined runtime does not support a query, the planner falls back to the slotted runtime.
It is the default for Enterprise Edition.

Option Description Default

runtime=slotted

Forces the Cypher query planner to use the slotted runtime.

Default for Community Edition.

runtime=pipelined

Forces the Cypher query planner to use the pipelined runtime.

Default for Enterprise Edition.

Cypher planner

The Cypher planner takes a Cypher query and computes an execution plan that solves it. For any given query there is likely a number of execution plan candidates that each solve the query in a different way. The planner uses a search algorithm to find the execution plan with the lowest estimated execution cost.

This table describes the available planner options:

Query option Description Default

planner=cost

Use cost based planning with default limits on plan search space and time.

planner=idp

Synonym for planner=cost.

planner=dp

Use cost based planning without limits on plan search space and time to perform an exhaustive search for the best execution plan.

Using this option can significantly increase the planning time of the query.

Cypher connect-components planner

One part of the Cypher planner is responsible for combining sub-plans for separate patterns into larger plans - a task referred to as connecting components.

This table describes the available query options for the connect-components planner:

Query option Description Default

connectComponentsPlanner=greedy

Use a greedy approach when combining sub-plans.

Using this option can significantly reduce the planning time of the query.

connectComponentsPlanner=idp

Use the cost based IDP search algorithm when combining sub-plans.

Using this option can significantly increase the planning time of the query but usually finds better plans.

Cypher update strategy

This option affects the eagerness of updating queries.

The possible values are:

Query option Description Default

updateStrategy=default

Update queries are executed eagerly when needed.

updateStrategy=eager

Update queries are always executed eagerly.

Cypher expression engine

This option affects how the runtime evaluates expressions.

The possible values are:

Query option Description Default

expressionEngine=default

Compile expressions and use the compiled expression engine when needed.

expressionEngine=interpreted

Always use the interpreted expression engine.

expressionEngine=compiled

Always compile expressions and use the compiled expression engine.

Cannot be used together with runtime=interpreted.

Cypher operator engine

This query option affects whether the pipelined runtime attempts to generate compiled code for groups of operators.

The possible values are:

Query option Description Default

operatorEngine=default

Attempt to generate compiled operators when applicable.

operatorEngine=interpreted

Never attempt to generate compiled operators.

operatorEngine=compiled

Always attempt to generate compiled operators.

Cannot be used together with runtime=interpreted or runtime=slotted.

Cypher interpreted pipes fallback

This query option affects how the pipelined runtime behaves for operators it does not directly support.

The available options are:

Query option Description Default

interpretedPipesFallback=default

Equivalent to interpretedPipesFallback=whitelisted_plans_only.

interpretedPipesFallback=disabled

If the plan contains any operators not supported by the pipelined runtime then another runtime is chosen to execute the entire plan.

Cannot be used together with runtime=interpreted or runtime=slotted.

interpretedPipesFallback=whitelisted_plans_only

Parts of the execution plan can be executed on another runtime. Only certain operators are allowed to execute on another runtime.

Cannot be used together with runtime=interpreted or runtime=slotted.

interpretedPipesFallback=all

Parts of the execution plan may be executed on another runtime. Any operator is allowed to execute on another runtime. Queries with this option set might produce incorrect results, or fail.

Cannot be used together with runtime=interpreted or runtime=slotted.

This setting is experimental, and using it in a production environment is discouraged.

Cypher replanning

Cypher replanning occurs in the following circumstances:

There may be situations where Cypher query planning can occur at a non-ideal time. For example, when a query must be as fast as possible and a valid plan is already in place.

Replanning is not performed for all queries at once; it is performed in the same thread as running the query, and can block the query. However, replanning one query does not replan any other queries.

There are three different replan options available:

Option Description Default

replan=default

This is the planning and replanning option as described above.

replan=force

This will force a replan, even if the plan is valid according to the planning rules. Once the new plan is complete, it replaces the existing one in the query cache.

replan=skip

If a valid plan already exists, it will be used even if the planning rules would normally dictate that it should be replanned.

The replan option is prepended to queries.

For example:

CYPHER replan=force MATCH ...

In a mixed workload, you can force replanning by using the Cypher EXPLAIN commands. This can be useful to schedule replanning of queries which are expensive to plan, at known times of low load. Using EXPLAIN will make sure the query is only planned, but not executed.

For example:

CYPHER replan=force EXPLAIN MATCH ...

During times of known high load, replan=skip can be useful to not introduce unwanted latency spikes.