From 5fb0c7ed06279c95577804453a02925ec7182db9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nadja=20M=C3=BCller?= Date: Sat, 31 May 2025 16:31:26 +0200 Subject: [PATCH 1/7] update documentation of graph references in Cypher 25 --- .../values-and-types/graph-references.adoc | 24 +++++++++++-------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/modules/ROOT/pages/values-and-types/graph-references.adoc b/modules/ROOT/pages/values-and-types/graph-references.adoc index 6efe8a96e..e31878199 100644 --- a/modules/ROOT/pages/values-and-types/graph-references.adoc +++ b/modules/ROOT/pages/values-and-types/graph-references.adoc @@ -26,13 +26,17 @@ These include: [[rules]] == Rules -The following rules apply for graph references when using identifiers (static graph references, administration commands) or the `graph.byName` functions: - -* 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 +The following rules apply for graph references when using identifiers (static graph references, administration commands) or the `graph.byName` functions. + +`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 or need to be quoted in its entirety, e.g. `USE neo4j` or `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: + +* `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 From fce50a84ff35b28b630837f88ee2a5fa62bde2d0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nadja=20M=C3=BCller?= Date: Thu, 5 Jun 2025 10:19:13 +0200 Subject: [PATCH 2/7] include section about constituent names --- .../ROOT/pages/values-and-types/graph-references.adoc | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/values-and-types/graph-references.adoc b/modules/ROOT/pages/values-and-types/graph-references.adoc index e31878199..c19c81e8d 100644 --- a/modules/ROOT/pages/values-and-types/graph-references.adoc +++ b/modules/ROOT/pages/values-and-types/graph-references.adoc @@ -1,8 +1,12 @@ = 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 administration commands. + +The output of the name column in `SHOW DATABASES` and `SHOW ALIASES FOR DATABASE` can be used as an identifier when referring to a specific 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. While we do not recommend creating databases or aliases containing dots, 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 @@ -32,7 +36,7 @@ The following rules apply for graph references when using identifiers (static gr * 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 or need to be quoted in its entirety, e.g. `USE neo4j` or `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``. +* 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: From eeb9437a667638d1d0a1b21be999ba939a3b1a8b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nadja=20M=C3=BCller?= Date: Thu, 5 Jun 2025 10:33:40 +0200 Subject: [PATCH 3/7] include deprecation update --- ...tions-additions-removals-compatibility.adoc | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc index 97e72a32b..f0834b25e 100644 --- a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc +++ b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc @@ -174,20 +174,14 @@ label:functionality[] label:updated[] [source, cypher, role="noheader"] ---- -USE graph.byName('tom`s-database') - -USE graph.propertiesByName('database.with.dot') +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')++` +| +The graph name ``composite.with.dot`.constituent` is deprecated. It is replaced by ``composite.with.dot`.constituent`. -Note that escaping graph names within the graph functions string argument is not supported in Cypher 5. +In Cypher 5, there was some special logic for composite databases or constituents with dots, +which required quotes around those name parts in order to find the name. This deprecations apply to 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 the graph references can be passed in without quoting +as in the name column from `SHOW ALIASES FOR DATABASE`.Note that escaping graph names within the graph functions string argument is not supported in Cypher 5. a| label:functionality[] From 94aaf6bfd00b766bafcebb827c658f61c9edff05 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nadja=20M=C3=BCller?= Date: Tue, 10 Jun 2025 16:10:42 +0200 Subject: [PATCH 4/7] update updated functionality section for graph functions --- .../deprecations-additions-removals-compatibility.adoc | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc index f0834b25e..cd7cfbadf 100644 --- a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc +++ b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc @@ -174,14 +174,13 @@ label:functionality[] label:updated[] [source, cypher, role="noheader"] ---- -USE graph.propertiesByName('`composite.with.dot`.constituent') +USE graph.byName('composite.with.dot.constituent') +USE graph.propertiesByName('composite.with.dot.constituent') ---- | -The graph name ``composite.with.dot`.constituent` is deprecated. It is replaced by ``composite.with.dot`.constituent`. +In Cypher 25, 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`] now require no syntactic quotes. -In Cypher 5, there was some special logic for composite databases or constituents with dots, -which required quotes around those name parts in order to find the name. This deprecations apply to 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 the graph references can be passed in without quoting -as in the name column from `SHOW ALIASES FOR DATABASE`.Note that escaping graph names within the graph functions string argument is not supported in Cypher 5. +In Cypher 5, there was some special logic for composite databases or constituents with dots, which required quotes around those name parts in order to find the name, e.g. `USE graph.byName('`composite.with.dot`.constituent')`. a| label:functionality[] From efdc42da3261c328b673925afb09676c57032ac1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nadja=20M=C3=BCller?= Date: Tue, 10 Jun 2025 16:52:50 +0200 Subject: [PATCH 5/7] formatting --- .../pages/deprecations-additions-removals-compatibility.adoc | 2 +- modules/ROOT/pages/values-and-types/graph-references.adoc | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc index cd7cfbadf..3429ab1f6 100644 --- a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc +++ b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc @@ -180,7 +180,7 @@ USE graph.propertiesByName('composite.with.dot.constituent') | In Cypher 25, 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`] now require no syntactic quotes. -In Cypher 5, there was some special logic for composite databases or constituents with dots, which required quotes around those name parts in order to find the name, e.g. `USE graph.byName('`composite.with.dot`.constituent')`. +In Cypher 5, there was some special logic for composite databases or constituents with dots, which required quotes around those name parts in order to find the name, 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 c19c81e8d..63d40cd20 100644 --- a/modules/ROOT/pages/values-and-types/graph-references.adoc +++ b/modules/ROOT/pages/values-and-types/graph-references.adoc @@ -36,7 +36,7 @@ The following rules apply for graph references when using identifiers (static gr * 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 or need to be quoted in its entirety, e.g. `USE neo4j` or `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``. +* 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: From 1e407a8960d4d23853452cd235fc27d1b1785e1e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nadja=20M=C3=BCller?= <73830555+nadja-muller@users.noreply.github.com> Date: Mon, 16 Jun 2025 12:08:04 +0200 Subject: [PATCH 6/7] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jens Pryce-Åklundh <112686610+JPryce-Aklundh@users.noreply.github.com> --- ...recations-additions-removals-compatibility.adoc | 2 +- .../pages/values-and-types/graph-references.adoc | 14 ++++++++------ 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc index 3429ab1f6..cb93d5fad 100644 --- a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc +++ b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc @@ -180,7 +180,7 @@ USE graph.propertiesByName('composite.with.dot.constituent') | In Cypher 25, 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`] now require no syntactic quotes. -In Cypher 5, there was some special logic for composite databases or constituents with dots, which required quotes around those name parts in order to find the name, e.g. `USE graph.byName('`composite.with.dot++`.constituent')++`. +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 63d40cd20..a679c95f7 100644 --- a/modules/ROOT/pages/values-and-types/graph-references.adoc +++ b/modules/ROOT/pages/values-and-types/graph-references.adoc @@ -2,11 +2,12 @@ :description: Information about Cypher's graph reference values. 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 administration commands. +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 output of the name column in `SHOW DATABASES` and `SHOW ALIASES FOR DATABASE` can be used as an identifier when referring to a specific graph references. +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. While we do not recommend creating databases or aliases containing dots, it is possible to refer to the alias `some.alias` in the composite `some.composite` as `some.composite.some.alias`. +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 @@ -30,11 +31,12 @@ 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: +`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 or need to be quoted in its entirety, e.g. `USE neo4j` or `USE `db-with-dash``. +* 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++``. From 6dc9af832e30360641dd23cbe2e1b06cbc0493d7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nadja=20M=C3=BCller?= <73830555+nadja-muller@users.noreply.github.com> Date: Mon, 16 Jun 2025 12:14:26 +0200 Subject: [PATCH 7/7] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jens Pryce-Åklundh <112686610+JPryce-Aklundh@users.noreply.github.com> --- .../pages/deprecations-additions-removals-compatibility.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc index cb93d5fad..ce26292f1 100644 --- a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc +++ b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc @@ -178,7 +178,7 @@ USE graph.byName('composite.with.dot.constituent') USE graph.propertiesByName('composite.with.dot.constituent') ---- | -In Cypher 25, 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`] now require no syntactic quotes. +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. 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')++`.