Managing database aliases in composite databases
Enterprise EditionNot available on Aura

Both local and remote database aliases can be created as part of a composite database. Starting with Neo4j 2025.04, a database alias can also be set as the default database for a composite database.

Starting with Neo4j 2025.06, a database or remote alias can be assigned a default Cypher version. However, local aliases and aliases in composite databases cannot be assigned a default Cypher version. Local aliases always get the Cypher version of their target database and aliases in composite databases always get the Cypher version of the composite database.

Show database aliases in composite databases

Available database aliases in composite databases can be seen using SHOW ALIASES FOR DATABASE. The name of the composite database a particular database alias appears in the returned composite column.
To run the command, the user must have the GRANT SHOW ALIAS ON DBMS TO role privilege on the composite database. For details, see the The DBMS ALIAS MANAGEMENT privileges.

For general information about the SHOW command, see the Cypher Manual → SHOW.

Query

SHOW ALIASES FOR DATABASE

Result

+--------------------------------------------------------------------------------------------------------------------------------+
| name              | composite | database        | location | url                       | credentials                 | user    |
+--------------------------------------------------------------------------------------------------------------------------------+
| "library.romance" | "library" | "romance-books" | "remote" | "neo4j+s://location:7687" | "STORED NATIVE CREDENTIALS" | "alice" |
| "library.sci-fi"  | "library" | "sci-fi-books"  | "local"  | NULL                      | NULL                        | NULL    |
+--------------------------------------------------------------------------------------------------------------------------------+

For a description of all the returned columns of this command, and for ways in which the SHOW ALIASES FOR DATABASE command can be filtered for aliases, see list aliases for standard databases.

Create database aliases in composite databases

Both local and remote database aliases can be part of a composite database.

The database alias consists of two parts, separated by a dot: the namespace and the alias name.

The namespace must be the name of the composite database.

Query

CREATE ALIAS garden.flowers
FOR DATABASE `perennial-flowers`

Query

CREATE ALIAS garden.trees
FOR DATABASE trees AT 'neo4j+s://location:7687'
USER alice PASSWORD 'password'

When a database alias has been created in a composite database, it will show up in the constituents column provided by the command SHOW DATABASES and in the SHOW ALIASES FOR DATABASE command.

Query

SHOW DATABASE garden YIELD name, type, constituents

Result

+-------------------------------------------------------------+
| name     | type        | constituents                       |
+-------------------------------------------------------------+
| "garden" | "composite" | ["garden.flowers", "garden.trees"] |
+-------------------------------------------------------------+

Query

SHOW ALIASES FOR DATABASE
WHERE composite = 'garden'

Result

+-----------------------------------------------------------------------------------------------------------------------------------+
| name             | composite | database            | location | url                       | credentials                 | user    |
+-----------------------------------------------------------------------------------------------------------------------------------+
| "garden.flowers" | "garden"  | "perennial-flowers" | "local"  | NULL                      | NULL                        | NULL    |
| "garden.trees"   | "garden"  | "trees"             | "remote" | "neo4j+s://location:7687" | "STORED NATIVE CREDENTIALS" | "alice" |
+-----------------------------------------------------------------------------------------------------------------------------------+

Database aliases cannot target a composite database.

Query

CREATE ALIAS yard FOR DATABASE garden

Error message

Failed to create the specified database alias 'yard': Database 'garden' is composite.

From 5.26 onwards, the error message also contains the GQLSTATUS code 42NA6 and the status description error: syntax error or access rule violation - invalid alias target. Aliases are not allowed to target composite databases.

Alter local and remote database aliases in composite databases

Local and remote database aliases belonging to a composite database can be altered using the ALTER ALIAS command. This is the same command that is used for altering aliases that are not part of a composite database.

Query

ALTER ALIAS garden.flowers SET DATABASE PROPERTIES { perennial: true }

Query

ALTER ALIAS garden.trees SET DATABASE TARGET updatedTrees AT 'neo4j+s://location:7687' PROPERTIES { treeVersion: 2 }

