Skip to content
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

use quote in backticks rather than escape #1111

Merged
merged 2 commits into from
Nov 14, 2024
Merged

use quote in backticks rather than escape #1111

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3abb172
use quote in backticks rather than escape
JPryce-Aklundh Nov 14, 2024
9406faf
update
JPryce-Aklundh Nov 14, 2024
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
28 changes: 14 additions & 14 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 @@ -49,8 +49,8 @@ MATCH (where {...})
----
MATCH (...)-[where {...}]->()
----
a| The unescaped variable named `where` (or any casing variant, like `WHERE`) used in a node or relationship pattern followed directly by a property key-value expression is deprecated.
To continue using variables with this name, use backticks to escape the variable name:
a| The variable named `where` (or any casing variant, like `WHERE`) used in a node or relationship pattern followed directly by a property key-value expression is deprecated.
To continue using variables with this name, use backticks to quote the variable name:

* Node patterns: `MATCH (++`where`++ { ... })`
* Relationship patterns: `MATCH (...)-[++`where`++ { ... }]->()`
Expand Down Expand Up @@ -78,8 +78,8 @@ label:deprecated[]
----
CASE x ... WHEN is :: STRING THEN ... END
----
a| Using an unescaped variable named `is` (or any casing variant, like `IS`) as a `WHEN` operand in a xref:queries/case.adoc#case-simple[simple `CASE`] expression is deprecated.
To continue using variables with this name in simple `CASE` expressions, use backticks to escape the variable name: `CASE x ... WHEN ++`is`++ :: STRING THEN ... END`
a| Using a variable named `is` (or any casing variant, like `IS`) as a `WHEN` operand in a xref:queries/case.adoc#case-simple[simple `CASE`] expression is deprecated.
To continue using variables with this name in simple `CASE` expressions, use backticks to quote the variable name: `CASE x ... WHEN ++`is`++ :: STRING THEN ... END`

a|
label:functionality[]
Expand All @@ -91,8 +91,8 @@ CASE x ... WHEN contains + 1 THEN ... END
----
CASE x ... WHEN contains - 1 THEN ... END
----
a| Using an unescaped variable named `contains` (or any casing variant, like `CONTAINS`) in addition or subtraction operations within a `WHEN` operand of a xref:queries/case.adoc#case-simple[simple `CASE`] expression is deprecated.
To continue using variables with this name, use backticks to escape the variable name:
a| Using a variable named `contains` (or any casing variant, like `CONTAINS`) in addition or subtraction operations within a `WHEN` operand of a xref:queries/case.adoc#case-simple[simple `CASE`] expression is deprecated.
To continue using variables with this name, use backticks to quote the variable name:

* Additions: `CASE x ... WHEN ++`contains`++ + 1 THEN ... END`
* Subtractions: `CASE x ... WHEN ++`contains`++ - 1 THEN ... END`
Expand All @@ -107,8 +107,8 @@ CASE x ... WHEN in[1] THEN ... END
----
CASE x ... WHEN in["abc"] THEN ... END
----
a| Using the `[]` operator on an unescaped variable named `in` (or any casing variant, like `IN`) within a `WHEN` operand of a xref:queries/case.adoc#case-simple[simple `CASE`] expression is deprecated.
To continue using variables with this name, use backticks to escape the variable name:
a| Using the `[]` operator on a variable named `in` (or any casing variant, like `IN`) within a `WHEN` operand of a xref:queries/case.adoc#case-simple[simple `CASE`] expression is deprecated.
To continue using variables with this name, use backticks to quote the variable name:

* `CASE x ... WHEN ++`in`++[1] THEN ... END`
* `CASE x ... WHEN ++`in`++["abc"] THEN ... END`
Expand Down Expand Up @@ -1000,9 +1000,9 @@ label:deprecated[]
RETURN 1 as my\u0085identifier
----
a|
The Unicode character \`\u0085` is deprecated for unescaped identifiers and will be considered as a whitespace character in the future.
To continue using it, escape the identifier by adding backticks around the identifier.
This applies to all unescaped identifiers in Cypher, such as label expressions, properties, variable names or parameters.
The Unicode character \`\u0085` is deprecated for identifiers not quoted in backticks and will be considered as a whitespace character in the future.
To continue using it, quote the identifier with backticks.
This applies to all identifiers in Cypher, such as label expressions, properties, variable names or parameters.
In the given example, the quoted identifier would be \`my�identifier`.

