add graph reference section to expressions

Author: nadja-muller

modules/ROOT/pages/clauses/use.adoc

@@ -10,22 +10,39 @@ It is supported for queries and schema commands.
 [[query-use-syntax]]
 == Syntax
 
-The `USE` clause can only appear as the prefix of schema commands, or as the first clause of queries:
-
 [source, syntax, role="noheader"]
 ----
-USE <graph>
+USE <graph reference>
 <other clauses>
 ----
 
-Where `<graph>` refers to the name or alias of a database in the DBMS.
+A graph reference can be described using:
+
+* direct graph references: `USE db1`
+* the graph function xref:functions/graph.adoc#functions-graph-by-elementid[`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 xref:functions/graph.adoc#functions-graph-byname[`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 xref::queries/expressions.adoc#graphreferences[here].
 
-[[query-use-syntax-composite]]
-=== Composite database syntax
+== USE clause when connected to a standard or system database
+=== Allowed graph reference targets
 
-When running queries against a link:{neo4j-docs-base-uri}/operations-manual/current/database-administration/composite-databases/concepts/[composite database], the `USE` clause can also appear as the first clause of:
+All databases except composite databases can be targeted. It is not possible to target more than one database. This is only possible when 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
+=== Allowed graph reference targets
+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 link:{neo4j-docs-base-uri}/operations-manual/current/database-administration/composite-databases/concepts/[composite database], the `USE` clause can appear as the first clause of:
+
+* a query (as when connected to a non-composite database)
 * Union parts:
 +
 [source, syntax, role="noheader"]
@@ -49,8 +66,6 @@ CALL () {
 +
 In subqueries, a `USE` clause may appear directly following the xref:subqueries/call-subquery.adoc#variable-scope-clause[variable scope clause]: `CALL () { ... }`.
 
-When executing queries against a composite database, the `USE` clause must only refer to graphs that are part of the current composite database.
-
 
 [[query-use-examples]]
 == Examples
@@ -118,9 +133,6 @@ MATCH (n) RETURN n
 
 The xref:functions/graph.adoc#functions-graph-by-elementid[`graph.byElementId()`] function can be used in the `USE` clause to resolve a constituent graph to which a given xref:functions/scalar.adoc#functions-elementid[element id] belongs.
 
-[NOTE]
-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

modules/ROOT/pages/queries/expressions.adoc

@@ -82,3 +82,21 @@ String literals can contain the following escape sequences:
 * A predicate expression (i.e. an expression returning a `BOOLEAN` value): `a.prop = 'Hello'`, `length(p) > 10`, `a.name IS NOT NULL`.
 * Label and relationship type expressions: `(n:A|B)`, `+()-[r:R1|R2]->()+`.
 * `null`.
+
+[[graphreferences]]
+== Graph references
+* static graph references: `USE <symbolic-name>` (for standard and system databases), `USE <symbolic-name>.<symbolic-name>` (for composite databases)
+* dynamic graph reference with the xref:functions/graph.adoc#functions-graph-byname[`graph.byName`] function, to access a graph of a given name: `USE graph.byName(<string-expression>)`
+* dynamic graph reference with the xref:functions/graph.adoc#functions-graph-by-elementid[`graph.byElementId`] function, to access a graph of a given node or relationship: `USE graph.byName(<element-id-string>)`
+
+Rules on string expressions for graph references when using identifiers (static graph references, administration commands) or a string (graph.byName function):
+
+* Unquoted dots are separators between a composite database and its constituent. For example, `composite.db1` represents the constituent composite.db1 in the composite database composite. To refer to a database with a dot in its name, quote the graph reference instead: `+`composite.db1`+`
+* When resolving a graph reference within a graph function, the string argument is parsed the same as a static graph reference before resolving it. This means that for most arguments, `USE graph.byName(<graph-reference>)` is equal to `USE <graph-reference>`. However, escaping rules for xref::syntax/naming.adoc#symbolic-names-escaping-rules[symbolic names] are applied to the argument. When passing in a string literal, this means both the escaping rules for xref:queries/expressions.adoc#expressions-string-literals[string literals] (when parsing the query) as well as the escaping rules for xref::syntax/naming.adoc#symbolic-names-escaping-rules[symbolic names] (when evaluating the graph reference) are applied. For example, the graph reference in `USE graph.byName('+composite.1\\u0041+')` will resolve to the constituent `composite.1a` of the composite database `composite`.
+
+Graph references are used within:
+
+* xref:clauses/use.adoc[`USE clauses`]
+* database and alias names when managing databases and aliases, see link:{neo4j-docs-base-uri}/operations-manual/current/database-administration/[Database administration]
+
+