Cypher and Neo4j

This section discusses aspects of Neo4j that are important to consider when using Cypher®.

Cypher and the different editions of Neo4j

Neo4j consists of two editions: a commercial Enterprise Edition, and a Community Edition.

Cypher works almost identically between the two editions, but there are key areas in which they differ:

Feature Enterprise Edition Community Edition

Multi-database

Any number of user databases.

Only system and one user database.

Role-based security

User, role, and privilege management for flexible access control and sub-graph access control.

Multi-user management. All users have full access rights.

Constraints

All constraints: node property existence constraints, relationship property existence constraints, node property type constraints, relationship property type constraints, node property uniqueness constraints, relationship property uniqueness constraints, node key constraints, and relationship key constraints.

Only node and relationship property uniqueness constraints.

Key Neo4j terminology

Cypher queries are executed against a Neo4j database, but normally apply to specific graphs. It is important to understand the meaning of these terms and exactly when a graph is not a database.

DBMS

A Neo4j Database Management System is capable of containing and managing multiple graphs contained in databases. Client applications will connect to the DBMS and open sessions against it. A client session provides access to any graph in the DBMS.

Graph

Refers to a data model within a database. Normally there is only one graph within each database, and many administrative commands that refer to a specific graph do so using the database name. Cypher queries executed in a session may declare which graph they apply to, or use a default, given by the session. Composite databases can contain multiple graphs, by means of aliases to other databases. Queries submitted to composite databases may refer to multiple graphs within the same query. For more information, see Operations manual → Composite databases.

Database

A database is a storage and retrieval mechanism for collecting data in a defined space on disk and in memory.

Built-in databases in Neo4j

All Neo4j servers contain a built-in database called system, which behaves differently than all other databases. The system database stores system data and you can not perform graph queries against it.

A fresh installation of Neo4j includes two databases:

  • system - the system database described above, containing meta-data on the DBMS and security configuration.

  • neo4j - the default database, named using the config option dbms.default_database=neo4j.

For more information about the system database, see the sections on Database management and Access control.

Query considerations

Most of the time Cypher queries are reading or updating queries, which are run against a graph. There are also administrative commands that apply to a database, or to the entire DBMS. Administrative commands cannot be run in a session connected to a normal user database, but instead need to be run within a session connected to the system database. Administrative commands execute on the system database. If an administrative command is submitted to a user database, it is rerouted to the system database.

Cypher and Neo4j transactions

All Cypher queries run within transactions. Modifications done by updating queries are held in memory by the transaction until it is committed, at which point the changes are persisted to disk and become visible to other transactions. If an error occurs - either during query evaluation, such as division by zero, or during commit, such as constraint violations - the transaction is automatically rolled back, and no changes are persisted in the graph.

In short, an updating query always either fully succeeds or does not succeed at all.

A query that makes a large number of updates consequently uses large amounts of memory since the transaction holds changes in memory. For memory configuration in Neo4j, see the Neo4j Operations Manual → Memory configuration.

Explicit and implicit transactions

Transactions in Neo4j can be either explicit or implicit.

Explicit Implicit

Opened by the user.

Opened automatically.

Can execute multiple Cypher queries in sequence.

Can execute a single Cypher query.

Committed, or rolled back, by the user.

Committed automatically when a transactions finishes successfully.

Queries that start separate transactions themselves, such as queries using CALL { ... } IN TRANSACTIONS, are only allowed in implicit mode. Explicit transactions cannot be managed directly from queries, they must be managed via APIs or tools.

For examples of the API, or the commands used to start and commit transactions, refer to the API or tool-specific documentation:

When writing procedures or using Neo4j embedded, remember that all iterators returned from an execution result should be either fully exhausted or closed. This ensures that the resources bound to them are properly released.

DBMS transactions

Beginning a transaction while connected to a DBMS will start a DBMS-level transaction. A DBMS-level transaction is a container for database transactions.

A database transaction is started when the first query to a specific database is issued. Database transactions opened inside a DBMS-level transaction are committed or rolled back when the DBMS-level transaction is committed or rolled back.

DBMS transactions have the following limitations:

  • Only one database can be written to in a DBMS transaction.

  • Cypher operations fall into the following main categories:

    • Operations on graphs.

    • Schema commands.

    • Administration commands.

It is not possible to combine any of these workloads in a single DBMS transaction.

ACID compliance

Neo4j is fully ACID compliant. This means that:

  • Atomicity - If a part of a transaction fails, the database state is left unchanged.

  • Consistency — Every transaction leaves the database in a consistent state.

  • Isolation — During a transaction, modified data cannot be accessed by other operations.

  • Durability — The DBMS can always recover the results of a committed transaction.