graph references in Cypher 25

modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc

@@ -174,20 +174,13 @@ label:functionality[]
 label:updated[]
 [source, cypher, role="noheader"]
 ----
-USE graph.byName('tom`s-database')
-
-USE graph.propertiesByName('database.with.dot')
+USE graph.byName('composite.with.dot.constituent')
+USE graph.propertiesByName('composite.with.dot.constituent')
 ----
-|  xref::values-and-types/graph-references.adoc[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')++`
+|
+xref::values-and-types/graph-references.adoc[Graph references] in the arguments of the functions xref:functions/graph.adoc#functions-graph-byname[`graph.byName`] and xref:functions/graph.adoc#functions-graph-propertiesByName[`graph.propertiesByName`] now require no syntactic quotes.
 
-Note that escaping graph names within the graph functions string argument is not supported in Cypher 5.
+In Cypher 5, if a composite database or constituent name contains dots, those name parts have to be wrapped in quotes to resolve the name correctly,  e.g., `USE graph.byName('`composite.with.dot++`.constituent')++`.
 
 a|
 label:functionality[]

modules/ROOT/pages/values-and-types/graph-references.adoc

@@ -1,8 +1,13 @@
 = Graph references
 :description: Information about Cypher's graph reference values.
 
-Graph references are values used to specify which graph to operate on in a query.
-They are principally used with the xref:clauses/use.adoc[`USE`] clause and xref:functions/graph.adoc[graph functions], such as `graph.byName()`.
+Graph references are values used to specify which graph is targeted in a query.
+They are principally used with the xref:clauses/use.adoc[`USE`] clause, xref:functions/graph.adoc[graph functions], such as `graph.byName()`, and when referring to databases and aliases in link:{neo4j-docs-base-uri}/operations-manual/current/database-administration/[administration commands].
+
+The `name` column output from link:{neo4j-docs-base-uri}/operations-manual/current/database-administration/standard-databases/listing-databases/#_show_databases_output[`SHOW DATABASES`] and link:{neo4j-docs-base-uri}/operations-manual/current/database-administration/aliases/manage-aliases-composite-databases/#manage-aliases-composite-databases-list[`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]]
 == Static graph references
@@ -26,13 +31,18 @@ These include:
 [[rules]]
 == Rules
 
-The following rules apply for graph references when using identifiers (static graph references, administration commands) or the `graph.byName` functions:
+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 xref::syntax/naming.adoc#symbolic-names-escaping-rules[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 xref:values-and-types/boolean-numeric-string.adoc#string-literal-escape-sequences[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:
 
-* 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 xref:values-and-types/boolean-numeric-string.adoc#string-literal-escape-sequences[escaping rules] (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`.
+* `USE `db-with-dash``
+* `USE graph.byName('db-with-dash')`
+* `USE graph.byName($param)` with parameter `db-with-dash`