diff --git a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc index 97e72a32b..ce26292f1 100644 --- a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc +++ b/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 `` or `.` 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[] diff --git a/modules/ROOT/pages/values-and-types/graph-references.adoc b/modules/ROOT/pages/values-and-types/graph-references.adoc index 6efe8a96e..a679c95f7 100644 --- a/modules/ROOT/pages/values-and-types/graph-references.adoc +++ b/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 `.`, 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()` is typically equivalent to `USE `. +There may be differences if the name contains special characters: + +* Graph references passed as identifiers such as `USE ` 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()` 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()` is typically equivalent to `USE `. -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`. \ No newline at end of file +* `USE `db-with-dash`` +* `USE graph.byName('db-with-dash')` +* `USE graph.byName($param)` with parameter `db-with-dash` \ No newline at end of file