3.5.1. Indexes

This section explains how to work with indexes in Neo4j and Cypher.

3.5.1.1. Introduction

A database index is a redundant copy of information in the database for the purpose of making retrieving said data more efficient. This comes at the cost of additional storage space and slower writes, so deciding what to index and what not to index is an important and often non-trivial task.

Cypher enables the creation of indexes on one or more properties for all nodes that have a given label:

  • An index that is created on a single property for any given label is called a single-property index.
  • An index that is created on more than one property for any given label is called a composite index. Differences in the usage patterns between composite and single-property indexes are detailed in the examples below.

Once an index has been created, it will automatically be managed and kept up to date by the database when the graph is changed. Neo4j will automatically pick up and start using the index once it has been created and brought online.

3.5.1.2. Create a single-property index

An index on a single property for all nodes that have a particular label can be created with CREATE INDEX ON :Label(property). Note that the index is not immediately available, but will be created in the background.

Query. 

CREATE INDEX ON :Person(firstname)

Result. 

+--------------------------------------------+
| No data returned, and nothing was changed. |
+--------------------------------------------+

3.5.1.3. Get a list of all indexes in the database

Calling the built-in procedure db.indexes will list all the indexes in the database.

Query. 

CALL db.indexes

Result. 

+------------------------------------------------------------------------------------------------------------------------------------------+
| description                   | label    | properties    | state    | type                  | provider                                   |
+------------------------------------------------------------------------------------------------------------------------------------------+
| "INDEX ON :Person(firstname)" | "Person" | ["firstname"] | "ONLINE" | "node_label_property" | {version -> "1.0", key -> "lucene+native"} |
+------------------------------------------------------------------------------------------------------------------------------------------+
1 row

3.5.1.4. Create a composite index

An index on multiple properties for all nodes that have a particular label — i.e. a composite index — can be created with CREATE INDEX ON :Label(prop1, …​, propN). Only nodes labeled with the specified label and which contain all the properties in the index definition will be added to the index.

The following statement will create a composite index on all nodes labeled with Person and which have both a firstname and surname property:

CREATE INDEX ON :Person(firstname, surname)

Now, assume the following query is run:

CREATE (a:Person {firstname: 'Bill', surname: 'Johnson', age: 34}),
(b:Person {firstname: 'Sue', age: 39}

Node a has both a firstname and a surname property, and so it will be added to the composite index. However, as node b has no surname property, it will not be added to the composite index.

Note that the composite index is not immediately available, but will be created in the background.

3.5.1.5. Drop a single-property index

An index on all nodes that have a label and single property combination can be dropped with DROP INDEX ON :Label(property).

Query. 

DROP INDEX ON :Person(firstname)

Result. 

+-------------------+
| No data returned. |
+-------------------+
Indexes removed: 1

3.5.1.6. Drop a composite index

A composite index on all nodes that have a label and multiple property combination can be dropped with DROP INDEX ON :Label(prop1, …​, propN).

The following statement will drop a composite index on all nodes labeled with Person and which have both a firstname and surname property:

DROP INDEX ON :Person(firstname, surname)

3.5.1.7. Use index

There is usually no need to specify which indexes to use in a query, Cypher will figure that out by itself. For example the query below will use the Person(firstname) index, if it exists. If you want Cypher to use specific indexes, you can enforce it using hints. See Section 3.6.4, “Planner hints and the USING keyword”.

Query. 

MATCH (person:Person { firstname: 'Andres' })
RETURN person

Query Plan. 

Compiler CYPHER 3.3

Planner COST

Runtime INTERPRETED

+-----------------+----------------+------+---------+-----------------+-------------------+----------------------+-----------+--------------------+
| Operator        | Estimated Rows | Rows | DB Hits | Page Cache Hits | Page Cache Misses | Page Cache Hit Ratio | Variables | Other              |
+-----------------+----------------+------+---------+-----------------+-------------------+----------------------+-----------+--------------------+
| +ProduceResults |              1 |    1 |       0 |               0 |                 0 |               0.0000 | person    |                    |
| |               +----------------+------+---------+-----------------+-------------------+----------------------+-----------+--------------------+
| +NodeIndexSeek  |              1 |    1 |       2 |               0 |                 0 |               0.0000 | person    | :Person(firstname) |
+-----------------+----------------+------+---------+-----------------+-------------------+----------------------+-----------+--------------------+

Total database accesses: 2

3.5.1.8. Use a single-property index with WHERE using equality

A query containing equality comparisons of a single indexed property in the WHERE clause is backed automatically by the index. If you want Cypher to use specific indexes, you can enforce it using hints. See Section 3.6.4, “Planner hints and the USING keyword”.

Query. 

MATCH (person:Person)
WHERE person.firstname = 'Andres'
RETURN person

Query Plan. 

Compiler CYPHER 3.3

Planner COST

Runtime INTERPRETED

+-----------------+----------------+------+---------+-----------------+-------------------+----------------------+-----------+--------------------+
| Operator        | Estimated Rows | Rows | DB Hits | Page Cache Hits | Page Cache Misses | Page Cache Hit Ratio | Variables | Other              |
+-----------------+----------------+------+---------+-----------------+-------------------+----------------------+-----------+--------------------+
| +ProduceResults |              1 |    1 |       0 |               0 |                 0 |               0.0000 | person    |                    |
| |               +----------------+------+---------+-----------------+-------------------+----------------------+-----------+--------------------+
| +NodeIndexSeek  |              1 |    1 |       2 |               0 |                 0 |               0.0000 | person    | :Person(firstname) |
+-----------------+----------------+------+---------+-----------------+-------------------+----------------------+-----------+--------------------+

Total database accesses: 2

3.5.1.9. Use a composite index with WHERE using equality

A query containing equality comparisons for all the properties of a composite index will automatically be backed by the same index.

For instance, assume the following composite index has been created:

CREATE INDEX ON :Person(firstname, surname)

The following query will use the composite index:

MATCH (n:Person)
WHERE n.firstname = 'Bill' AND n.surname = 'Johnson'
RETURN n

However, this query will not be backed by the composite index, as the query does not contain an equality predicate on the surname property:

MATCH (n:Person)
WHERE n.firstname = 'Bill'
RETURN n

The query above will only be backed by an index on the Person label and firstname property defined thus: :Person(firstname); i.e. a single-property index.

Moreover, unlike single-property indexes, composite indexes currently do not support queries containing the following types of predicates on properties in the index:

  • Existence: exists(n.prop)
  • Range: n.prop > value
  • STARTS WITH
  • ENDS WITH
  • CONTAINS

Therefore, the following queries will not be able to be backed by the composite index defined earlier:

MATCH (n:Person)
WHERE n.firstname = 'Bill' AND exists(n.surname)
RETURN n
MATCH (n:Person)
WHERE n.firstname = 'Bill' AND n.surname STARTS WITH 'Jo'
RETURN n

If you want Cypher to use specific indexes, you can enforce it using hints. See Section 3.6.4, “Planner hints and the USING keyword”.

3.5.1.10. Use index with WHERE using range comparisons

Single-property indexes are also automatically used for inequality (range) comparisons of an indexed property in the WHERE clause. Composite indexes are currently not able to support range comparisons. If you want Cypher to use specific indexes, you can enforce it using hints. See Section 3.6.4, “Planner hints and the USING keyword”.

Query. 

MATCH (person:Person)
WHERE person.firstname > 'B'
RETURN person

Query Plan. 

Compiler CYPHER 3.3

Planner COST

Runtime INTERPRETED

+-----------------------+----------------+------+---------+-----------------+-------------------+----------------------+-----------+------------------------------------------------------+
| Operator              | Estimated Rows | Rows | DB Hits | Page Cache Hits | Page Cache Misses | Page Cache Hit Ratio | Variables | Other                                                |
+-----------------------+----------------+------+---------+-----------------+-------------------+----------------------+-----------+------------------------------------------------------+
| +ProduceResults       |             10 |    1 |       0 |               0 |                 0 |               0.0000 | person    |                                                      |
| |                     +----------------+------+---------+-----------------+-------------------+----------------------+-----------+------------------------------------------------------+
| +NodeIndexSeekByRange |             10 |    1 |       2 |               0 |                 0 |               0.0000 | person    | :Person(firstname) < Parameter(  AUTOSTRING0,String) |
+-----------------------+----------------+------+---------+-----------------+-------------------+----------------------+-----------+------------------------------------------------------+

Total database accesses: 2

3.5.1.11. Use index with IN

The IN predicate on person.firstname in the following query will use the Person(firstname) index, if it exists. If you want Cypher to use specific indexes, you can enforce it using hints. See Section 3.6.4, “Planner hints and the USING keyword”.

Query. 

MATCH (person:Person)
WHERE person.firstname IN ['Andres', 'Mark']
RETURN person

Query Plan. 

Compiler CYPHER 3.3

Planner COST

Runtime INTERPRETED

+-----------------+----------------+------+---------+-----------------+-------------------+----------------------+-----------+--------------------+
| Operator        | Estimated Rows | Rows | DB Hits | Page Cache Hits | Page Cache Misses | Page Cache Hit Ratio | Variables | Other              |
+-----------------+----------------+------+---------+-----------------+-------------------+----------------------+-----------+--------------------+
| +ProduceResults |             24 |    2 |       0 |               0 |                 0 |               0.0000 | person    |                    |
| |               +----------------+------+---------+-----------------+-------------------+----------------------+-----------+--------------------+
| +NodeIndexSeek  |             24 |    2 |       4 |               0 |                 0 |               0.0000 | person    | :Person(firstname) |
+-----------------+----------------+------+---------+-----------------+-------------------+----------------------+-----------+--------------------+

Total database accesses: 4

3.5.1.12. Use index with STARTS WITH

The STARTS WITH predicate on person.firstname in the following query will use the Person(firstname) index, if it exists. Composite indexes are currently not able to support STARTS WITH, ENDS WITH and CONTAINS.

Query. 

MATCH (person:Person)
WHERE person.firstname STARTS WITH 'And'
RETURN person

Query Plan. 

Compiler CYPHER 3.3

Planner COST

Runtime INTERPRETED

+-----------------------+----------------+------+---------+-----------------+-------------------+----------------------+-----------+------------------------------------------------+
| Operator              | Estimated Rows | Rows | DB Hits | Page Cache Hits | Page Cache Misses | Page Cache Hit Ratio | Variables | Other                                          |
+-----------------------+----------------+------+---------+-----------------+-------------------+----------------------+-----------+------------------------------------------------+
| +ProduceResults       |             26 |    1 |       0 |               0 |                 0 |               0.0000 | person    |                                                |
| |                     +----------------+------+---------+-----------------+-------------------+----------------------+-----------+------------------------------------------------+
| +NodeIndexSeekByRange |             26 |    1 |       2 |               0 |                 0 |               0.0000 | person    | :Person(firstname STARTS WITH {  AUTOSTRING0}) |
+-----------------------+----------------+------+---------+-----------------+-------------------+----------------------+-----------+------------------------------------------------+

Total database accesses: 2

3.5.1.13. Use index when checking for the existence of a property

The exists(p.firstname) predicate in the following query will use the Person(firstname) index, if it exists. Composite indexes are currently not able to support the exists predicate.

Query. 

MATCH (p:Person)
WHERE exists(p.firstname)
RETURN p

Query Plan. 

Compiler CYPHER 3.3

Planner COST

Runtime INTERPRETED

+-----------------+----------------+------+---------+-----------------+-------------------+----------------------+-----------+--------------------+
| Operator        | Estimated Rows | Rows | DB Hits | Page Cache Hits | Page Cache Misses | Page Cache Hit Ratio | Variables | Other              |
+-----------------+----------------+------+---------+-----------------+-------------------+----------------------+-----------+--------------------+
| +ProduceResults |              2 |    2 |       0 |               0 |                 0 |               0.0000 | p         |                    |
| |               +----------------+------+---------+-----------------+-------------------+----------------------+-----------+--------------------+
| +NodeIndexScan  |              2 |    2 |       3 |               0 |                 1 |               0.0000 | p         | :Person(firstname) |
+-----------------+----------------+------+---------+-----------------+-------------------+----------------------+-----------+--------------------+

Total database accesses: 3

3.5.1.14. Use built-in procedures to manage and use explicit indexes

Explicit indexes are alternative data structures, in which a user can explicitly maintain search and seek data for nodes and relationships. These data structures are special-purpose and the procedures are primarily provided for users who have legacy deployments depending on such structures.

Signature Description

db.index.explicit.addNode

Add a node to an explicit index based on a specified key and value

db.index.explicit.addRelationship

Add a relationship to an explicit index based on a specified key and value

db.index.explicit.auto.searchNodes

Search nodes from explicit automatic index. Replaces START n=node:node_auto_index('key:foo*')

db.index.explicit.auto.searchRelationships

Search relationship from explicit automatic index. Replaces START r=relationship:relationship_auto_index('key:foo*')

db.index.explicit.auto.seekNodes

Get node from explicit automatic index. Replaces START n=node:node_auto_index(key = 'A')

db.index.explicit.auto.seekRelationships

Get relationship from explicit automatic index. Replaces START r=relationship:relationship_auto_index(key = 'A')

db.index.explicit.drop

Remove an explicit index - YIELD type, name, config

db.index.explicit.existsForNodes

Check if a node explicit index exists

db.index.explicit.existsForRelationships

Check if a relationship explicit index exists

db.index.explicit.forNodes

Get or create a node explicit index - YIELD type, name, config

db.index.explicit.forRelationships

Get or create a relationship explicit index - YIELD type, name, config

db.index.explicit.list

List all explicit indexes - YIELD type, name, config

db.index.explicit.removeNode(indexName

Remove a node from an explicit index with an optional key

db.index.explicit.removeRelationship

Remove a relationship from an explicit index with an optional key

db.index.explicit.searchNodes

Search nodes from explicit index. Replaces START n=node:nodes('key:foo*')

db.index.explicit.searchRelationships

Search relationship from explicit index. Replaces START r=relationship:relIndex('key:foo*')

db.index.explicit.searchRelationshipsBetween

Search relationship in explicit index, starting at the node 'in' and ending at 'out'

db.index.explicit.searchRelationshipsIn

Search relationship in explicit index, starting at the node 'in'

db.index.explicit.searchRelationshipsOut

Search relationship in explicit index, ending at the node 'out'

db.index.explicit.seekNodes

Get node from explicit index. Replaces START n=node:nodes(key = 'A')

db.index.explicit.seekRelationships

Get relationship from explicit index. Replaces START r=relationship:relIndex(key = 'A')

Table 3.201. db.index.explicit.addNode
Signature Description

db.index.explicit.addNode(indexName :: STRING?, node :: NODE?, key :: STRING?, value :: ANY?) :: (success :: BOOLEAN?)

Add a node to an explicit index based on a specified key and value

Table 3.202. db.index.explicit.addRelationship
Signature Description

db.index.explicit.addRelationship(indexName :: STRING?, relationship :: RELATIONSHIP?, key :: STRING?, value :: ANY?) :: (success :: BOOLEAN?)

Add a relationship to an explicit index based on a specified key and value

Table 3.203. db.index.explicit.auto.searchNodes
Signature Description

db.index.explicit.auto.searchNodes(query :: ANY?) :: (node :: NODE?, weight :: FLOAT?)

Search nodes from explicit automatic index. Replaces START n=node:node_auto_index('key:foo*')

Table 3.204. db.index.explicit.auto.searchRelationships
Signature Description

db.index.explicit.auto.searchRelationships(query :: ANY?) :: (relationship :: RELATIONSHIP?, weight :: FLOAT?)

Search relationship from explicit automatic index. Replaces START r=relationship:relationship_auto_index('key:foo*')

Table 3.205. db.index.explicit.auto.seekNodes
Signature Description

db.index.explicit.auto.seekNodes(key :: STRING?, value :: ANY?) :: (node :: NODE?)

Get node from explicit automatic index. Replaces START n=node:node_auto_index(key = 'A')

Table 3.206. db.index.explicit.auto.seekRelationships
Signature Description

db.index.explicit.auto.seekRelationships(key :: STRING?, value :: ANY?) :: (relationship :: RELATIONSHIP?)

Get relationship from explicit automatic index. Replaces START r=relationship:relationship_auto_index(key = 'A')

Table 3.207. db.index.explicit.drop
Signature Description

db.index.explicit.drop(indexName :: STRING?) :: (type :: STRING?, name :: STRING?, config :: MAP?)

Remove an explicit index - YIELD type, name, config

Table 3.208. db.index.explicit.existsForNodes
Signature Description

db.index.explicit.existsForNodes(indexName :: STRING?) :: (success :: BOOLEAN?)

Check if a node explicit index exists

Table 3.209. db.index.explicit.existsForRelationships
Signature Description

db.index.explicit.existsForRelationships(indexName :: STRING?) :: (success :: BOOLEAN?)

Check if a relationship explicit index exists

Table 3.210. db.index.explicit.forNodes
Signature Description

db.index.explicit.forNodes(indexName :: STRING?) :: (type :: STRING?, name :: STRING?, config :: MAP?)

Get or create a node explicit index - YIELD type, name, config

Table 3.211. db.index.explicit.forRelationships
Signature Description

db.index.explicit.forRelationships(indexName :: STRING?) :: (type :: STRING?, name :: STRING?, config :: MAP?)

Get or create a relationship explicit index - YIELD type, name, config

Table 3.212. db.index.explicit.list
Signature Description

db.index.explicit.list() :: (type :: STRING?, name :: STRING?, config :: MAP?)

List all explicit indexes - YIELD type, name, config

Table 3.213. db.index.explicit.removeNode
Signature Description

db.index.explicit.removeNode(indexName :: STRING?, node :: NODE?, key :: STRING?) :: (success :: BOOLEAN?)

Remove a node from an explicit index with an optional key

Table 3.214. db.index.explicit.removeRelationship
Signature Description

db.index.explicit.removeRelationship(indexName :: STRING?, relationship :: RELATIONSHIP?, key :: STRING?) :: (success :: BOOLEAN?)

Remove a relationship from an explicit index with an optional key

Table 3.215. db.index.explicit.searchNodes
Signature Description

db.index.explicit.searchNodes(indexName :: STRING?, query :: ANY?) :: (node :: NODE?, weight :: FLOAT?)

Search nodes from explicit index. Replaces START n=node:nodes('key:foo*')

Table 3.216. db.index.explicit.searchRelationships
Signature Description

db.index.explicit.searchRelationships(indexName :: STRING?, query :: ANY?) :: (relationship :: RELATIONSHIP?, weight :: FLOAT?)

Search relationship from explicit index. Replaces START r=relationship:relIndex('key:foo*')

Table 3.217. db.index.explicit.searchRelationshipsBetween
Signature Description

db.index.explicit.searchRelationshipsBetween(indexName :: STRING?, in :: NODE?, out :: NODE?, query :: ANY?) :: (relationship :: RELATIONSHIP?, weight :: FLOAT?)

Search relationship in explicit index, starting at the node 'in' and ending at 'out'

Table 3.218. db.index.explicit.searchRelationshipsIn
Signature Description

db.index.explicit.searchRelationshipsIn(indexName :: STRING?, in :: NODE?, query :: ANY?) :: (relationship :: RELATIONSHIP?, weight :: FLOAT?)

Search relationship in explicit index, starting at the node 'in'

Table 3.219. db.index.explicit.searchRelationshipsOut
Signature Description

db.index.explicit.searchRelationshipsOut(indexName :: STRING?, out :: NODE?, query :: ANY?) :: (relationship :: RELATIONSHIP?, weight :: FLOAT?)

Search relationship in explicit index, ending at the node 'out'

Table 3.220. db.index.explicit.seekNodes
Signature Description

db.index.explicit.seekNodes(indexName :: STRING?, key :: STRING?, value :: ANY?) :: (node :: NODE?)

Get node from explicit index. Replaces START n=node:nodes(key = 'A')

Table 3.221. db.index.explicit.seekRelationships
Signature Description

db.index.explicit.seekRelationships(indexName :: STRING?, key :: STRING?, value :: ANY?) :: (relationship :: RELATIONSHIP?)

Get relationship from explicit index. Replaces START r=relationship:relIndex(key = 'A')