The updated properties can then be used in queries with the graph.propertiesByName() function.

The changes for all database aliases will show up in the SHOW ALIASES FOR DATABASE command.

Query

SHOW ALIASES FOR DATABASE YIELD *

Result

+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| name              | composite | database            | location | url                       | credentials                 | user    | driver | defaultLanguage | properties        |
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| "garden.flowers"  | "garden"  | "perennial-flowers" | "local"  | NULL                      | NULL                        | NULL    | NULL   | NULL            | {perennial: TRUE} |
| "garden.trees"    | "garden"  | "updatedtrees"      | "remote" | "neo4j+s://location:7687" | "STORED NATIVE CREDENTIALS" | "alice" | {}     | NULL            | {treeversion: 2}  |
| "library.romance" | "library" | "romance-books"     | "remote" | "neo4j+s://location:7687" | "STORED NATIVE CREDENTIALS" | "alice" | {}     | NULL            | {}                |
| "library.sci-fi"  | "library" | "sci-fi-books"      | "local"  | NULL                      | NULL                        | NULL    | NULL   | NULL            | {}                |
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Delete database aliases in composite databases

To delete an alias in a composite database, use the DROP ALIAS FOR DATABASE command. This is the same command that is used for deleting aliases that are not part of a composite database.

Query

DROP ALIAS garden.flowers FOR DATABASE

When a database alias has been deleted, it will no longer show up in the SHOW ALIASES FOR DATABASE command.

Query

SHOW ALIASES FOR DATABASE

Result

+--------------------------------------------------------------------------------------------------------------------------------+
| name              | composite | database        | location | url                       | credentials                 | user    |
+--------------------------------------------------------------------------------------------------------------------------------+
| "garden.trees"    | "garden"  | "updatedtrees"  | "remote" | "neo4j+s://location:7687" | "STORED NATIVE CREDENTIALS" | "alice" |
| "library.romance" | "library" | "romance-books" | "remote" | "neo4j+s://location:7687" | "STORED NATIVE CREDENTIALS" | "alice" |
| "library.sci-fi"  | "library" | "sci-fi-books"  | "local"  | NULL                      | NULL                        | NULL    |
+--------------------------------------------------------------------------------------------------------------------------------+

Additionally, deleted aliases will no longer appear in the constituents column for the SHOW DATABASE command.

Query

SHOW DATABASE garden YIELD name, type, constituents

Result

+-------------------------------------------+
| name     | type        | constituents     |
+-------------------------------------------+
| "garden" | "composite" | ["garden.trees"] |
+-------------------------------------------+

Database alias names that contain dots

Naming database aliases in composite databases follows the same rule as naming aliases for standard databases. However, when it comes to escaping names using backticks, there are some additional things to consider:

Dots in alias names are ambiguous. They could either be interpreted as part of the name itself, or as the dot that separates a composite namespace from the alias name.

Conflicting names
Introduced in 2025.06

In versions earlier than Neo4j 2025.06, it is possible to create conflicting aliases, such as the constituent alias flowers within the composite database garden as well as the non-composite local alias garden.flowers. Both of these are referred to by the same name, garden.flowers.

Neo4j 2025.06 and later versions ensure that no such conflicts exist and throw an exception when attempting to create a new alias with the same name as an existing alias.

Creating a regular alias with the same name as an existing composite constituent is disallowed. In Cypher 25, the two names are considered the same since the parts are not quoted separately as they would be in Cypher 5.

Query

CYPHER 25 CREATE COMPOSITE DATABASE `garden`
CYPHER 25 CREATE ALIAS `garden.flowers` FOR DATABASE `northwind-graph`
CYPHER 25 CREATE ALIAS `garden.flowers` FOR DATABASE `northwind-graph`

Error message

Failed to create the specified database alias 'garden.flowers': Database name or alias already exists.

The exception has the GQLSTATUS code 42001 - invalid syntax with the cause 42N11 - graph reference already exists.

