add graph reference section to expressions (#1162)

* adds section about graph references to expressions
* attempt to split behavior of use clauses in the docs depending on
which database you're connected to

---------

Co-authored-by: Jens Pryce-Åklundh <[email protected]>

Author: nadja-muller

modules/ROOT/pages/clauses/use.adoc

@@ -10,22 +10,38 @@ 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
 
-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 and aliases are valid graph reference targets except link:operations-manual/current/database-administration/aliases/manage-aliases-composite-databases/[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 link:{neo4j-docs-base-uri}/operations-manual/current/database-administration/composite-databases/concepts/[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:
 +
 [source, syntax, role="noheader"]
@@ -49,8 +65,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 +132,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/deprecations-additions-removals-compatibility.adoc

@@ -152,6 +152,27 @@ Several  xref:clauses/transaction-clauses.adoc#query-listing-transactions[`SHOW
 * `startTime` and `currentQueryStartTime` now return a `ZONED DATETIME` instead of a `STRING` representation of a temporal value.
 * `clientAddress` and `outerTransactionId` now return `null` instead of an empty `STRING` when unavailable.
 * The current query-related columns — `currentQuery`, `currentQueryId`, `parameters`, `planner`, `runtime`, `indexes`, `currentQueryStartTime`, `currentQueryElapsedTime`, `currentQueryCpuTime`, `currentQueryIdleTime`, and `currentQueryStatus` — now return `null` when no query is executing.
+
+a|
+label:functionality[]
+label:updated[]
+[source, cypher, role="noheader"]
+----
+USE graph.byName('tom`s-database')
+
+USE graph.propertiesByName('database.with.dot')
+----
+|  xref::queries/expressions.adoc#graphreferences[Graph references] in arguments of the functions xref:functions/graph.adoc#functions-graph-byname[`graph.byName`] and xref:functions/graph.adoc#functions-graph-propertiesByName[`graph.propertiesByName`] in Cypher 25 are parsed as `<symbolic-name>` or `<symbolic-name>.<symbolic-name>` and now support escaping names.
+For more information, see xref:syntax/expressions.adoc#graph-references[Cypher expressions -> Graph references.
+Graph name parts that contain unsupported characters for unescaped symbolic names now require backtick quoting.
+Graph name parts with special characters may require additional escaping of those characters:
+
+* `++USE graph.byName('`tom``s-database`')++`
+
+* `++USE graph.propertiesByName('database.with.dot')++`
+
+Note that escaping graph names within the graph functions string argument is not supported in Cypher 5.
+
 |===
 
 === New features

modules/ROOT/pages/queries/expressions.adoc

@@ -82,3 +82,25 @@ 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`.
+
+[[graph-references]]
+== Graph references
+* Database and alias names when managing link:{neo4j-docs-base-uri}/operations-manual/current/database-administration/[databases and aliases]: `CREATE DATABASE <symbolic-name>`.
+* Static graph references: `USE <symbolic-name>` or `USE <symbolic-name>.<symbolic-name>` (for constituents of a link:{neo4j-docs-base-uri}/operations-manual/current/database-administration/composite-databases/concepts/[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 references 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>)`.
+* Retrieving properties of a graph with the xref:functions/graph.adoc#functions-graph-propertiesByName[`graph.propertiesByName`] function: `graph.propertiesByName(<string-expression>)`.
+
+
+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 like a static graph reference.
+ Thus, `USE graph.byName(<graph-reference>)` is typically equivalent to `USE <graph-reference>`.
+ However, escaping rules for xref::syntax/naming.adoc#symbolic-names-escaping-rules[symbolic names] are applied to the argument.
+ For string literals, both the escaping rules for xref:queries/expressions.adoc#expressions-string-literals[string literals] (during query parsing) and xref::syntax/naming.adoc#symbolic-names-escaping-rules[symbolic names] (during graph reference evaluation) are applied.
+For example, the graph reference in `USE graph.byName('+composite.1\\u0041+')` resolves to the constituent `composite.1a` of the composite database `composite`.
+
+