USE

The USE clause determines which graph a query, or query part, is executed against. It is supported for queries and schema commands.

Syntax

The USE clause can only appear as the prefix of schema commands, or as the first clause of queries:

USE <graph>
<other clauses>

Where <graph> refers to the name or alias of a database in the DBMS.

Composite database syntax

When running queries against a composite database, the USE clause can also appear as the first clause of:

  • Union parts:

    USE <graph>
    <other clauses>
      UNION
    USE <graph>
    <other clauses>
  • Subqueries:

    CALL () {
      USE <graph>
      <other clauses>
    }

    In subqueries, a USE clause may appear directly following the variable scope clause: CALL () { …​ } (introduced in Neo4j 5.23). Or, if you are using an older version of Neo4j, directly following an importing WITH clause.

When executing queries against a composite database, the USE clause must only refer to graphs that are part of the current composite database.

Examples

Query a graph

In this example it is assumed that the DBMS contains a database named myDatabase:

Query
USE myDatabase
MATCH (n) RETURN n

Query a composite database constituent graph

In this example it is assumed that the DBMS contains a composite database named myComposite, which includes an alias named myConstituent:

Query
USE myComposite.myConstituent
MATCH (n) RETURN n

Query a composite database constituent graph dynamically

The graph.byName() function can be used in the USE clause to resolve a constituent graph from a STRING value containing the qualified name of a constituent.

This example uses a composite database named myComposite that includes an alias named myConstituent:

Query
USE graph.byName('myComposite.myConstituent')
MATCH (n) RETURN n

The argument can be any expression that evaluates to the name of a constituent graph - for example a parameter:

Query
USE graph.byName($graphName)
MATCH (n) RETURN n

Query a composite database constituent using elementId

The graph.byElementId() function can be used in the USE clause to resolve a constituent graph to which a given element id belongs. As of Neo4j 5.26, it is supported on both standard and composite databases (on previous versions it is only available on composite databases).

On a standard database, a USE clause with graph.byElementId() cannot be combined with other USE clauses unless the subsequent USE clauses reference the same element id.

In the below example, it is assumed that the DBMS contains the database corresponding to the given element id. If you are connected to a composite database it needs to be a element id to a constituent database, which is a standard database in the DBMS.

Query
USE graph.byElementId("4:c0a65d96-4993-4b0c-b036-e7ebd9174905:0")
MATCH (n) RETURN n