Graph references

Graph references are values used to specify which graph is targeted in a query. They are principally used with the USE clause, graph functions, such as graph.byName(), and when referring to databases and aliases in administration commands.

The name column output from SHOW DATABASES and SHOW ALIASES FOR DATABASE can be used as identifiers for graph references.

When referring to a constituent in a composite database, the identifier is defined as <composite-name>.<alias-name>, where the dot functions as a separator between the composite database name and the alias name. Although creating databases or aliases containing dots is not recommended, it is possible to refer to the alias some.alias in the composite some.composite as some.composite.some.alias.

Static graph references

A static graph reference is a direct reference to a graph in a database. These include:

  • Database and alias names when managing databases and aliases: CREATE DATABASE <symbolic-name>.

  • Database and alias names when selecting a graph with the USE clause: USE <symbolic-name> or USE <symbolic-name>.<symbolic-name> (for constituents of a composite databases).

Dynamic graph references

A dynamic graph reference is a reference to a graph using values that are evaluated during query execution using a function. These include:

  • Dynamic graph reference with the graph.byName() function, to access a graph of a given name: USE graph.byName(<string-expression>).

  • Dynamic graph references with the graph.byElementId() function, to access a graph of a given node or relationship: USE graph.byElementId(<element-id-string>).

  • Retrieving properties of a graph with the graph.propertiesByName() function: graph.propertiesByName(<string-expression>).

Rules

The following rules apply for graph references when using identifiers (static graph references, administration commands) or the graph.byName function.

USE graph.byName(<graph-reference>) is typically equivalent to USE <graph-reference>. There may be differences if the name contains special characters:

  • Graph references passed as identifiers such as USE <graph-reference> apply the escaping rules of symbolic names. Graph names can either be unquoted (e.g. ,USE neo4j) or need to be quoted in its entirety (e.g., USE `db-with-dash`).

  • Graph references passed as graph functions such as USE graph.byName(<graph-reference>) apply the escaping rules of string literals. Note that quotes are considered as part of the name, e.g. USE graph.byName('`db-with-dash`') would try to resolve the graph reference `db-with-dash`.

For example, the graph reference db-with-dash can be passed as:

  • USE `db-with-dash`

  • USE graph.byName('db-with-dash')

  • USE graph.byName($param) with parameter db-with-dash