diff --git a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc index 6250cc475..9decf9b67 100644 --- a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc +++ b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc @@ -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`++ { ... }]->()` @@ -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[] @@ -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` @@ -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` @@ -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| @@ -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', @@ -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"] ---- diff --git a/modules/ROOT/pages/styleguide.adoc b/modules/ROOT/pages/styleguide.adoc index 0874703f7..bff296f2e 100644 --- a/modules/ROOT/pages/styleguide.adoc +++ b/modules/ROOT/pages/styleguide.adoc @@ -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] diff --git a/modules/ROOT/pages/syntax/naming.adoc b/modules/ROOT/pages/syntax/naming.adoc index 4f70b12f7..a483e62f7 100644 --- a/modules/ROOT/pages/syntax/naming.adoc +++ b/modules/ROOT/pages/syntax/naming.adoc @@ -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. diff --git a/modules/ROOT/pages/syntax/reserved.adoc b/modules/ROOT/pages/syntax/reserved.adoc index e38ba0ed2..fe298c19b 100644 --- a/modules/ROOT/pages/syntax/reserved.adoc +++ b/modules/ROOT/pages/syntax/reserved.adoc @@ -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