Skip to content

graph references in Cypher 25 #1295

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: cypher-25
Choose a base branch
from
Open

graph references in Cypher 25 #1295

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5fb0c7e
update documentation of graph references in Cypher 25
nadja-muller May 31, 2025
fce50a8
include section about constituent names
nadja-muller Jun 5, 2025
eeb9437
include deprecation update
nadja-muller Jun 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 6 additions & 12 deletions modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -174,20 +174,14 @@ label:functionality[]
label:updated[]
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

since this is talking about deprecations/removals it should probably not be under the updated in Cypher 25 section, the deprecated bit should probably be in a Deprecated features section (not related to Cypher 25) and then in Removed in Cypher 25 for the breaking change part 🤔

[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 `<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')++`
|
The graph name ``composite.with.dot`.constituent` is deprecated. It is replaced by ``composite.with.dot`.constituent`.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

isn't your replacement the exact same thing as the deprecated one? 🤔

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The graph name ``composite.with.dot`.constituent` is deprecated. It is replaced by ``composite.with.dot`.constituent`.
The graph name ``composite.with.dot`.constituent` is deprecated. It is replaced by ``composite.with.dot.constituent``.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think just the fix above of moving a ` will help but there is also in general something up with the formatting:
image


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.
Comment on lines +182 to +184
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
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.

Usually we split the lines between sentences and not in the middle of sentences


a|
label:functionality[]
Expand Down
10 changes: 7 additions & 3 deletions modules/ROOT/pages/values-and-types/graph-references.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <composite-name>.<alias-name>, 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
Expand Down Expand Up @@ -32,7 +36,7 @@ The following rules apply for graph references when using identifiers (static gr

* 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 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(<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``.
* 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:
Expand Down