Creating a regular alias with the same name as an existing composite constituent is disallowed:

Query

CYPHER 5 CREATE COMPOSITE DATABASE `garden`
CYPHER 5 CREATE ALIAS `garden`.`flowers` FOR DATABASE `northwind-graph`
CYPHER 5 CREATE ALIAS `garden.flowers` FOR DATABASE `northwind-graph`

Error message

Failed to create the specified database alias 'garden.flowers': Database name or alias already exists.

The exception has the GQLSTATUS code 42001 - invalid syntax with the cause 42N11 - graph reference already exists.

Creating a composite constituent with the same name as an existing non-composite alias is disallowed. This example scenario is already prevented on the second line; thus, the constituent on the third line cannot be created. The Cypher 25 syntax makes no distinction between the names to clarify that they are considered equivalent.

Query

CYPHER 25 CREATE ALIAS `garden.flowers` FOR DATABASE `northwind-graph`
CYPHER 25 CREATE COMPOSITE DATABASE `garden`
CYPHER 25 CREATE ALIAS `garden.flowers` FOR DATABASE `northwind-graph`

Error message

Cannot create database 'garden' because another database 'garden.flowers' exists with an ambiguous name.

The exception has GQLSTATUS code 42N87 - database or alias with similar name exists.

Query

CYPHER 5 CREATE ALIAS `garden.flowers` FOR DATABASE `northwind-graph`
CYPHER 5 CREATE COMPOSITE DATABASE `garden`
CYPHER 5 CREATE ALIAS `garden`.`flowers` FOR DATABASE `northwind-graph`

Error message

Cannot create database 'garden' because another database 'garden.flowers' exists with an ambiguous name.

The exception has the GQLSTATUS code 42N87 - database or alias with similar name exists.

Cypher 25 specific behaviour
Introduced in 2025.06

Accessing an existing alias with dots

Cypher 25 relies on the guarantee that no conflicting names are allowed in Neo4j 2025.06 and later. The following queries all act on the same alias, regardless of whether that alias is a composite constituent or not. The special quoting of separate name parts that is necessary in Cypher 5 is not permitted in Cypher 25.

Parameters

{
  "name": "my.garden.beautiful.flowers"
}

Query

CYPHER 25 ALTER ALIAS `my.garden.beautiful.flowers` SET DATABASE PROPERTIES { perennial: true }
CYPHER 25 ALTER ALIAS $name SET DATABASE PROPERTIES { perennial: true }
CYPHER 25 USE `my.garden.beautiful.flowers` RETURN 1

Creating a new alias with dots

During CREATE, Cypher 25 splits the given name on each dot, left to right, and checks if a corresponding composite database exists. If no composite database is found, Cypher 25 falls back to creating a regular non-composite alias.

For example:

Query

CYPHER 25 CREATE COMPOSITE DATABASE `my.garden`
CYPHER 25 CREATE ALIAS `my.garden.beautiful.flowers` FOR DATABASE `northwind-graph`

The query attempts to create the following aliases in the given order:

Constituent alias garden.beautiful.flowers within composite database my.
Constituent alias beautiful.flowers within composite database my.garden.
Constituent alias flowers within composite database my.garden.beautiful.
Regular non-composite alias my.garden.beautiful.flowers.

When it finds the composite database my.garden, it creates the constituent alias beautiful.flowers within that composite.

Cypher 5 specific behaviour

Quoting database alias and composite database names

The composite database name and the database alias name need to be quoted individually. Backticks may be added regardless of whether the name contains special characters or not, so it is good practice to always backtick both names, e.g. `composite`.`alias`.

Separating composite database name and alias name with backticks is no longer supported in Cypher 25. See Cypher 25 specific behaviour for details.

The following example creates a database alias named my alias with spaces as a constituent in the composite database named my-composite-database-with-dashes:

Query

CYPHER 5 CREATE ALIAS `my-composite-database-with-dashes`.`my alias with spaces` FOR DATABASE `northwind-graph`;

