diff --git a/modules/ROOT/pages/clauses/use.adoc b/modules/ROOT/pages/clauses/use.adoc index 3a75add21..70beae342 100644 --- a/modules/ROOT/pages/clauses/use.adoc +++ b/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 +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 -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 diff --git a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc index 309887365..b57d87d75 100644 --- a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc +++ b/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 `` 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')++` + +Note that escaping graph names within the graph functions string argument is not supported in Cypher 5. + |=== === New features diff --git a/modules/ROOT/pages/queries/expressions.adoc b/modules/ROOT/pages/queries/expressions.adoc index 7f73fb3cb..f4ba6f036 100644 --- a/modules/ROOT/pages/queries/expressions.adoc +++ b/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 `. +* 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()`. + + +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()` 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`. + +