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 supports only the options seedURI, seedConfig, seedSourceDatabase, seedRestoreUntil, and txLogEnrichment when creating a sharded property database.

When using with seedURI, you can specify the seed URI in different ways, depending on how your seed data is organized and where it is stored:

  • A path to folder containing a data seed, e.g., OPTIONS {seedURI: "s3://bucket/folder/"}, where the folder contains the backup for each shard. The folder notation only works for backups, not dumps, because the DBMS relies on the metadata in the backup files to allocate the data to the correct databases.

  • A map of shard names to data seed URIs, e.g., OPTIONS {key: 'value'}. Because the DBMS relies on the provided key-value pairs to allocate the data to the correct databases, the seed data can be in either backup or dump format.

  • Introduced in 2026.04 A list of server URIs, e.g., OPTIONS {seedURI: ["server://server0/seeds/", "server://server1/seeds/"]}. This allows seed data to be distributed across multiple servers, which is useful when the data cannot fit on a single server or is already stored across several locations. Does not support dumps, use URI map approach instead.

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.

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 };
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 };
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 property database from a URI (online)

You can create a 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 sharded property database as a copy of an existing database, for example, for testing or staging purposes, or your seed data is from another source, for example, a backup with a different name, or when your seed data is in a dump format, or already stored across several locations.

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 URI, multiple URIs, and multiple server URIs.

Create a sharded property database by seeding from a single URI

Create a sharded property database by seeding from a single URI, which is a path to a folder containing the backup files for each shard. This approach relies on the metadata in the backup files to allocate the data to the correct databases. Therefore, the seed data must be in backup format, and the DBMS looks for foo-sharded-g000.backup, foo-sharded-p001.backup, foo-sharded-p002.backup, and so on at the specified location.

Create a sharded database by seeding from single URI, which is a folder containing the backup files for each shard
CYPHER 25 CREATE DATABASE `foo-sharded`
PROPERTY SHARDS { COUNT 3 }
OPTIONS { seedURI: “s3://bucket/folder/” };
Create a sharded database by seeding data from a backup with a different name
CYPHER 25 CREATE DATABASE `foo-sharded`
PROPERTY SHARDS { COUNT 3 }
OPTIONS { seedURI: “s3://bucket/folder/”, seedSourceDatabase: “other-database” };

Create a sharded property database by seeding from multiple URIs

When seeding from multiple URIs, you specify different URIs for each shard, by using a map where the key is the shard name and the value is the URI where the seed for that shard can be found. The DBMS looks for the seeds at the specified locations for each shard, and all seeds can be in the same location or spread across multiple locations. Because the DBMS relies on the provided key-value pairs to allocate the data to the correct databases, the seed data can be in either backup or dump format.

Create a sharded database by seeding data from dumps
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"
 } };
Create a sharded database by seeding data that is spread across multiple locations
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"
  }
 };

Seeding from multiple server URIs
Introduced in 2026.04

You can specify multiple server URIs as a list in the seedUri options when creating a sharded property database. This allows seed data to be distributed across multiple servers, which is useful when the data cannot fit on a single server or is already stored across several locations. For each shard, the DBMS selects a suitable seed from the provided URIs. Only one URI is expected to contain the required artefact for a given seed. When using a backup chain to create a database, all backups in the same chain must be located within a single directory, i.e., the backup chain for foo-p000 cannot be spread across server-0 and server-1. There can only be one backup chain per-shard existing across the directories. This approach also does not support specifying artefact names, for example,[“server://server-0/seeds/foo-g000.backup”,“server://server-2/seeds/foo-p000.backup”], or mixing URI formats, for example, [“server://server-0/seeds/”,“s3://bucket/folder/”]. Dumps are not supported, use URI map approach instead.

Create a sharded database by seeding data from multiple server URIs
CYPHER 25 CREATE DATABASE `foo-sharded`
SET GRAPH SHARD { TOPOLOGY 1 PRIMARIES 0 SECONDARIES }
SET PROPERTY SHARDS { COUNT 2 TOPOLOGY 1 REPLICA }
OPTIONS {
  seedUri: ["server://server0/seeds/", "server://server1/seeds/"] };
Create a sharded database without specifying server URIs
CREATE DATABASE spd
SET GRAPH SHARD { TOPOLOGY 1 PRIMARIES 0 SECONDARIES }
SET PROPERTY SHARDS { COUNT 2 TOPOLOGY 1 REPLICA }
OPTIONS { seedUri: [] }

In this case, the DBMS looks for seeds on all known servers in the cluster.