When not quoted individually, a database alias with the full name my alias with.dots and spaces gets created instead:

Query

CYPHER 5 CREATE ALIAS `my alias with.dots and spaces` FOR DATABASE `northwind-graph`;

Handling multiple dots

Database alias names may also include dots. Though these always need to be quoted in order to avoid ambiguity with the composite database and database alias split character.

Query

CYPHER 5 CREATE ALIAS `my.alias.with.dots` FOR DATABASE `northwind-graph`;

Query

CYPHER 5 CREATE ALIAS `my.composite.database.with.dots`.`my.other.alias.with.dots` FOR DATABASE `northwind-graph`;

Single dots and local database aliases

As of Neo4j 2025.06, this feature is no longer deprecated.

There is a special case for local database aliases with a single dot without any existing composite database. If a composite database some exists, the query below will create a database alias named alias within the composite database some. If no such database exists, however, the same query will instead create a database alias named some.alias:

Query

CYPHER 5 CREATE ALIAS some.alias FOR DATABASE `northwind-graph`;

Handling parameters

When using parameters to specify database alias names, the same rules apply as when using literal strings. However, since parameters cannot be quoted, it is not possible to specify the composite database name and the alias name separately when using parameters. This means that the first dot in the parameter value will always be considered as the separator between the composite database name and the alias name, which can lead to unexpected results if the parameter value contains dots.

Parameters with dots

When using parameters, names cannot be quoted. When the given parameter includes dots, the first dot is considered the divider for the composite database.

Consider the query with parameter:

Parameters

{
  "aliasname": "mySimpleCompositeDatabase.myAlias"
}

Query

CYPHER 5 CREATE ALIAS $aliasname FOR DATABASE `northwind-graph`;

If the composite database mySimpleCompositeDatabase exists, then a database alias myAlias will be created in that composite database. If no such composite database exists, then a database alias mySimpleCompositeDatabase.myAlias will be created.

Parameters with multiple dots

On the contrary, a database alias myAlias cannot be created in composite myCompositeDatabase.withDot using parameters. Consider the same query but with the following parameter:

Parameters

{
  "aliasname": "myCompositeDatabase.withDot.myAlias"
}

Since the first dot will be used as a divider, the command will attempt to create the database alias withdot.myalias in the composite database mycompositedatabase. If mycompositedatabase does not exist, the command will create a database alias with the name mycompositedatabase.withdot.myalias, which is not part of any composite database.

In these cases, it is recommended to avoid parameters and explicitly quote the composite database name and alias name separately to avoid ambiguity.

Avoiding ambiguity when using parameters

Database aliases and similarly named composite databases require further special handling with parameters.

Consider the setup:

Query

CYPHER 5 CREATE COMPOSITE DATABASE foo;
CYPHER 5 CREATE ALIAS `foo.bar` FOR DATABASE `northwind-graph`;

Because the alias foo.bar does not belong to the composite database foo, dropping this alias using a parameter will fail with a chain of errors about a missing alias:

Parameters

{
  "aliasname": "foo.bar"
}

Query

CYPHER 5 DROP ALIAS $aliasname FOR DATABASE;

Error

42N00: Syntax error or access rule violation - graph reference not found. A graph reference with the name `foo.bar` was not found. Verify that the spelling is correct.
42N51: Syntax error or access rule violation - invalid parameter. Invalid parameter $`aliasname`.
42001: Syntax error or access rule violation - invalid syntax

In this example, Neo4j looks for the alias bar within the composite database foo. Since no such alias exists, the operation cannot be completed. If the composite database foo did not exist, the alias foo.bar would be resolved as a standalone alias and could be dropped successfully. In these cases, it is recommended to avoid parameters and explicitly quote the composite database name and alias name separately to avoid ambiguity.

Glossary

