Store formats

The store format dictates how a database in Neo4j, is stored on disk. The available formats are:

  • aligned Default

  • standard

  • high_limit Enterprise Edition

  • block Enterprise Edition GA in Neo4j 5.16

Neo4j’s newest store format is block. It has the best performance and supports the highest limits.

The block format is intended to replace all the older formats. It uses a range of different data structures and inlining techniques to achieve data locality and store related data together on disk. This allows more related data to be fetched by fewer read operations, resulting in better resource utilization.

The older store formats are based on the original standard format, each with different features and limitations. aligned, standard, and high_limit formats store most graph data in linked list-like structures on disk. The aligned format performs better than the standard but requires slightly more disk space. The high-limit format allows more nodes and relationships to be stored than standard but performs slightly worse and requires more disk space.

How to set the database store format

You can either set the store format when creating a new database or change the store format of an existing database.

Creating new databases

The default store format for all new databases is aligned. If you want to change it, you can set a new value for the db.format configuration in the neo4j.conf file.

You can also create a new database on a specific store format by passing the new format as an argument to the command creating the database, for example, neo4j-admin database import full or neo4j-admin database copy commands.

For example:

bin/neo4j-admin database import full ... --format=block blockdb

Changing the store format of existing databases

Changing the store format is possible by re-writing all data in the new format. Therefore, it requires that:

  • There is enough disk space for both old and new copies of the database.

  • The graph fits within the new format’s entity limits.

Changing the store format can be a time-consuming operation, depending on the size and complexity of the data in the database. Performance heavily depends on the speed of the disk and the amount of available memory.

In a standalone server

Changing the store format of an existing database in a standalone server requires the database to be offline. The following steps assume that you want to migrate the database called mydb to block format but the same steps apply to other formats.

  1. Stop the database using the Cypher command STOP DATABASE mydb.

  2. Change the store format of the stopped database using one of the following options:

    • Migrate an existing database using neo4j-admin database migrate command. For example:

      bin/neo4j-admin database migrate --to-format="block" mydb

    • Pass the new store format as an argument when using the neo4j-admin database copy command to create a copy of an existing database. For example:

      bin/neo4j-admin database copy --to-format="block" mydb blockdb

  3. After the successful completion, start the database using the Cypher command START DATABASE mydb.

In a cluster

Changing the store format of an existing database in a cluster requires that you restore a backup of the database that you want to migrate on one of the servers, and then, use that server as a designated seeder for the other cluster members to copy that database from.

The following steps assume that you want to migrate the database called mydb to block format but the same steps apply to other formats. The database is hosted on three servers in primary mode.

On one of the servers, server01

  1. In Cypher Shell, put the database that you want to migrate in read-only mode using the Cypher command ALTER DATABASE …​​ SET ACCESS READ ONLY. For example:

    @system> ALTER DATABASE mydb SET ACCESS READ ONLY;

  2. In your command-line tool, back up that database using the neo4j-admin database backup command. For example:

    bin/neo4j-admin database backup mydb --to-path=/path/to/your-backup-folder --include-metadata=all

  3. Back in Cypher Shell, drop the database to delete it and all users and roles associated with it:

    @system> DROP DATABASE mydb;

  4. In the command-line tool, restore the backup that you created using the neo4j-admin database restore command:

    bin/neo4j-admin database restore --from-path=/path/to/your-backup-folder/mydb-2024-03-05T11-26-38.backup mydb

  5. Migrate the restored database to block format:

    bin/neo4j-admin database migrate --to-format="block" mydb

  6. In Cypher Shell, run SHOW SERVERS to find the server ID of server01. Cross-reference the address to find the server ID. Use any database to connect.

    SHOW SERVERS YIELD serverId, name, address, state, health, hosting;

On one of the servers:

  1. Use the system database and create the migrated database mydb using the server ID of server01. The topology of mydb is stored in the system database and when you create it, it is allocated according to the default topology (which can be shown with CALL dbms.showTopologyGraphConfig). For more information, see Designated seeder.

    @system> CREATE DATABASE mydb OPTIONS {existingData: 'use', existingDataSeedInstance: '<server01 id>'};

  2. Verify that the database is created and available using the Cypher command SHOW DATABASE mydb.

  3. After the successful completion, restore the roles and permissions. For more information, see Restore users and roles metadata.

Verify the store format

You can verify the store format of a database using the following Cypher:

SHOW DATABASES YIELD name, store
Result
+----------------------------------+
| name      | store                |
+----------------------------------+
| "blockdb" | "block-block-1.1"    |
| "neo4j"   | "record-aligned-1.1" |
| "system"  | "record-aligned-1.1" |
+----------------------------------+

Additionally, you can use the neo4j-admin database info command to get detailed information about the store format of a database. For details, see Display store information.

Effects of store format choice

The store format is responsible for how data is written to disk and how to read it. Some key aspects that may differ between formats are:

  • The performance and resource consumption of read and write transactions. An operation may be faster on one store format than another.

  • Size of database files on disk. Two databases containing identical logical data may have different sizes due to different formats.

  • Which files/filenames exist in the database directory.

  • Performance in memory-constrained environments. The same query on different formats may have a different page cache hit ratio when the database does not entirely fit in the page cache.

  • The amount of data that can be stored. See Store formats and entity limits for limitations of the individual formats.

  • The order of query results when the order is not specified. Different store formats may traverse and return data in different order.

  • Algorithms used by the Neo4j Admin tools. Especially neo4j-admin database check and neo4j-admin database import commands. Performance and resource utilization may differ.

Store formats and entity limits

The following tables show the format and Neo4j version compatibility and the limits of the different store formats:

Aligned format

Table 1. Aligned format and Neo4j version compatibility
Name Store format version Introduced in Unsupported from

ALIGNED_V5_0 Default

record-aligned-1.1

5.0.0

ALIGNED_V4_3

AF4.3.0

4.3.0

5.0.0

ALIGNED_V4_1

AF4.1.a

4.1.0

5.0.0
Table 2. Aligned format entity limits
Name Limit

Property keys

2^24 (16 777 216)

Nodes

2^35 (34 359 738 368)

Relationships

2^35 (34 359 738 368)

Properties

2^36 (68 719 476 736)

Labels

2^31 (2 147 483 648)

Relationship types

2^16 (65 536)

Relationship groups

2^35 (34 359 738 368)

Standard format

Table 3. Standard format and Neo4j version compatibility
Name Store format version Introduced in Unsupported from

STANDARD_V5_0

record-standard-1.1

5.0.0

STANDARD_V4_3

SF4.3.0

4.3.0

5.0.0

STANDARD_V4_0

SF4.0.0

4.0.0

5.0.0

STANDARD_V3_4

v0.A.9

3.4.0

5.0.0
Table 4. Standard format entity limits
Name Limit

Property keys

2^24 (16 777 216)

Nodes

2^35 (34 359 738 368)

Relationships

2^35 (34 359 738 368)

Properties

2^36 (68 719 476 736)

Labels

2^31 (2 147 483 648)

Relationship types

2^16 (65 536)

Relationship groups

2^35 (34 359 738 368)

High_limit format

Table 5. High_limit format and Neo4j version compatibility
Name Store format version Introduced in Unsupported from

HIGH_LIMIT_V5_0

record-high_limit-1.1

5.0.0

HIGH_LIMIT_V4_3_0

HL4.3.0

4.3.0

5.0.0

HIGH_LIMIT_V4_0_0

HL4.0.0

4.0.0

5.0.0

HIGH_LIMIT_V3_4_0

vE.H.4

3.4.0

5.0.0

HIGH_LIMIT_V3_2_0

vE.H.3

3.2.0

5.0.0

HIGH_LIMIT_V3_1_0

vE.H.2

3.1.0

5.0.0

HIGH_LIMIT_V3_0_6

vE.H.0b

3.0.6

5.0.0

HIGH_LIMIT_V3_0_0

vE.H.0

3.0.0

5.0.0
Table 6. High_limit format entity limits
Name Limit

Property keys

2^24 (16 777 216)

Nodes

2^50 (1 Quadrillion)

Relationships

2^50 (1 Quadrillion)

Properties

2^50 (1 Quadrillion)

Labels

2^31 (2 147 483 648)

Relationship types

2^24 (16 777 216)

Relationship groups

2^50 (1 Quadrillion)

Block format

Table 7. Block format and Neo4j version compatibility
Name Store format version Introduced in GA from

BLOCK_V1

block-block-1.1

5.14.0

5.16.0
Table 8. Block format entity limits
Name Limit

Nodes

2^48 (281 474 976 710 656)

Relationships

∞ (no defined upper bound)

Properties

∞ (no defined upper bound)

Labels

2^31 (2 147 483 648)

Relationship types

2^30 (1 073 741 824)

Property keys

2^31 (2 147 483 648)