From 524f4db22cb7e4a087877852d01ce8a410b1ecaa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nadja=20M=C3=BCller?= Date: Tue, 14 Jan 2025 13:09:05 +0100 Subject: [PATCH 1/8] add graph reference section to expressions --- modules/ROOT/pages/clauses/use.adoc | 36 ++++++++++++++------- modules/ROOT/pages/queries/expressions.adoc | 18 +++++++++++ 2 files changed, 42 insertions(+), 12 deletions(-) diff --git a/modules/ROOT/pages/clauses/use.adoc b/modules/ROOT/pages/clauses/use.adoc index 3a75add21..27a8c669e 100644 --- a/modules/ROOT/pages/clauses/use.adoc +++ b/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 +USE ---- -Where `` 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()` + +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()` +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 diff --git a/modules/ROOT/pages/queries/expressions.adoc b/modules/ROOT/pages/queries/expressions.adoc index 7f73fb3cb..cf0ab3b55 100644 --- a/modules/ROOT/pages/queries/expressions.adoc +++ b/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 ` (for standard and system databases), `USE .` (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()` +* 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()` + +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()` is equal to `USE `. 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] + + From 81a695c1253dbb946b89dcaf443a269f1cc3273e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nadja=20M=C3=BCller?= <73830555+nadja-muller@users.noreply.github.com> Date: Thu, 16 Jan 2025 14:58:18 +0100 Subject: [PATCH 2/8] 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> --- modules/ROOT/pages/clauses/use.adoc | 17 ++++++++--------- modules/ROOT/pages/queries/expressions.adoc | 14 +++++++++----- 2 files changed, 17 insertions(+), 14 deletions(-) diff --git a/modules/ROOT/pages/clauses/use.adoc b/modules/ROOT/pages/clauses/use.adoc index 27a8c669e..469351d15 100644 --- a/modules/ROOT/pages/clauses/use.adoc +++ b/modules/ROOT/pages/clauses/use.adoc @@ -18,31 +18,30 @@ USE 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()` +* 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()`. 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()` +* The graph function xref:functions/graph.adoc#functions-graph-byname[`graph.byName()`], which allows the graph reference to be resolved dynamically: `USE graph.byName()`. 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]. == USE clause when connected to a standard or system database -=== Allowed graph reference targets -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. +All databases are valid graph reference targets except composite databases. +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 -=== 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 *`. +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 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: +When running queries against a composite database, the `USE` clause can appear as the first clause of: -* a query (as when connected to a non-composite database) +* A query (similar to how it is used when connected to a non-composite database). * Union parts: + [source, syntax, role="noheader"] diff --git a/modules/ROOT/pages/queries/expressions.adoc b/modules/ROOT/pages/queries/expressions.adoc index cf0ab3b55..9cdf20a76 100644 --- a/modules/ROOT/pages/queries/expressions.adoc +++ b/modules/ROOT/pages/queries/expressions.adoc @@ -85,18 +85,22 @@ String literals can contain the following escape sequences: [[graphreferences]] == Graph references -* static graph references: `USE ` (for standard and system databases), `USE .` (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()` -* 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()` +* Static graph references: `USE ` (for link:{neo4j-docs-base-uri}/operations-manual/current/database-administration/[standard and system databases]), `USE .` (for 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()`. +* 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()`. 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()` is equal to `USE `. 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`. +* 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 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`. 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] +* Database and alias names when managing link:{neo4j-docs-base-uri}/operations-manual/current/database-administration/[databases and aliases]. From c7dc2e00a9de3972adec7f3d0f89432124900483 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nadja=20M=C3=BCller?= <73830555+nadja-muller@users.noreply.github.com> Date: Thu, 16 Jan 2025 14:59:18 +0100 Subject: [PATCH 3/8] Update modules/ROOT/pages/queries/expressions.adoc 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> --- modules/ROOT/pages/queries/expressions.adoc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/queries/expressions.adoc b/modules/ROOT/pages/queries/expressions.adoc index 9cdf20a76..5810b321d 100644 --- a/modules/ROOT/pages/queries/expressions.adoc +++ b/modules/ROOT/pages/queries/expressions.adoc @@ -91,7 +91,9 @@ String literals can contain the following escape sequences: 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`+` +* 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. From aab9b59361b2fd0d7d536019dd5dc532e1d28c92 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nadja=20M=C3=BCller?= Date: Thu, 16 Jan 2025 17:35:29 +0100 Subject: [PATCH 4/8] merge lists --- modules/ROOT/pages/queries/expressions.adoc | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/pages/queries/expressions.adoc b/modules/ROOT/pages/queries/expressions.adoc index 5810b321d..6d2a6516b 100644 --- a/modules/ROOT/pages/queries/expressions.adoc +++ b/modules/ROOT/pages/queries/expressions.adoc @@ -85,9 +85,12 @@ String literals can contain the following escape sequences: [[graphreferences]] == Graph references +* Database and alias names when managing link:{neo4j-docs-base-uri}/operations-manual/current/database-administration/[databases and aliases]: `CREATE DATABASE ` * Static graph references: `USE ` (for link:{neo4j-docs-base-uri}/operations-manual/current/database-administration/[standard and system databases]), `USE .` (for 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()`. * 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()`. +* Retrieving properties of a graph with the xref:functions/graph.adoc#functions-graph-propertiesByName[`graph.propertiesByName`] function: `graph.propertiesByName()` + Rules on string expressions for graph references when using identifiers (static graph references, administration commands) or a string (graph.byName function): @@ -100,9 +103,4 @@ To refer to a database with a dot (`.`) in its name, quote the graph reference i 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`. -Graph references are used within: - -* xref:clauses/use.adoc[`USE clauses`] -* Database and alias names when managing link:{neo4j-docs-base-uri}/operations-manual/current/database-administration/[databases and aliases]. - From c3da91147a75fe57fafa207e7019568c1ee999aa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nadja=20M=C3=BCller?= Date: Thu, 16 Jan 2025 17:41:01 +0100 Subject: [PATCH 5/8] add deprecation for graph function string arguments --- ...ions-additions-removals-compatibility.adoc | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc index 309887365..bf7ecdf1e 100644 --- a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc +++ b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc @@ -152,6 +152,25 @@ 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:deprecated[] +[source, cypher, role="noheader"] +---- +USE graph.byName('tom`s-database') +USE graph.propertiesByName('database.with.dot') +---- +| The xref::queries/expressions.adoc#graphreferences[graph references] expressed in arguments of the functions xref:functions/graph.adoc#functions-graph-byname[`graph.byName`] and xref:functions/graph.adoc#functions-graph-propertiesByName[`graph.propertiesByName`] are parsed as static references in Cypher 25. +Graph name parts that contain unsupported characters for unescaped identifiers require backtick escaping. +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 From 2bccaa45c57b5c2fa94e345f336c3baef26bc84d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nadja=20M=C3=BCller?= Date: Thu, 16 Jan 2025 17:43:40 +0100 Subject: [PATCH 6/8] formatting --- .../pages/deprecations-additions-removals-compatibility.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc index bf7ecdf1e..8bf09e67f 100644 --- a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc +++ b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc @@ -159,6 +159,7 @@ label:deprecated[] [source, cypher, role="noheader"] ---- USE graph.byName('tom`s-database') + USE graph.propertiesByName('database.with.dot') ---- | The xref::queries/expressions.adoc#graphreferences[graph references] expressed in arguments of the functions xref:functions/graph.adoc#functions-graph-byname[`graph.byName`] and xref:functions/graph.adoc#functions-graph-propertiesByName[`graph.propertiesByName`] are parsed as static references in Cypher 25. From bef6e03c074ee33d284081b080015ed48380b533 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nadja=20M=C3=BCller?= Date: Fri, 17 Jan 2025 10:38:30 +0100 Subject: [PATCH 7/8] fixing wrong/improving descriptions --- modules/ROOT/pages/clauses/use.adoc | 2 +- .../pages/deprecations-additions-removals-compatibility.adoc | 4 ++-- modules/ROOT/pages/queries/expressions.adoc | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/pages/clauses/use.adoc b/modules/ROOT/pages/clauses/use.adoc index 469351d15..8649532d9 100644 --- a/modules/ROOT/pages/clauses/use.adoc +++ b/modules/ROOT/pages/clauses/use.adoc @@ -29,7 +29,7 @@ A more detailed description of how and when a graph references needs to be quote == USE clause when connected to a standard or system database -All databases are valid graph reference targets except composite databases. +All databases and aliases are valid graph reference targets except composite databases and their constituents. Targeting multiple databases is not allowed, unless connected to a composite database. === Position of use clauses diff --git a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc index 8bf09e67f..dac8b5a4a 100644 --- a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc +++ b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc @@ -162,8 +162,8 @@ USE graph.byName('tom`s-database') USE graph.propertiesByName('database.with.dot') ---- -| The xref::queries/expressions.adoc#graphreferences[graph references] expressed in arguments of the functions xref:functions/graph.adoc#functions-graph-byname[`graph.byName`] and xref:functions/graph.adoc#functions-graph-propertiesByName[`graph.propertiesByName`] are parsed as static references in Cypher 25. -Graph name parts that contain unsupported characters for unescaped identifiers require backtick escaping. +| 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 or . and now support escaping names. +Graph name parts that contain unsupported characters for unescaped symbolic names now require backtick escaping. Graph name parts with special characters may require additional escaping of those characters: * `++USE graph.byName('`tom``s-database`')++` diff --git a/modules/ROOT/pages/queries/expressions.adoc b/modules/ROOT/pages/queries/expressions.adoc index 6d2a6516b..77b6936d2 100644 --- a/modules/ROOT/pages/queries/expressions.adoc +++ b/modules/ROOT/pages/queries/expressions.adoc @@ -86,7 +86,7 @@ String literals can contain the following escape sequences: [[graphreferences]] == Graph references * Database and alias names when managing link:{neo4j-docs-base-uri}/operations-manual/current/database-administration/[databases and aliases]: `CREATE DATABASE ` -* Static graph references: `USE ` (for link:{neo4j-docs-base-uri}/operations-manual/current/database-administration/[standard and system databases]), `USE .` (for link:{neo4j-docs-base-uri}/operations-manual/current/database-administration/composite-databases/concepts/[composite databases]). +* Static graph references: `USE ` or `USE .` (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()`. * 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()`. * Retrieving properties of a graph with the xref:functions/graph.adoc#functions-graph-propertiesByName[`graph.propertiesByName`] function: `graph.propertiesByName()` @@ -97,7 +97,7 @@ Rules on string expressions for graph references when using identifiers (static * 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. +* 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 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. From ef6af69c6a16e12244c585d815ace5f0b93a070d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nadja=20M=C3=BCller?= <73830555+nadja-muller@users.noreply.github.com> Date: Mon, 20 Jan 2025 15:07:42 +0100 Subject: [PATCH 8/8] 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> --- modules/ROOT/pages/clauses/use.adoc | 2 +- .../deprecations-additions-removals-compatibility.adoc | 7 ++++--- modules/ROOT/pages/queries/expressions.adoc | 6 +++--- 3 files changed, 8 insertions(+), 7 deletions(-) diff --git a/modules/ROOT/pages/clauses/use.adoc b/modules/ROOT/pages/clauses/use.adoc index 8649532d9..70beae342 100644 --- a/modules/ROOT/pages/clauses/use.adoc +++ b/modules/ROOT/pages/clauses/use.adoc @@ -29,7 +29,7 @@ A more detailed description of how and when a graph references needs to be quote == USE clause when connected to a standard or system database -All databases and aliases are valid graph reference targets except composite databases and their constituents. +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 diff --git a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc index dac8b5a4a..b57d87d75 100644 --- a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc +++ b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc @@ -155,15 +155,16 @@ Several xref:clauses/transaction-clauses.adoc#query-listing-transactions[`SHOW a| label:functionality[] -label:deprecated[] +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 or . and now support escaping names. -Graph name parts that contain unsupported characters for unescaped symbolic names now require backtick escaping. +| 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 `` 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`')++` diff --git a/modules/ROOT/pages/queries/expressions.adoc b/modules/ROOT/pages/queries/expressions.adoc index 77b6936d2..f4ba6f036 100644 --- a/modules/ROOT/pages/queries/expressions.adoc +++ b/modules/ROOT/pages/queries/expressions.adoc @@ -83,13 +83,13 @@ String literals can contain the following escape sequences: * Label and relationship type expressions: `(n:A|B)`, `+()-[r:R1|R2]->()+`. * `null`. -[[graphreferences]] +[[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 ` +* Database and alias names when managing link:{neo4j-docs-base-uri}/operations-manual/current/database-administration/[databases and aliases]: `CREATE DATABASE `. * Static graph references: `USE ` or `USE .` (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()`. * 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()`. -* Retrieving properties of a graph with the xref:functions/graph.adoc#functions-graph-propertiesByName[`graph.propertiesByName`] function: `graph.propertiesByName()` +* Retrieving properties of a graph with the xref:functions/graph.adoc#functions-graph-propertiesByName[`graph.propertiesByName`] function: `graph.propertiesByName()`. Rules on string expressions for graph references when using identifiers (static graph references, administration commands) or a string (graph.byName function):