allocator: A component in the cluster that allocates databases to servers according to the topology constraints specified and an allocation strategy.
asynchronous replication: Asynchronous replication is used by secondary copies to poll for new transactions, which means they cannot be guaranteed to have received the most recent transactions. This enables efficient scale-out of read-performance.
Aura instance: A fully-managed DBMS represented by a single instance ID, that is running in the Neo4j Aura cloud.
auto-commit transaction: An automatically committed transaction that contains a single query.
Bolt protocol: Bolt is a protocol used for interaction between Neo4j instances and drivers.
bookmark: A marker the client can request from the cluster to ensure that it is able to read its own writes so that the application’s state is consistent and only databases that have a copy of the bookmark are permitted to respond.
category (Bloom): A category is based on a node label and is defined in a Perspective as a way of visually distinguishing nodes with the same label(s).
causal consistency: All servers in a cluster agree on the order in which transactions take place. The position of a server on the causal chain can be guaranteed using a bookmark.
cluster: A Neo4j DBMS that spans multiple servers working together to increase fault tolerance and/or read scalability. Databases on a cluster may be configured to replicate across servers in the cluster thus achieving read scalability or high availability.
client application: Software that interacts with a Neo4j server.
commit: A commit is the successful completion of a transaction, which ensures durability of any changes made. For more details, visit Operations Manual → Transaction management.
composite database: Composite databases are the means to access partitioned graph data with a single Cypher query.
constraint: Constraints are sets of data modeling rules that ensure the data is consistent and reliable.
Cypher®: Neo4j’s graph query language.
data model: A data model defines how information is organized in a database. A good data model will make querying and understanding your data easier. In Neo4j, the data models have a graph structure.
database: A database is a container used by the DBMS to manage and store graph data. The physical structure of data is controlled by the database.
database vs graph: Databases are the physical containers of graph data. Graphs are the logical structure of data in Neo4j.
Database Management System: Database Management System, or DBMS, capable of managing multiple databases. A DBMS may run on a single server, or span several servers configured as a cluster.
database schema: The prescribed property existence and datatypes for nodes and relationships.
deallocate: An act of removing a database from a server or a server from a cluster without loss of data or reduced fault tolerance.
degree (of a node): The number of relationships of a specific node; loops are counted twice.
disaster recovery: A manual intervention to restore availability of a cluster, or databases within a cluster.
driver: A software library that provides access to Neo4j from a particular programming language.
election: In the event that the Raft leader becomes unresponsive, followers automatically trigger an election and vote for a new leader.
entity: A node or a relationship.
expression (Cypher): A component of a Cypher query which produces values. It may be used in projections, as a predicate, or when setting properties on graph elements.
fabric: Fabric is the architectural design of a unified system that provides a single access point to local or distributed graph data.
fault tolerance: A guarantee that a cluster can maintain a database’s persistence and availability in the event of one or more servers failing.
follower: A primary copy of a database acting as a follower, receives and acknowledges synchronous writes from the leader.
Generative AI (GenAI): A type of artificial intelligence (AI) system that generates text, images, or other media in response to prompts.
graph: A logical representation of a set of nodes where some pairs are connected by relationships.
index: Data structure that improves read performance of a database.
knowledge graph: A specific type of graph that has an organizing principle so that a user (or a computer system) can reason about the underlying data. The organizing principle provides an additional layer of structure that adds context to support knowledge discovery.
label: Marks a node as a member of a named and indexed subset. A node may be assigned zero or more labels.
leader: A single primary copy of a database is designated as the leader. It receives all write transactions from clients and replicates writes synchronously to followers and asynchronously to secondary copies of the database.
main database: In terms of Neo4j Enterprise Studio, the database(s) containing the user’s data. Can exist in the same Neo4j deployment as the tool asset database.
motif: A description of a specific pattern within a graph.
node: A node represents an entity or discrete object in your graph data model. Nodes can be connected by relationships, hold data in properties, and are classified by labels.
operator: A symbol representing a mathematical or logical operation.
parameter: Named value provided when running a Cypher statement.
path: A sequence of nodes and the relationships connecting them, that does not contain duplicate relationships. Several paths can match a pattern.
pattern: A specific arrangement of nodes and relationships that can be matched in a graph. A pattern follows a motif.
perspective (Bloom): A Perspective defines a certain business view or domain that can be found in the target Neo4j graph. A single Neo4j graph can be viewed through different Perspectives, each tailored for a different business purpose.
primary: A copy of the database that is able to process write transactions and is eligible to be elected as a leader. It participates in fault tolerant writes as it is part of the majority required to acknowledge and commit write transactions.
primary vs secondary: In a cluster, databases can operate in either primary or secondary mode. Primary databases are able to process write and read transactions, ensuring fault tolerance. Secondary databases are replicated asynchronously from primaries, and their main purpose is to provide read scaling within the cluster.
project (Aura): An isolated environment in the unified Aura console that contains its own database instances, configurations, and resources. Preceded by tenant in the classic Aura console.
property: Properties are key-value pairs that are used for storing data on nodes and relationships.
query (Cypher): A statement that retrieves or writes information to a database.
Raft group: A group of servers that are participating in hosting a particular database in primary mode.
Raft group member: A server that is participating in a Raft group. A server can be a member of one or more groups.
Raft log: A shared log between all Raft group members that is guaranteed to be consistently updated and viewed by those members. The log contains both database data and operational state of the Raft group.
Raft protocol: The networking mechanism that enables a database to replicate its data across multiple servers to give high availability for accessing the data and high durability to the data stored.
read scaling: Distributing query load by creating additional database copies hosted in secondary mode (read-only).
relationship: A relationship represents a connection between nodes in your graph data model. Relationships connect a source node to a target node, hold data in properties, and are classified by type.
secondary: An asynchronously replicated copy of the database that provides read scaling within the cluster.
seed: A seed is a database dump or a full backup used to create a database on a cluster. This is sometimes called seeding.
server: A physical machine, a virtual machine, or a container running an instance of Neo4j. Servers can be standalone or part of a cluster.
session: A causally linked sequence of transactions.
session consistency: An alternative name for Neo4j’s causal consistency.
standalone: A single server running Neo4j and not part of a cluster.
synchronous replication: Synchronous replication requires the leader primary to replicate a transaction and block the commit until a quorum of the follower primaries acknowledges that the transaction is successfully replicated. Once the transaction is replicated, the commit is allowed to proceed. This ensures data durability and consistency within the cluster.
system database: A database used by Neo4j to store system information.
tenant (Aura): An isolated environment in the classic Aura console that contains its own database instances, configurations, and resources. Replaced by project in the unified Aura console.
tool asset database: In terms of Neo4j Enterprise Studio, the database where tools' assets are stored. This can be in the same Neo4j deployment as the main database(s) or in a separate deployment.
topology: A configuration that describes how the copies of a database should be spread across the servers in a cluster, see primary mode and secondary mode.
transaction: A transaction comprises a unit of work performed against a database. It is treated in a coherent and reliable way, independent of other transactions. Transactions comply with the ACID consistency model (atomic, consistent, isolated, and durable).

Managing database aliases in composite databasesEnterprise EditionNot available on Aura

Show database aliases in composite databases

Create database aliases in composite databases

Alter local and remote database aliases in composite databases

Delete database aliases in composite databases

Database alias names that contain dots

Conflicting namesIntroduced in 2025.06

Cypher 25 specific behaviourIntroduced in 2025.06

Accessing an existing alias with dots

Creating a new alias with dots

Cypher 5 specific behaviour

Quoting database alias and composite database names

Handling multiple dots

Single dots and local database aliases

Handling parameters

Parameters with dots

Parameters with multiple dots

Avoiding ambiguity when using parameters

Glossary

Managing database aliases in composite databases
Enterprise EditionNot available on Aura

Conflicting names
Introduced in 2025.06

Cypher 25 specific behaviour
Introduced in 2025.06