USE

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

Syntax

USE <graph reference>
<other clauses>

A graph reference can be described using:

Direct graph references: USE db1.
The graph function graph.byElementId(), to access a graph of a given element: USE graph.byName(<element-id-string>).

When connected to a composite database, a graph reference may additionally be passed with:

The graph function graph.byName(), which allows the graph reference to be resolved dynamically: USE graph.byName(<string-expression>).

A more detailed description of how and when a graph references needs to be quoted and/or escaped is defined here.

USE clause when connected to a standard or system database

All databases and aliases are valid graph reference targets except composite databases and their constituents. Targeting multiple databases is not allowed, unless connected to a composite database.

Position of use clauses

When connected to a non-composite database, the USE clause can only appear as the prefix of schema commands, or as the first clause of queries. There may be multiple USE clauses as long as they target the same database.

USE clause when connected to a composite database

When executing queries against a composite database, the USE clause must only refer to graphs that are part of the current composite database. The constituents can be listed either with RETURN graph.names() when connected to the composite database or SHOW DATABASES YIELD name, constituents RETURN *.

Position of use clauses

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

A query (similar to how it is used when connected to a non-composite database).

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 () { … }.

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.

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