3.6.1. Cypher query options

This section describes the query options available in Cypher.

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.

3.6.1.1. Cypher version

Occasionally, there is a requirement to use a previous version of the Cypher compiler when running a query. Here we detail the available versions:

Query option Description Default?

2.3

This will force the query to use Neo4j Cypher 2.3.

 

3.1

This will force the query to use Neo4j Cypher 3.1.

 

3.2

This will force the query to use Neo4j Cypher 3.2.

 

3.3

This will force the query to use Neo4j Cypher 3.3. As this is the default version, it is not necessary to use this option explicitly.

X

3.6.1.2. Cypher planner

Each query is turned into an execution plan by something called the execution planner. The execution plan tells Neo4j which operations to perform when executing the query.

Neo4j uses a cost-based execution planning strategy (known as the 'cost' planner): the statistics service in Neo4j is used to assign a cost to alternative plans and picks the cheapest one.

All versions of Neo4j prior to Neo4j 3.2 also included a rule-based planner, which used rules to produce execution plans. This planner considered available indexes, but did not use statistical information to guide the query compilation. The rule planner was removed in Neo4j 3.2 owing to inferior query execution performance when compared with the cost planner.

Option Description Default?

planner=rule

This will force the query to use the rule planner, and will therefore cause the query to fall back to using Cypher 3.1.

 

planner=cost

Neo4j 3.3 uses the cost planner for all queries, and therefore it is not necessary to use this option explicitly.

X

It is also possible to change the default planner by using the cypher.planner configuration setting (see Operations Manual → Configuration Settings).

You can see which planner was used by looking at the execution plan.

When Cypher is building execution plans, it looks at the schema to see if it can find indexes it can use. These index decisions are only valid until the schema changes, so adding or removing indexes leads to the execution plan cache being flushed.

3.6.1.3. Cypher runtime

Using the execution plan, the query is executed — and records returned — by the query engine, or runtime. Depending on whether Neo4j Enterprise Edition or Neo4j Community Edition is used, there are three different runtimes available:

Interpreted
In this 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 thus comprises nested iterators, and the records are streamed in a pipelined manner from the top iterator, which pulls from the next iterator and so on.
Slotted
This is very similar to the interpreted runtime, except that there are additional optimizations regarding the way in which the records are streamed through the iterators. This results in improvements to both the performance and memory usage of the query. In effect, this can be thought of as a the 'faster interpreted' runtime. This is still under development and does not support all possible operators or queries.

The slotted runtime is only available in Neo4j Enterprise Edition.

Compiled
Algorithms are employed to intelligently group the operators in the execution plan in order to generate new combinations and orders of execution which are optimised for performance and memory usage. While this should lead to superior performance in most cases (over both the interpreted and slotted runtimes), it is still under development and does not support all possible operators or queries (the slotted runtime has a higher coverage of operators and queries).

The compiled runtime is only available in Neo4j Enterprise Edition.

In Enterprise Edition, the query execution engine’s fallback mechanism is to try the compiled runtime first, and if it does not support the query, to then try the slotted runtime, and if that also does not support the query, to finally fall back to the interpreted runtime, which supports all queries.

Option Description Default?

runtime=interpreted

This will force the query execution engine to use the interpreted runtime.

This is the default option for some queries in Enterprise Edition, and the only option for all queries in Community Edition (so it is not necessary to use this option in Community Edition).

runtime=slotted

This will cause the query execution engine to use the slotted runtime if it supports the query, and fall back to using the interpreted runtime if it does not.

This is the default option for some queries in Enterprise Edition only.

runtime=compiled

This will cause the query execution engine to use the compiled runtime if it supports the query. If the compiled runtime does not support the query, the engine will fall back to the slotted runtime, and, failing that, to the interpreted runtime.

This is the default option for some queries in Enterprise Edition only.