a|
Expand All @@ -1013,8 +1013,8 @@ label:deprecated[]
RETURN 1 as my$Identifier
----
a|
The character with the Unicode representation \`\u0024` is deprecated for unescaped identifiers and will not be supported in the future. To continue using it, escape the identifier by adding backticks around the identifier.
This applies to all unescaped identifiers in Cypher, such as label expressions, properties, variable names or parameters. In the given example, the quoted identifier would be \`my$identifier`.
The character with the Unicode representation \`\u0024` is deprecated for identifiers not quoted in backticks and will not be supported in the future. To continue using it, quote the identifier with backticks.
This applies to all identifiers in Cypher, such as label expressions, properties, variable names or parameters. In the given example, the quoted identifier would be \`my$identifier`.

The following Unicode Characters are deprecated in identifiers:
'\u0000', '\u0001', '\u0002', '\u0003', '\u0004', '\u0005', '\u0006', '\u0007',
Expand Down Expand Up @@ -2682,7 +2682,7 @@ label:deprecated[]
CREATE DATABASE databaseName.withDot ...
----
a|
Creating a database with unescaped dots in the name has been deprecated, instead escape the database name:
Creating a database with dots in the name has been deprecated, instead quote the database name using backticks:

[source, cypher, role="noheader"]
----
Expand Down
2 changes: 1 addition & 1 deletion modules/ROOT/pages/styleguide.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -472,7 +472,7 @@ RETURN 'Cypher\'s a nice language', "Mats' quote: \"statement\""
RETURN "Cypher's a nice language", 'Mats\' quote: "statement"'
----

* Avoid having to use back-ticks to escape characters and keywords.
* Avoid using characters and keywords that require the input to be quoted with backticks.

.Bad
[source, cypher]
Expand Down
10 changes: 5 additions & 5 deletions modules/ROOT/pages/syntax/naming.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,23 +25,23 @@ For example, `MATCH ( a ) RETURN a` is equivalent to `MATCH (a) RETURN a`.

[[symbolic-names-escaping-rules]]
=== Using special characters in names
Non-alphabetic characters, including numbers, symbols and whitespace characters, *can* be used in names, but *must* be escaped using backticks.
Non-alphabetic characters, including numbers, symbols and whitespace characters, *can* be used in names, but *must* be quoted using backticks.
For example: `++`^n`++`, `++`1first`++`, `++`$$n`++`, and `++`my variable has spaces`++`.
Database names are an exception and may include dots without the need for escaping, although this behavior is deprecated as it may introduce ambiguity when addressing composite databases.
Database names are an exception and may include dots without the need for quoting using backticks, although this behavior is deprecated as it may introduce ambiguity when addressing composite databases.
For example: naming a database `foo.bar.baz` is valid, but deprecated. `++`foo.bar.baz`++` is valid.

Within an escaped name, the following escaping sequences are allowed:
Within a name quoted by backticks, the following character representations are allowed:

[options="header", cols=">1,<2"]
|===
|Escape sequence|Character
| Character representation | Description
|````| Backtick
|`\uxxxx`| Unicode UTF-16 code point (4 hex digits must follow the `\u`)
|===

[NOTE]
====
Using escaped names with unsanitized user input makes you vulnerable to Cypher injection.
Using names quoted in backticks with unsanitized user input makes you vulnerable to Cypher injection.
Some techniques to mitigate this are:

* sanitizing (and validating) the user input.
Expand Down
2 changes: 1 addition & 1 deletion modules/ROOT/pages/syntax/reserved.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ The reserved keywords are not permitted to be used as identifiers in the followi
* Function names
* Parameters

If any reserved keyword is escaped -- i.e. is encapsulated by backticks ```, such as `++`AND`++` -- it would become a valid identifier in the above contexts.
If any reserved keyword is quoted in backticks (```), such as `++`AND`++`, it would become a valid identifier in the above contexts; however, this approach is not recommended.

== Clauses

Expand Down
Loading