Creating sharded property databases
InfinigraphNot available on AuraIntroduced in 2025.12

You can create a sharded property database using the Cypher command CREATE DATABASE (requires Cypher 25, introduced alongside Neo4j 2025.06.0).

Starting from Neo4j 2026.02, the distributed neo4j.conf explicitly sets db.query.default_language=CYPHER_25. As a result, new deployments using the provided configuration file default to Cypher 25 for newly created databases. If you are using an older version of Neo4j, you need to explicitly set the default Cypher version to Cypher 25 when creating the database or by prefixing your Cypher queries with CYPHER_25 to be able to use the sharding features. For details on configuring the Cypher version, see Configure the Cypher default version.

Syntax

Command Syntax

CREATE DATABASE

 
CREATE DATABASE name [IF NOT EXISTS]
[[SET] DEFAULT LANGUAGE CYPHER {5|25}]
[[SET] GRAPH SHARD {
  [TOPOLOGY n PRIMAR{Y|IES} [m SECONDAR{Y|IES}]]
}]
[SET] PROPERTY SHARD[S] {
  COUNT n [TOPOLOGY m REPLICA[S]]
}
[OPTIONS "{" option: value[, ...] "}"]
[WAIT [n [SEC[OND[S]]]]|NOWAIT]

When creating a sharded property database, the following are created:

  • A virtual sharded property database <name>.

  • A single graph shard with the name <name>-g000.

  • A number of property shards with the name <name>-p<index>, where <index> ranges from 000 to 999. The count property in SET PROPERTY SHARDS specifies the number of property shards.

CREATE OR REPLACE does not replace an existing sharded property database.

Options

The CREATE DATABASE command can have a map of options, e.g., OPTIONS {key: 'value'}. For sharded databases, only the options seedURI, seedConfig, seedSourceDatabase, seedRestoreUntil, and txLogEnrichment are supported. For details see Create databases → Options.

The folder notation for seedURI only works for backups, not dumps.

When specifying each artifact manually the key of the map is the name of the shard, where the graph shard name = databaseName-g000 and the property shards = databaseName-p000 with the last property shard name being databaseName-px where x = numShards -1.

Default numbers for topology

The sharded property databases use the Neo4j cluster topology. Therefore, you need to consider how the following settings will affect the creation of your sharded property database. initial.dbms.default_primaries_count and initial.dbms.default_secondaries_count affect only the graph shard

Configuration setting Default value Valid values Description

initial.dbms.default_primaries_count

1

[1-11]

The initial default number of primaries for the standard databases. Initialized at the first DBMS startup. If the user does not specify the number of primaries in CREATE DATABASE, this value will be used unless overwritten by the dbms.setDefaultAllocationNumbers procedure.

initial.dbms.default_secondaries_count

0

[0-20]

The initial default number of secondaries for the standard databases. Initialized at the first DBMS startup. If the user does not specify the number of secondaries in CREATE DATABASE, this value will be used unless overwritten by the dbms.setDefaultAllocationNumbers procedure.

initial.dbms.default_property_shard_replica_count

1

[1-20]

The initial default number of replicas of property shards. Initialized at the first DBMS startup. If the user does not specify the number replicas of property shards in CREATE DATABASE, this value will be used unless overwritten by the dbms.setDefaultAllocationNumbers procedure.

Creating an empty sharded property database

You can create an empty sharded database using the CREATE DATABASE command. The command allows you to specify the number of property shards and the topology of the graph shard. The following examples show how to create an empty sharded database with different configurations.

Example 1: Create an empty sharded database with the default topology (1 primary, no secondaries, and 1 replica per property shard)

CYPHER 25 CREATE DATABASE `foo-sharded`
PROPERTY SHARDS { COUNT 3 };

Example 2: Create an empty sharded database with a custom topology

CYPHER 25 CREATE DATABASE `foo-sharded`
 SET GRAPH SHARD { TOPOLOGY 1 PRIMARY 0 SECONDARIES }
 SET PROPERTY SHARDS { COUNT 3 TOPOLOGY 1 REPLICAS };

Example 3: Create an empty sharded database with a custom high-availability topology

CYPHER 25 CREATE DATABASE `foo-sharded`
 SET GRAPH SHARD { TOPOLOGY 3 PRIMARY 0 SECONDARIES }
 SET PROPERTY SHARDS { COUNT 3 TOPOLOGY 2 REPLICAS };

Creating a sharded database from a URI (online)

You can create a new sharded property database from an existing sharded property database by seeding it with data from one or more URIs. This is useful when you want to create a new database as a copy of an existing one, when the data is from another source, or when your seed data is spread across multiple locations, or when your seed data is in dump form, not backup form. For more information on how seed from a URI works, see the Create a database from a URI.

The following examples show how to create a sharded property database by seeding data from one or multiple URIs.

Example 1: Create a sharded database by seeding from one URI

When seeding from a single URI (a path to a folder), the DBMS uses metadata to allocate the data to the correct databases. This requires seed data to be in a backup form, and the DBMS will look for foo-sharded-g000.backup, foo-sharded-p001.backup, foo-sharded-p002.backup, and so on at the specified location.

CYPHER 25 CREATE DATABASE `foo-sharded`
PROPERTY SHARDS { COUNT 3 }
OPTIONS { seedURI: “s3://bucket/folder/” };

Example 2: Create a sharded database by seeding data from a backup with a different name

This one is similar to Example 1, but the DBMS looks for other-database-g000, etc.

CYPHER 25 CREATE DATABASE `foo-sharded`
PROPERTY SHARDS { COUNT 3 }
OPTIONS { seedURI: “s3://bucket/folder/”, seedSourceDatabase: “other-database” };

Example 3: Create a sharded database by seeding data from dumps

When seeding from dumps, the URIs need to be keyed by the shard name they should be used to seed, because there is no metadata to indicate which data belongs to which shard. In this example, the shard names will be foo-sharded-g000 and foo-sharded-p000 to foo-sharded-px, where x is the number of property shards -1.

CYPHER 25 CREATE DATABASE `foo-sharded`
PROPERTY SHARDS { COUNT 3 }
OPTIONS { seedUri: {
  `foo-sharded-g000`: "s3://bucket/folder/foo-g000.dump",
  `foo-sharded-p000`: "s3://bucket/folder/foo-p001.dump",
  `foo-sharded-p001`: "s3://bucket/folder/foo-p002.dump",
  `foo-sharded-p002`: "s3://bucket/folder/foo-p003.dump"
 } };

Example 4: Create a sharded database by seeding data that is spread across multiple locations

When seeding from backups stored in multiple locations, you specify different URIs for each shard.

CYPHER 25 CREATE DATABASE `foo-sharded`
PROPERTY SHARDS { COUNT 3 }
OPTIONS {
  seedUri: {
    `foo-sharded-g000`: "s3://bucket/folder1/foo-g000.backup",
    `foo-sharded-p000`: "s3://bucket/folder2/foo-p001.backup",
    `foo-sharded-p001`: "s3://bucket/folder3/foo-p002.backup",
    `foo-sharded-p002`: "s3://bucket/folder4/foo-p003.backup"
  }
 };