From e81a677ffd6051b761c65c5656055d3283ec5040 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jens=20Pryce-=C3=85klundh?= <112686610+JPryce-Aklundh@users.noreply.github.com> Date: Wed, 16 Apr 2025 11:45:38 +0200 Subject: [PATCH 1/5] final expressions initial --- modules/ROOT/content-nav.adoc | 5 +- .../gql-conformance/additional-cypher.adoc | 2 +- .../gql-conformance/supported-mandatory.adoc | 8 +- .../gql-conformance/supported-optional.adoc | 2 +- modules/ROOT/pages/clauses/match.adoc | 2 +- modules/ROOT/pages/clauses/order-by.adoc | 2 +- modules/ROOT/pages/clauses/use.adoc | 2 +- ...ions-additions-removals-compatibility.adoc | 6 +- .../expressions/conditional-expressions.adoc | 11 +- .../expressions/expressions-overview.adoc | 107 ------------------ modules/ROOT/pages/expressions/index.adoc | 15 ++- .../predicates/path-pattern-expressions.adoc | 4 +- .../predicates/string-operators.adoc | 2 +- modules/ROOT/pages/functions/predicate.adoc | 4 +- modules/ROOT/pages/functions/string.adoc | 2 +- modules/ROOT/pages/patterns/reference.adoc | 4 +- modules/ROOT/pages/queries/basic.adoc | 2 +- modules/ROOT/pages/queries/concepts.adoc | 2 +- modules/ROOT/pages/syntax/index.adoc | 1 - modules/ROOT/pages/syntax/parsing.adoc | 2 +- .../values-and-types/graph-references.adoc | 37 ++++++ .../ROOT/pages/values-and-types/index.adoc | 2 + .../numeric-string-boolean.adoc | 66 +++++++++++ .../ordering-equality-comparison.adoc | 6 +- .../property-structural-constructed.adoc | 6 +- .../ROOT/pages/values-and-types/spatial.adoc | 4 +- .../values-and-types/working-with-null.adoc | 6 +- 27 files changed, 161 insertions(+), 151 deletions(-) create mode 100644 modules/ROOT/pages/values-and-types/graph-references.adoc create mode 100644 modules/ROOT/pages/values-and-types/numeric-string-boolean.adoc diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index 1f2ddf6d0..8afcccb90 100644 --- a/modules/ROOT/content-nav.adoc +++ b/modules/ROOT/content-nav.adoc @@ -56,6 +56,7 @@ * xref:values-and-types/index.adoc[] ** xref:values-and-types/property-structural-constructed.adoc[] +** xref:values-and-types/numeric-string-boolean.adoc[] ** xref:values-and-types/temporal.adoc[] ** xref:values-and-types/spatial.adoc[] ** xref:values-and-types/working-with-null.adoc[] @@ -63,9 +64,10 @@ ** xref:values-and-types/maps.adoc[] ** xref:values-and-types/casting-data.adoc[] ** xref:values-and-types/ordering-equality-comparison.adoc[] +** xref:values-and-types/graph-references.adoc[] + * xref:expressions/index.adoc[] -** xref:expressions/expressions-overview.adoc[] ** xref:expressions/predicates/index.adoc[] *** xref:expressions/predicates/boolean-operators.adoc[] *** xref:expressions/predicates/comparison-operators.adoc[] @@ -135,7 +137,6 @@ ** xref:syntax/variables.adoc[] ** xref:syntax/keywords.adoc[] ** xref:syntax/parameters.adoc[] -** xref:syntax/operators.adoc[] ** xref:syntax/comments.adoc[] * xref:deprecations-additions-removals-compatibility.adoc[] diff --git a/modules/ROOT/pages/appendix/gql-conformance/additional-cypher.adoc b/modules/ROOT/pages/appendix/gql-conformance/additional-cypher.adoc index 1dabfe915..62fc7080c 100644 --- a/modules/ROOT/pages/appendix/gql-conformance/additional-cypher.adoc +++ b/modules/ROOT/pages/appendix/gql-conformance/additional-cypher.adoc @@ -620,7 +620,7 @@ GQL supports `GRAPH TYPES` as a way of constraining a graph schema, but does not | Cypher feature | Description -| xref:syntax/operators.adoc#query-operator-comparison-string-specific[`STARTS WITH`, `CONTAINS`, `ENDS WITH`, and regular expressions]. +| xref:expressions/predicates/string-operators.adoc[`STARTS WITH`, `CONTAINS`, `ENDS WITH`, and regular expressions]. | `STRING` comparison operators. | xref:expressions/predicates/list-operators.adoc[`IN`] diff --git a/modules/ROOT/pages/appendix/gql-conformance/supported-mandatory.adoc b/modules/ROOT/pages/appendix/gql-conformance/supported-mandatory.adoc index ff76821d2..54373be09 100644 --- a/modules/ROOT/pages/appendix/gql-conformance/supported-mandatory.adoc +++ b/modules/ROOT/pages/appendix/gql-conformance/supported-mandatory.adoc @@ -132,7 +132,7 @@ The only way to guarantee row order in Neo4j is to use xref:clauses/order-by.ado | 19.3 | -| xref:syntax/operators.adoc##query-operators-comparison[Comparison operators] +| xref:expressions/predicates/comparison-operators.adoc[Comparison operators] | | 19.4 @@ -152,12 +152,12 @@ The only way to guarantee row order in Neo4j is to use xref:clauses/order-by.ado | 19.7 | -| xref:syntax/operators.adoc#match-string-is-normalized[`IS NORMALIZED`], xref:syntax/operators.adoc#match-string-is-not-normalized[`IS NOT NORMALIZED`] +| xref:expressions/predicates/string-operators.adoc#string-normalization-operators[`IS NORMALIZED`,`IS NOT NORMALIZED`] | | 20.2 | -| xref:expressions/expressions-overview.adoc[] +| xref:expressions/index.adoc[] | | 20.3 @@ -194,7 +194,7 @@ For example, `RETURN sum()` on an empty table returns `NULL` in GQL, but i | 20.23 | -| xref:syntax/operators.adoc#syntax-concatenating-two-strings-doublebar[`STRING` concatenation operator (`\|\|`)] +| xref:expressions/string-operators.adoc[`STRING` concatenation operator (`\|\|`)] | | 20.24 diff --git a/modules/ROOT/pages/appendix/gql-conformance/supported-optional.adoc b/modules/ROOT/pages/appendix/gql-conformance/supported-optional.adoc index 0f930c4ab..bccbf9cd7 100644 --- a/modules/ROOT/pages/appendix/gql-conformance/supported-optional.adoc +++ b/modules/ROOT/pages/appendix/gql-conformance/supported-optional.adoc @@ -128,7 +128,7 @@ Cypher only supports xref:functions/mathematical-numeric.adoc#functions-ceil[`ce | Note the following exceptions: * Cypher uses the xref:functions/mathematical-logarithmic.adoc#functions-log[`log()`] function instead of GQL's `LN()` function. -* Cypher uses the xref:syntax/operators.adoc#syntax-using-the-exponentiation-operator[exponentiation operator (`^`)] instead of GQL's `POWER()` function. +* Cypher uses the xref:expressions/mathematical-operators.adoc[exponentiation operator (`^`)] instead of GQL's `POWER()` function. | GF05 | Multi-character trim functions diff --git a/modules/ROOT/pages/clauses/match.adoc b/modules/ROOT/pages/clauses/match.adoc index 207483bde..1aae9acc6 100644 --- a/modules/ROOT/pages/clauses/match.adoc +++ b/modules/ROOT/pages/clauses/match.adoc @@ -370,7 +370,7 @@ RETURN p.name AS actor, r.role AS role ---- [NOTE] -The above query uses the xref:syntax/operators.adoc#query-operator-comparison-string-specific[`CONTAINS` operator]. +The above query uses the xref:expressions/predicates/string-operators.adoc[`CONTAINS` operator]. .Result [role="queryresult",options="header,footer",cols="2*)`. -A more detailed description of how and when a graph references needs to be quoted and/or escaped is defined xref::expressions/expressions-overview.adoc#graphreferences[here]. +A more detailed description of how and when a graph references needs to be quoted and/or escaped is defined xref::values-and-types/graph-references.adoc#rules[here]. == USE clause when connected to a standard or system database diff --git a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc index 04fb8e5d5..38e383633 100644 --- a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc +++ b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc @@ -173,7 +173,7 @@ USE graph.byName('tom`s-database') USE graph.propertiesByName('database.with.dot') ---- -| xref::expressions/expressions-overview.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. +| 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 `` 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: @@ -1152,7 +1152,7 @@ RETURN "Hello" \|\| " " \|\| "World"; RETURN [1, 2] \|\| [3, 4, 5]; ---- -| Added a new `STRING` and `LIST` xref:syntax/operators.adoc[concatenation operator]. +| Added a new `STRING` and `LIST` xref:expressions/string-operators.adoc[concatenation operator]. a| label:functionality[] @@ -1353,7 +1353,7 @@ IS [NOT] [NFC \| NFD \| NFKC \| NFKD] NORMALIZED RETURN "string" IS NORMALIZED ---- -| Introduction of an xref::syntax/operators.adoc#match-string-is-normalized[IS NORMALIZED] operator. +| Introduction of an xref::expressions/predicates/string-operators.adoc#string-normalization-operator[IS NORMALIZED] operator. The operator can be used to check if a `STRING` is normalized according to the specified normalization form, which can be of type `NFC`, `NFD`, `NFKC`, or `NFKD`. a| diff --git a/modules/ROOT/pages/expressions/conditional-expressions.adoc b/modules/ROOT/pages/expressions/conditional-expressions.adoc index 8a775bcb6..edbf3832d 100644 --- a/modules/ROOT/pages/expressions/conditional-expressions.adoc +++ b/modules/ROOT/pages/expressions/conditional-expressions.adoc @@ -106,11 +106,12 @@ implied equals (`=`) comparator. The supported comparators are: -* xref::syntax/operators.adoc#query-operators-comparison[Regular Comparison Operators]: `+=+`, `+<>+`, `+<+`, `+>+`, `+<=+`, `+>=+` -* xref:values-and-types/working-with-null.adoc#is-null-is-not-null[`IS NULL` Operator]: `IS [NOT] NULL` -* xref:expressions/predicates/type-predicate-expressions.adoc[Type Predicate Expression]: `IS [NOT] TYPED ` (Note that the form `IS [NOT] :: ` is not accepted) -* xref::syntax/operators.adoc#match-string-is-normalized[Normalization Predicate Expression]: `IS [NOT] NORMALIZED` -* xref::syntax/operators.adoc#query-operator-comparison-string-specific[String Comparison Operators]: `STARTS WITH`, `ENDS WITH`, `=~` (regex matching) +* xref:expressions/predicates/comparison-operators.adoc[Regular Comparison Operators]: `+=+`, `+<>+`, `+<+`, `+>+`, `+<=+`, `+>=+` +* xref:expressions/predicates/comparison-operators.adoc[`IS [NOT] NULL`] +* xref:expressions/predicates/type-predicate-expressions.adoc[Type predicate expressions]: `IS [NOT] TYPED ` (Note that the form `IS [NOT] :: ` is not accepted) +* xref:expressions/predicates/string-operators.adoc[Normalization Predicate Expression]: `IS [NOT] NORMALIZED` +* xref:expressions/predicates/string-operators.adoc[String Comparison Operators]: `STARTS WITH`, `ENDS WITH`, `=~` (regex matching) + === Syntax diff --git a/modules/ROOT/pages/expressions/expressions-overview.adoc b/modules/ROOT/pages/expressions/expressions-overview.adoc index 94251910c..8b1378917 100644 --- a/modules/ROOT/pages/expressions/expressions-overview.adoc +++ b/modules/ROOT/pages/expressions/expressions-overview.adoc @@ -1,108 +1 @@ -= Expressions overview -:description: Overview of the expressions allowed in Cypher. - -This page contains an overview of the allowed expressions in Cypher. - -[[general]] -== General - -* A xref:syntax/variables.adoc[variable]: `n`, `x`, `rel`, `myFancyVariable`, `++`A name with special characters in it[]!`++`. -* A xref:queries/concepts.adoc[property]: `n.prop`, `x.prop`, `rel.thisProperty`, `++myFancyVariable.`(special property name)`++`. -For more information, see xref:values-and-types/property-structural-constructed.adoc#property-types[Values and types -> property types]. -* A xref:clauses/set.adoc#dynamic-set-property[dynamic property]: `n["prop"]`, `rel[n.city + n.zip]`, `map[coll[0]]`. -For more information, see xref:clauses/where.adoc#filter-on-dynamic-property[`WHERE` -> filter on dynamically computed properties]. -* A xref:syntax/parameters.adoc[parameter]: `$param`, `$0`. -* A xref:values-and-types/lists.adoc[list of expressions]: `['a', 'b']`, `[1, 2, 3]`, `['a', 2, n.property, $param]`, `[]`. -* A xref:functions/index.adoc[function] call: `length(p)`, `nodes(p)`. -* An xref:functions/aggregating.adoc[aggregating function] call: `avg(x.prop)`, `+count(*)+`. -* A xref:patterns/fixed-length-patterns.adoc#path-patterns[path-pattern]: `+(a)-[r]->(b)+`, `+(a)-[r]-(b)+`, `+(a)--(b)+`, `+(a)-->()<--(b)+`. -* An xref:syntax/operators.adoc[operator application]: `1 + 2`, `3 < 4`. -* A xref:subqueries/index.adoc[subquery expression]: `COUNT {}`, `COLLECT {}`, `EXISTS {}`, `CALL {}`. -* A xref:expressions/predicates/string-operators#regular-expressions[regular expression]: `a.name =~ 'Tim.*'`. -* A xref:expressions/conditional-expressions.adoc[`CASE` expression]. -* xref:values-and-types/working-with-null[`null`]. - -[NOTE] -==== -Expressions containing unsanitized user input may make your application vulnerable to Cypher injection. -Consider using xref:syntax/parameters.adoc[parameters] instead. -Learn more in link:https://neo4j.com/developer/kb/protecting-against-cypher-injection/[Protecting against Cypher Injection]. -==== - -[NOTE] -==== -Most expressions in Cypher evaluate to `null` if any of their inner expressions are `null`. -Notable exceptions are the operators `IS NULL`, `IS NOT NULL`, and the xref:expressions/predicates/type-predicate-expressions.adoc[type predicate expressions]. -==== - -[[numerical]] -== Numerical - -* A numeric (`INTEGER` or `FLOAT`) literal: `13`, `-40000`, `3.14`. -* A numeric (`INTEGER` or `FLOAT`) literal in scientific notation: `6.022E23`. -* A hexadecimal `INTEGER` literal (starting with `0x`): `0x13af`, `0xFC3A9`, `-0x66eff`. -* An octal `INTEGER` literal (starting with `0o`): `0o1372`, `-0o5671`. -* A `FLOAT` literal: `Inf`, `Infinity`, `NaN`. -* `null`. - -[NOTE] -==== -Any numeric literal may contain an underscore `_` between digits. -There may be an underscore between the `0x` or `0o` and the digits for hexadecimal and octal literals. -==== - -[[string]] -== String - -* A `STRING` literal: `'Hello'`, `"World"`. -* A case-sensitive `STRING` matching expression: `a.surname STARTS WITH 'Sven'`, `a.surname ENDS WITH 'son'` or `a.surname CONTAINS 'son'`. -* `null`. - -[[expressions-string-literals]] -=== String literal escape sequences - -String literals can contain the following escape sequences: - -[options="header", cols=">1,<2"] -|=================== -|Escape sequence|Character -|`\t`|Tab -|`\b`|Backspace -|`\n`|Newline -|`\r`|Carriage return -|`\f`|Form feed -|`\'`|Single quote -|`\"`|Double quote -|`\\`|Backslash -|`\uxxxx`|Unicode UTF-16 code point (4 hex digits must follow the `\u`) -|=================== - -[[boolean]] -== Boolean - -* A `BOOLEAN` literal: `true`, `false`. -* 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:expressions/expressions-overview.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`. - diff --git a/modules/ROOT/pages/expressions/index.adoc b/modules/ROOT/pages/expressions/index.adoc index df1119866..9b936acfa 100644 --- a/modules/ROOT/pages/expressions/index.adoc +++ b/modules/ROOT/pages/expressions/index.adoc @@ -2,11 +2,9 @@ :description: Information about the expressions available in Cypher. :page-aliases: syntax/operators.adoc - A Cypher expression is any part of a query that evaluates to a value. For details and examples of specific expressions, see the following sections: -* xref:expressions/expressions-overview.adoc[] * xref:expressions/predicates/index.adoc[] ** xref:expressions/predicates/boolean-operators.adoc[]: `AND`, `OR`, `XOR`, `NOT` ** xref:expressions/predicates/comparison-operators.adoc[]: `=`, `<>`, `<`, `>`, `\<=`, `>=`, `IS NULL`, `IS NOT NULL` @@ -21,3 +19,16 @@ For details and examples of specific expressions, see the following sections: * xref:expressions/list-expressions.adoc[]: information about list concatenation operators (`||`, `+`), list element access, list slicing, and list as well as pattern comprehensions. * xref:expressions/map-expressions.adoc[]: information about map operators (`.`, `[]`) and map projection. * xref:expressions/conditional-expressions.adoc[] +* xref:values-and-types/graph-references.adoc[] + +The following expressions are documented elsewhere in the Cypher Manual: + +* xref:patterns/reference.adoc#label-expressions[Label expressions] +* xref:functions/index.adoc[Function calls] +* Subquery expressions: xref:subqueries/collect.adoc[`COLLECT`], xref:subqueries/count.adoc[`COUNT`], and xref:subqueries/existential.adoc[`EXISTS`]. + +[NOTE] +Expressions containing unsanitized user input may make your application vulnerable to Cypher injection. +Consider using xref:syntax/parameters.adoc[parameters] instead. +Learn more in link:https://neo4j.com/developer/kb/protecting-against-cypher-injection/[Protecting against Cypher Injection]. + diff --git a/modules/ROOT/pages/expressions/predicates/path-pattern-expressions.adoc b/modules/ROOT/pages/expressions/predicates/path-pattern-expressions.adoc index 3b01b4dfb..b484bc791 100644 --- a/modules/ROOT/pages/expressions/predicates/path-pattern-expressions.adoc +++ b/modules/ROOT/pages/expressions/predicates/path-pattern-expressions.adoc @@ -2,7 +2,7 @@ :table-caption!: :description: Information about path pattern expressions in Cypher. -Similar to xref::subqueries/existential.adoc[existential subqueries], path pattern expressions can be used to assert whether a specified path exists at least once in a graph. +Similar to xref::subqueries/existential.adoc[`EXISTS` subqueries], path pattern expressions can be used to assert whether a specified path exists at least once in a graph. While existential subqueries are more powerful and capable of performing anything achievable with path pattern expressions, path pattern expressions are more concise. For more information about graph pattern matching in Cypher, see xref:patterns/index.adoc[]. @@ -20,7 +20,7 @@ In other words, it must contain at least one xref::patterns/reference.adoc#relat * Path pattern expressions may not declare new variables. They can only reference existing variables. -* Path pattern expressions may only be used in positions where a xref:expressions/expressions-overview.adoc#boolean[boolean expression] is expected. +* Path pattern expressions may only be used in positions where a xref:expressions/predicates/boolean-operators.adoc[boolean expression] is expected. The following sections will demonstrate how to use path pattern expressions in a `WHERE` clause. [[example-graph]] diff --git a/modules/ROOT/pages/expressions/predicates/string-operators.adoc b/modules/ROOT/pages/expressions/predicates/string-operators.adoc index f7164b1f5..44eeb043b 100644 --- a/modules/ROOT/pages/expressions/predicates/string-operators.adoc +++ b/modules/ROOT/pages/expressions/predicates/string-operators.adoc @@ -185,7 +185,7 @@ RETURN n.name AS name, n.email AS email |=== Note that the regular expression constructs in -link:https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/regex/Pattern.html[Java regular expressions] are applied only after resolving the escaped character sequences in the given xref::expressions/expressions-overview.adoc#expressions-string-literals[string literal]. +link:https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/regex/Pattern.html[Java regular expressions] are applied only after resolving the escaped character sequences in the given xref::values-and-types/numeric-string-boolean.adoc#string[string literal]. It is sometimes necessary to add additional backslashes to express regular expression constructs. This list clarifies the combination of these two definitions, containing the original escape sequence and the resulting character in the regular expression: diff --git a/modules/ROOT/pages/functions/predicate.adoc b/modules/ROOT/pages/functions/predicate.adoc index cd1eb446b..25c6a714f 100644 --- a/modules/ROOT/pages/functions/predicate.adoc +++ b/modules/ROOT/pages/functions/predicate.adoc @@ -196,7 +196,7 @@ RETURN any(i IN emptyList WHERE true) as anyTrue, any(i IN emptyList WHERE false [NOTE] ==== -To check if a property is not `null` use the xref::syntax/operators.adoc#cypher-comparison[`IS NOT NULL` predicate]. +To check if a property is not `null` use the xref:expressions/predicates/comparison-operators.adoc[`IS NOT NULL` predicate]. ==== .+exists()+ @@ -330,7 +330,7 @@ The `name` property of each node that has an empty `STRING` `address` property i The function `isEmpty()`, like most other Cypher functions, returns `null` if `null` is passed in to the function. That means that a predicate `isEmpty(n.address)` will filter out all nodes where the `address` property is not set. Thus, `isEmpty()` is not suited to test for `null`-values. -xref:syntax/operators.adoc#cypher-comparison[`IS NULL` or `IS NOT NULL`] should be used for that purpose. +xref:expressions/predicates/comparison-operators.adoc[`IS NULL` or `IS NOT NULL`] should be used for that purpose. ==== diff --git a/modules/ROOT/pages/functions/string.adoc b/modules/ROOT/pages/functions/string.adoc index 4a843d4a7..4b6a53b83 100644 --- a/modules/ROOT/pages/functions/string.adoc +++ b/modules/ROOT/pages/functions/string.adoc @@ -269,7 +269,7 @@ RETURN normalize('\u212B') = '\u00C5' AS result ====== -To check if a `STRING` is normalized, use the xref:syntax/operators.adoc#match-string-is-normalized[`IS NORMALIZED`] operator. +To check if a `STRING` is normalized, use the xref:expressions/predicates/string-operators.adoc#string-normalization-operators[`IS NORMALIZED`] operator. [[functions-normalize-with-normal-form]] === normalize() with specified normal form diff --git a/modules/ROOT/pages/patterns/reference.adoc b/modules/ROOT/pages/patterns/reference.adoc index c469e8529..b653ab9b2 100644 --- a/modules/ROOT/pages/patterns/reference.adoc +++ b/modules/ROOT/pages/patterns/reference.adoc @@ -344,7 +344,7 @@ is equivalent to the following node pattern with a `WHERE` clause: (n WHERE n.p = valueExp1 AND n.q = valueExp2) ---- -The value expression can be any expression as listed in the section on xref:expressions/expressions-overview.adoc[expressions], except for path patterns (which will throw a syntax error) and regular expressions (which will be treated as string literals). +The value expression can be any expression as listed in the section on xref:expressions/index.adoc[expressions], except for path patterns (which will throw a syntax error) and regular expressions (which will be treated as string literals). An empty property key-value expression matches all elements. Property key-value expressions can be combined with a `WHERE` clause. @@ -860,7 +860,7 @@ It is equivalent to the syntax for quantified relationships, with the following * Position and syntax of quantifier. * Semantics of the asterisk symbol. -* Type expressions are limited to the xref::syntax/operators.adoc#query-operators-boolean[disjunction operator]. +* Type expressions are limited to the xref:expressions/predicates/boolean-operators.adoc[disjunction operator]. * The xref:clauses/where.adoc[WHERE] clause is not allowed. [[variable-length-relationships-syntax]] diff --git a/modules/ROOT/pages/queries/basic.adoc b/modules/ROOT/pages/queries/basic.adoc index 416eeedd6..cb8c89698 100644 --- a/modules/ROOT/pages/queries/basic.adoc +++ b/modules/ROOT/pages/queries/basic.adoc @@ -743,7 +743,7 @@ There are several ways in which Cypher can be used to search a graph for paths b To search for patterns of a fixed length, specify the distance (hops) between the nodes in the pattern by using a xref::patterns/reference.adoc#quantifiers[quantifier] (`\{n}`). For example, the following query matches all `Person` nodes exactly 2 hops away from `Tom Hanks` and returns the first five rows. -The xref:syntax/operators.adoc#syntax-using-the-distinct-operator[DISTINCT] operator ensures that the result contain no duplicate values. +The ``DISTINCT` operator ensures that the result contain no duplicate values. .Query [source, cypher] diff --git a/modules/ROOT/pages/queries/concepts.adoc b/modules/ROOT/pages/queries/concepts.adoc index f0caa0fd8..d46e01358 100644 --- a/modules/ROOT/pages/queries/concepts.adoc +++ b/modules/ROOT/pages/queries/concepts.adoc @@ -68,7 +68,7 @@ RETURN DISTINCT friend.name AS olderConnections ---- This example uses a xref:patterns/variable-length-patterns.adoc#quantified-relationships[quantified relationship] to find all paths up to `5` hops away, traversing only relationships of type `KNOWS` from the start node `Anna` to other older `Person` nodes (as defined by the xref:clauses/where.adoc[] clause). -The xref:syntax/operators.adoc#syntax-using-the-distinct-operator[DISTINCT] operator is used to ensure that the `RETURN` clause only returns unique nodes. +The `DISTINCT` operator is used to ensure that the `RETURN` clause only returns unique nodes. Paths can also be assigned variables. For example, the below query binds a whole path pattern, which matches the xref:patterns/shortest-paths.adoc[`SHORTEST`] path from `Anna` to another `Person` node in the graph with a `nationality` property set to `Canadian`. diff --git a/modules/ROOT/pages/syntax/index.adoc b/modules/ROOT/pages/syntax/index.adoc index 04a664be0..b4e150bf2 100644 --- a/modules/ROOT/pages/syntax/index.adoc +++ b/modules/ROOT/pages/syntax/index.adoc @@ -10,5 +10,4 @@ Further information can be found in the following sections: * xref::syntax/variables.adoc[Variables] * xref::syntax/keywords.adoc[Keywords] * xref::syntax/parameters.adoc[Parameters] -* xref::syntax/operators.adoc[Operators] * xref::syntax/comments.adoc[Comments] diff --git a/modules/ROOT/pages/syntax/parsing.adoc b/modules/ROOT/pages/syntax/parsing.adoc index b35919f00..f1d3c6ad0 100644 --- a/modules/ROOT/pages/syntax/parsing.adoc +++ b/modules/ROOT/pages/syntax/parsing.adoc @@ -23,7 +23,7 @@ RETURN r Additional documentation on escaping rules for `STRING` literals, names and regular expressions can be found here: -* xref::expressions/expressions-overview.adoc#expressions-string-literals[String literal escape sequences] +* xref::values-and-types/numeric-string-boolean.adoc#string-literal-escape-sequences[String literal escape sequences] * xref::syntax/naming.adoc#symbolic-names-escaping-rules[Using special characters in names] * xref:expressions/predicates/string-operators.adoc#regular-expressions[Regular expressions] diff --git a/modules/ROOT/pages/values-and-types/graph-references.adoc b/modules/ROOT/pages/values-and-types/graph-references.adoc new file mode 100644 index 000000000..7c4955a8e --- /dev/null +++ b/modules/ROOT/pages/values-and-types/graph-references.adoc @@ -0,0 +1,37 @@ += Graph references + +In Cypher, 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()`. + +[[static-graph-references]] +== Static graph references + +A static graph reference is a direct reference to a graph in a database. +These include: + +* 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 selecting a graph with the `USE` clause: `USE ` or `USE .` (for constituents of a link:{neo4j-docs-base-uri}/operations-manual/current/database-administration/composite-databases/concepts/[composite databases]). + +[[dynamic-graph-references]] +== Dynamic graph references + +A dynamic graph reference is a reference to a graph using values that are evaluated during query execution using a function: +These include: + +* 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.byElementId()`. +* Retrieving properties of a graph with the xref:functions/graph.adoc#functions-graph-propertiesByName[`graph.propertiesByName()`] function: `graph.propertiesByName()`. + +[[rules]] +== Rules + +The following rules apply for 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:values-and-types/numeric-string-boolean.adoc#string-literal-escape-sequences[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`. \ No newline at end of file diff --git a/modules/ROOT/pages/values-and-types/index.adoc b/modules/ROOT/pages/values-and-types/index.adoc index 16bbbaf43..a2178904c 100644 --- a/modules/ROOT/pages/values-and-types/index.adoc +++ b/modules/ROOT/pages/values-and-types/index.adoc @@ -8,6 +8,7 @@ Rather, Cypher will automatically infer the data type of a given value. More information about the data values and types supported by Cypher can be found in the following sections: * xref::values-and-types/property-structural-constructed.adoc[] +* xref:values-and-types/numeric-string-boolean.adoc[] * xref::values-and-types/temporal.adoc[] * xref::values-and-types/spatial.adoc[] * xref::values-and-types/working-with-null.adoc[] @@ -15,6 +16,7 @@ More information about the data values and types supported by Cypher can be foun * xref::values-and-types/maps.adoc[] * xref::values-and-types/casting-data.adoc[] * xref:values-and-types/ordering-equality-comparison.adoc[] +* xref:values-and-types/graph-references.adoc[] [TIP] For information about how to check the type of a value, see xref:expressions/predicates/type-predicate-expressions.adoc[] diff --git a/modules/ROOT/pages/values-and-types/numeric-string-boolean.adoc b/modules/ROOT/pages/values-and-types/numeric-string-boolean.adoc new file mode 100644 index 000000000..d448fdaf8 --- /dev/null +++ b/modules/ROOT/pages/values-and-types/numeric-string-boolean.adoc @@ -0,0 +1,66 @@ += Numeric, string, and boolean literals + +This page describes the literal forms of numerical (`INTEGER` and `FLOAT`), `STRING`, and `BOOLEAN` values in xref:expressions/index.adoc[expressions]. + +[[numerical]] +== Numerical + +Numerical literals can represent `INTEGER` or `FLOAT` values. + +A numerical literal may be written as: + +* A numeric (`INTEGER` or `FLOAT`) literal: `13`, `-40000`, `3.14`. +* * A numeric (`INTEGER` or `FLOAT`) literal in scientific notation: `6.022E23`, `1e-9` +* A hexadecimal `INTEGER` literal (prefix `0x`): `0x13af`, `0xFC3A9`, `-0x66eff` +* An octal `INTEGER` literal (prefix `0o`): `0o1372`, `-0o5671` +* A `FLOAT` literal: `Inf`, `Infinity`, `NaN`. +* `NULL`. + +[NOTE] +Any numeric literal may contain an underscore `_` between digits. +There may be an underscore between the `0x` or `0o` and the digits for hexadecimal and octal literals. +For example: `1_000_000`, `0x_FC3A9`, and `0o_1372`. + +[[string]] +== String + +String literals represent `STRING` values. +They are written using single(`'`) or double quotes (`"`) and may contain escape sequences using a backslash (`\`). +A string literal may be written as: + +* A quoted `STRING` using single quotes: `'Hello, 42'` +* A quoted `STRING` using double quotes: `"Hello, 42"` +* A `STRING` with whitespace: `' hello '` +* A `STRING` with escape sequences: `'Line 1\nLine 2'`, `'Tab\tseparated'` +* A `STRING` using Unicode code point: `'Name: \u004Aohn'` (produces `'Name: John'`) +* `NULL`. + +[[string-literal-escape-sequences]] +=== String literal escape sequences + +String literals can contain the following escape sequences: + +[options="header", cols=">1,<2"] +|=== +|Escape sequence|Character +|`\t`|Tab +|`\b`|Backspace +|`\n`|Newline +|`\r`|Carriage return +|`\f`|Form feed +|`\'`|Single quote +|`\"`|Double quote +|`\\`|Backslash +|`\uxxxx`|Unicode UTF-16 code point (4 hex digits must follow the `\u`) +|=== + +[[boolean]] +== Boolean + +Boolean literals represent `BOOLEAN` values. + +A boolean literal may be written as: + +* The literal `true` +* The literal `false` +* `NULL`. \ No newline at end of file diff --git a/modules/ROOT/pages/values-and-types/ordering-equality-comparison.adoc b/modules/ROOT/pages/values-and-types/ordering-equality-comparison.adoc index f5cfb600d..8cf95403d 100644 --- a/modules/ROOT/pages/values-and-types/ordering-equality-comparison.adoc +++ b/modules/ROOT/pages/values-and-types/ordering-equality-comparison.adoc @@ -55,9 +55,9 @@ Values of different types are ordered based on a predefined hierarchy, from leas * xref::values-and-types/temporal.adoc[`LOCAL TIME`] * xref::values-and-types/temporal.adoc[`DURATION`] * xref::values-and-types/spatial.adoc[`POINT`] -* xref::expressions/expressions-overview.adoc#string[`STRING`] -* xref::expressions/expressions-overview.adoc#boolean[`BOOLEAN`] -* Numbers: xref::expressions/expressions-overview.adoc#numerical[`INTEGER`, `FLOAT`] +* xref::values-and-types/property-structural-constructed.adoc[`STRING`] +* xref::values-and-types/property-structural-constructed.adoc[`BOOLEAN`] +* Numbers: xref:values-and-types/property-structural-constructed.adoc[`INTEGER`, `FLOAT`] [NOTE] `NULL` is ordered after all other values. diff --git a/modules/ROOT/pages/values-and-types/property-structural-constructed.adoc b/modules/ROOT/pages/values-and-types/property-structural-constructed.adoc index 98f6c6240..39e0fba36 100644 --- a/modules/ROOT/pages/values-and-types/property-structural-constructed.adoc +++ b/modules/ROOT/pages/values-and-types/property-structural-constructed.adoc @@ -18,7 +18,7 @@ Property types are the most primitive types in Cypher and include the following: * Property types can be returned from Cypher queries. * Property types can be used as xref::syntax/parameters.adoc[parameters]. * Property types can be stored as properties. -* Property types can be constructed with xref::expressions/expressions-overview.adoc[Cypher literals]. +* Property types can be constructed with Cypher literals. Homogeneous lists of simple types can be stored as properties, although lists in general (see xref::values-and-types/property-structural-constructed.adoc#constructed-types[Constructed types]) cannot be stored as properties. Lists stored as properties cannot contain `null` values. @@ -36,7 +36,7 @@ The following data types are included in the structural types category: `NODE`, * Structural types can be returned from Cypher queries. * Structural types cannot be used as xref::syntax/parameters.adoc[parameters]. * Structural types cannot be stored as properties. -* Structural types cannot be constructed with xref::expressions/expressions-overview.adoc[Cypher literals]. +* Structural types cannot be constructed with Cypher literals. The `NODE` data type includes: id, label(s), and a map of properties. Note that labels are not values, but a form of pattern syntax. @@ -60,7 +60,7 @@ The following data types are included in the constructed types category: `LIST` * Constructed types can be returned from Cypher queries. * Constructed types can be used as xref::syntax/parameters.adoc[parameters]. * Constructed types cannot be stored as properties (with the exception of homogenous lists). -* Constructed types can be constructed with xref::expressions/expressions-overview.adoc[Cypher literals]. +* Constructed types can be constructed with Cypher literals. The `LIST` data type can be either a homogenous collection of simple values, or a heterogeneous, ordered collection of values, each of which can have any property, structural or constructed type. diff --git a/modules/ROOT/pages/values-and-types/spatial.adoc b/modules/ROOT/pages/values-and-types/spatial.adoc index f1b89a2e0..d61959c0d 100644 --- a/modules/ROOT/pages/values-and-types/spatial.adoc +++ b/modules/ROOT/pages/values-and-types/spatial.adoc @@ -13,7 +13,7 @@ Finally, it briefly explains comparability and orderability with regard to spati ==== For more information about spatial functions, allowing for the creation and manipulation of spatial values, see the section on xref::functions/spatial.adoc[Spatial functions]. -For more information about the comparison and ordering of spatial values, see the section on the xref::syntax/operators.adoc#cypher-ordering[ordering and comparison of values]. +For more information about the comparison and ordering of spatial values, see the section on xref::values-and-types/ordering-equality-comparison.adoc#ordering-spatial-temporal[Ordering spatial and temporal values]. ==== [[spatial-values-point-type]] @@ -40,7 +40,7 @@ Four Coordinate Reference Systems (CRS) are supported, each of which falls withi Data within different coordinate systems are entirely incomparable, and cannot be implicitly converted from one to the other. This is true even if they are both Cartesian or both geographic but of a different dimension. For example, if you search for 3D points using a 2D range, you will get no results. -However, they can be ordered, as discussed in more detail in the section about xref::syntax/operators.adoc#cypher-ordering[ordering and comparison of values]. +However, they can be ordered, as discussed in more detail in the section about xref:values-and-types/ordering-equality-comparison.adoc#ordering-spatial-temporal[Ordering spatial and temporal values]. [[spatial-values-crs-geographic]] diff --git a/modules/ROOT/pages/values-and-types/working-with-null.adoc b/modules/ROOT/pages/values-and-types/working-with-null.adoc index e980d0494..5d732bd46 100644 --- a/modules/ROOT/pages/values-and-types/working-with-null.adoc +++ b/modules/ROOT/pages/values-and-types/working-with-null.adoc @@ -20,7 +20,7 @@ This means that the expression `null` = `null` yields `null`, and not `true`. [[cypher-null-logical-operators]] == Logical operations with `null` -The xref::syntax/operators.adoc#query-operators-boolean[logical operators] (`AND`, `OR`, `XOR`, `NOT`) treat `null` as the **unknown value** of three-valued logic. +The xref::expressions/predicates/boolean-operators.adoc[boolean operators] (`AND`, `OR`, `XOR`, `NOT`) treat `null` as the **unknown value** of three-valued logic. .Truth table for logical operators [options="header", cols="^,^,^,^,^,^"] @@ -41,7 +41,7 @@ The xref::syntax/operators.adoc#query-operators-boolean[logical operators] (`AND [[cypher-null-in-operator]] == The `IN` operator and `null` -The xref::syntax/operators.adoc#syntax-using-in-to-check-if-a-number-is-in-a-list[IN operator] follows similar logic. +The xref:expressions/predicates/list-operators[`IN` operator] follows similar logic. If Cypher can ascertain that something exists in a list, the result will be `true`. Any list that contains a `null` and does not have a matching element will return `null`. Otherwise, the result will be `false`. @@ -98,5 +98,5 @@ a[coalesce($lower,0)..coalesce($upper,size(a))] [[is-null-is-not-null]] == Using `IS NULL` and `IS NOT NULL` Testing any value against `null`, either with the `=` operator or with the `<>` operator, always evaluates to `null`. -Therefore, use the special equality operators xref:syntax/operators.adoc#cypher-comparison[IS NULL or IS NOT NULL]. +Therefore, use the special equality operators xref:expressions/predicates/comparison-operators.adoc[`IS NULL` or `IS NOT NULL`]. From 0c57bdc6d2683ef5113a4f1fb7fd40a26aeef3f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jens=20Pryce-=C3=85klundh?= <112686610+JPryce-Aklundh@users.noreply.github.com> Date: Wed, 16 Apr 2025 11:56:13 +0200 Subject: [PATCH 2/5] small edits --- .../ROOT/pages/values-and-types/graph-references.adoc | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/values-and-types/graph-references.adoc b/modules/ROOT/pages/values-and-types/graph-references.adoc index 7c4955a8e..107cf1960 100644 --- a/modules/ROOT/pages/values-and-types/graph-references.adoc +++ b/modules/ROOT/pages/values-and-types/graph-references.adoc @@ -1,6 +1,7 @@ = Graph references +:description: Information about Cypher's graph reference values. -In Cypher, graph references are values used to specify which graph to operate on in a query. +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()`. [[static-graph-references]] @@ -15,7 +16,7 @@ These include: [[dynamic-graph-references]] == Dynamic graph references -A dynamic graph reference is a reference to a graph using values that are evaluated during query execution using a function: +A dynamic graph reference is a reference to a graph using values that are evaluated during query execution using a function. These include: * 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()`. @@ -25,7 +26,7 @@ These include: [[rules]] == Rules -The following rules apply for string expressions for graph references when using identifiers (static graph references, administration commands) or a string (`graph.byName function`): +The following rules apply for graph references when using identifiers (static graph references, administration commands) or the `graph.byName` functions: * 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`. @@ -33,5 +34,5 @@ To refer to a database with a dot (`.`) in its name, quote the graph reference i * 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:values-and-types/numeric-string-boolean.adoc#string-literal-escape-sequences[string literals] (during query parsing) and xref::syntax/naming.adoc#symbolic-names-escaping-rules[symbolic names] (during graph reference evaluation) are applied. +For `STRING` literals, both the xref:values-and-types/numeric-string-boolean.adoc#string-literal-escape-sequences[escaping rules] (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`. \ No newline at end of file From dac12389e03776d3e209d554385bc674a4854d13 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jens=20Pryce-=C3=85klundh?= <112686610+JPryce-Aklundh@users.noreply.github.com> Date: Wed, 16 Apr 2025 14:52:12 +0200 Subject: [PATCH 3/5] update --- modules/ROOT/content-nav.adoc | 19 ++++---- modules/ROOT/pages/expressions/index.adoc | 6 ++- .../predicates/string-operators.adoc | 2 +- modules/ROOT/pages/syntax/parsing.adoc | 2 +- ...olean.adoc => boolean-numeric-string.adoc} | 48 +++++++++++-------- .../values-and-types/graph-references.adoc | 2 +- .../ROOT/pages/values-and-types/index.adoc | 6 +-- 7 files changed, 46 insertions(+), 39 deletions(-) rename modules/ROOT/pages/values-and-types/{numeric-string-boolean.adoc => boolean-numeric-string.adoc} (62%) diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index 8afcccb90..bdbda333e 100644 --- a/modules/ROOT/content-nav.adoc +++ b/modules/ROOT/content-nav.adoc @@ -55,17 +55,16 @@ ** xref:patterns/reference.adoc[] * xref:values-and-types/index.adoc[] -** xref:values-and-types/property-structural-constructed.adoc[] -** xref:values-and-types/numeric-string-boolean.adoc[] -** xref:values-and-types/temporal.adoc[] -** xref:values-and-types/spatial.adoc[] -** xref:values-and-types/working-with-null.adoc[] -** xref:values-and-types/lists.adoc[] -** xref:values-and-types/maps.adoc[] -** xref:values-and-types/casting-data.adoc[] -** xref:values-and-types/ordering-equality-comparison.adoc[] +** xref::values-and-types/property-structural-constructed.adoc[] +** xref:values-and-types/boolean-numeric-string.adoc[] +** xref::values-and-types/temporal.adoc[] +** xref::values-and-types/spatial.adoc[] +** xref::values-and-types/lists.adoc[] +** xref::values-and-types/maps.adoc[] ** xref:values-and-types/graph-references.adoc[] - +** xref::values-and-types/working-with-null.adoc[] +** xref::values-and-types/casting-data.adoc[] +** xref:values-and-types/ordering-equality-comparison.adoc[] * xref:expressions/index.adoc[] ** xref:expressions/predicates/index.adoc[] diff --git a/modules/ROOT/pages/expressions/index.adoc b/modules/ROOT/pages/expressions/index.adoc index 9b936acfa..5dd6828e3 100644 --- a/modules/ROOT/pages/expressions/index.adoc +++ b/modules/ROOT/pages/expressions/index.adoc @@ -25,10 +25,12 @@ The following expressions are documented elsewhere in the Cypher Manual: * xref:patterns/reference.adoc#label-expressions[Label expressions] * xref:functions/index.adoc[Function calls] -* Subquery expressions: xref:subqueries/collect.adoc[`COLLECT`], xref:subqueries/count.adoc[`COUNT`], and xref:subqueries/existential.adoc[`EXISTS`]. +* Subquery expressions: xref:subqueries/collect.adoc[`COLLECT`], xref:subqueries/count.adoc[`COUNT`], and xref:subqueries/existential.adoc[`EXISTS`] +* Value literals (see xref:values-and-types/index.adoc[]) +* xref:values-and-types/graph-references.adoc[] [NOTE] Expressions containing unsanitized user input may make your application vulnerable to Cypher injection. Consider using xref:syntax/parameters.adoc[parameters] instead. -Learn more in link:https://neo4j.com/developer/kb/protecting-against-cypher-injection/[Protecting against Cypher Injection]. +For more information, see link:https://neo4j.com/developer/kb/protecting-against-cypher-injection/[Neo4j Knowledge Base -> Protecting against Cypher Injection]. diff --git a/modules/ROOT/pages/expressions/predicates/string-operators.adoc b/modules/ROOT/pages/expressions/predicates/string-operators.adoc index 44eeb043b..2669ebd23 100644 --- a/modules/ROOT/pages/expressions/predicates/string-operators.adoc +++ b/modules/ROOT/pages/expressions/predicates/string-operators.adoc @@ -185,7 +185,7 @@ RETURN n.name AS name, n.email AS email |=== Note that the regular expression constructs in -link:https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/regex/Pattern.html[Java regular expressions] are applied only after resolving the escaped character sequences in the given xref::values-and-types/numeric-string-boolean.adoc#string[string literal]. +link:https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/regex/Pattern.html[Java regular expressions] are applied only after resolving the escaped character sequences in the given xref::values-and-types/boolean-numeric-string.adoc#string[string literal]. It is sometimes necessary to add additional backslashes to express regular expression constructs. This list clarifies the combination of these two definitions, containing the original escape sequence and the resulting character in the regular expression: diff --git a/modules/ROOT/pages/syntax/parsing.adoc b/modules/ROOT/pages/syntax/parsing.adoc index f1d3c6ad0..4f8c60a60 100644 --- a/modules/ROOT/pages/syntax/parsing.adoc +++ b/modules/ROOT/pages/syntax/parsing.adoc @@ -23,7 +23,7 @@ RETURN r Additional documentation on escaping rules for `STRING` literals, names and regular expressions can be found here: -* xref::values-and-types/numeric-string-boolean.adoc#string-literal-escape-sequences[String literal escape sequences] +* xref::values-and-types/boolean-numeric-string.adoc#string-literal-escape-sequences[String literal escape sequences] * xref::syntax/naming.adoc#symbolic-names-escaping-rules[Using special characters in names] * xref:expressions/predicates/string-operators.adoc#regular-expressions[Regular expressions] diff --git a/modules/ROOT/pages/values-and-types/numeric-string-boolean.adoc b/modules/ROOT/pages/values-and-types/boolean-numeric-string.adoc similarity index 62% rename from modules/ROOT/pages/values-and-types/numeric-string-boolean.adoc rename to modules/ROOT/pages/values-and-types/boolean-numeric-string.adoc index d448fdaf8..7ab1fde66 100644 --- a/modules/ROOT/pages/values-and-types/numeric-string-boolean.adoc +++ b/modules/ROOT/pages/values-and-types/boolean-numeric-string.adoc @@ -1,20 +1,37 @@ -= Numeric, string, and boolean literals += Boolean, numeric, and string literals +:description: Information about Cypher's boolean, numeric, and string literals. This page describes the literal forms of numerical (`INTEGER` and `FLOAT`), `STRING`, and `BOOLEAN` values in xref:expressions/index.adoc[expressions]. +[NOTE] +Expressions containing unsanitized user input may make your application vulnerable to Cypher injection. +Consider using xref:syntax/parameters.adoc[parameters] instead. +For more information, see link:https://neo4j.com/developer/kb/protecting-against-cypher-injection/[Neo4j Knowledge Base -> Protecting against Cypher Injection]. + +[[boolean]] +== Boolean + +Boolean literals represent `BOOLEAN` values. +A boolean literal may be written as: + +* The literal `true` +* The literal `false` + [[numerical]] == Numerical Numerical literals can represent `INTEGER` or `FLOAT` values. - A numerical literal may be written as: -* A numeric (`INTEGER` or `FLOAT`) literal: `13`, `-40000`, `3.14`. -* * A numeric (`INTEGER` or `FLOAT`) literal in scientific notation: `6.022E23`, `1e-9` +* A decimal `INTEGER` literal: `13`, `-40000` * A hexadecimal `INTEGER` literal (prefix `0x`): `0x13af`, `0xFC3A9`, `-0x66eff` * An octal `INTEGER` literal (prefix `0o`): `0o1372`, `-0o5671` -* A `FLOAT` literal: `Inf`, `Infinity`, `NaN`. -* `NULL`. + +// + +* A `FLOAT` literal in common notation: `3.14` +* A `FLOAT` literal in scientific notation: `6.022E23`, `1e-9` +* Literals for special `FLOAT` values: `Inf`, `Infinity`, `NaN` [NOTE] Any numeric literal may contain an underscore `_` between digits. @@ -28,12 +45,12 @@ String literals represent `STRING` values. They are written using single(`'`) or double quotes (`"`) and may contain escape sequences using a backslash (`\`). A string literal may be written as: -* A quoted `STRING` using single quotes: `'Hello, 42'` -* A quoted `STRING` using double quotes: `"Hello, 42"` +* A `STRING` quoted with single quotes: `'Hello, 42'` +* A `STRING` quoted with double quotes: `"Hello, 42"` * A `STRING` with whitespace: `' hello '` * A `STRING` with escape sequences: `'Line 1\nLine 2'`, `'Tab\tseparated'` -* A `STRING` using Unicode code point: `'Name: \u004Aohn'` (produces `'Name: John'`) -* `NULL`. +* A `STRING` containing Unicode characters: `'그래프는 어디에나 있다'` +* A `STRING` using a Unicode code point: `'Name: \u004Aohn'` (produces `'Name: John'`) [[string-literal-escape-sequences]] === String literal escape sequences @@ -53,14 +70,3 @@ String literals can contain the following escape sequences: |`\\`|Backslash |`\uxxxx`|Unicode UTF-16 code point (4 hex digits must follow the `\u`) |=== - -[[boolean]] -== Boolean - -Boolean literals represent `BOOLEAN` values. - -A boolean literal may be written as: - -* The literal `true` -* The literal `false` -* `NULL`. \ No newline at end of file diff --git a/modules/ROOT/pages/values-and-types/graph-references.adoc b/modules/ROOT/pages/values-and-types/graph-references.adoc index 107cf1960..6efe8a96e 100644 --- a/modules/ROOT/pages/values-and-types/graph-references.adoc +++ b/modules/ROOT/pages/values-and-types/graph-references.adoc @@ -34,5 +34,5 @@ To refer to a database with a dot (`.`) in its name, quote the graph reference i * 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 xref:values-and-types/numeric-string-boolean.adoc#string-literal-escape-sequences[escaping rules] (during query parsing) and xref::syntax/naming.adoc#symbolic-names-escaping-rules[symbolic names] (during graph reference evaluation) are applied. +For `STRING` literals, both the xref:values-and-types/boolean-numeric-string.adoc#string-literal-escape-sequences[escaping rules] (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`. \ No newline at end of file diff --git a/modules/ROOT/pages/values-and-types/index.adoc b/modules/ROOT/pages/values-and-types/index.adoc index a2178904c..61222e496 100644 --- a/modules/ROOT/pages/values-and-types/index.adoc +++ b/modules/ROOT/pages/values-and-types/index.adoc @@ -8,15 +8,15 @@ Rather, Cypher will automatically infer the data type of a given value. More information about the data values and types supported by Cypher can be found in the following sections: * xref::values-and-types/property-structural-constructed.adoc[] -* xref:values-and-types/numeric-string-boolean.adoc[] +* xref:values-and-types/boolean-numeric-string.adoc[] * xref::values-and-types/temporal.adoc[] * xref::values-and-types/spatial.adoc[] -* xref::values-and-types/working-with-null.adoc[] * xref::values-and-types/lists.adoc[] * xref::values-and-types/maps.adoc[] +* xref:values-and-types/graph-references.adoc[] +* xref::values-and-types/working-with-null.adoc[] * xref::values-and-types/casting-data.adoc[] * xref:values-and-types/ordering-equality-comparison.adoc[] -* xref:values-and-types/graph-references.adoc[] [TIP] For information about how to check the type of a value, see xref:expressions/predicates/type-predicate-expressions.adoc[] From def167317059b5268ad3c4d8e03d09204dfdfa1f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jens=20Pryce-=C3=85klundh?= <112686610+JPryce-Aklundh@users.noreply.github.com> Date: Thu, 24 Apr 2025 09:47:51 +0200 Subject: [PATCH 4/5] remove double graph references --- modules/ROOT/pages/expressions/index.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/modules/ROOT/pages/expressions/index.adoc b/modules/ROOT/pages/expressions/index.adoc index 5dd6828e3..bad2e021e 100644 --- a/modules/ROOT/pages/expressions/index.adoc +++ b/modules/ROOT/pages/expressions/index.adoc @@ -19,7 +19,6 @@ For details and examples of specific expressions, see the following sections: * xref:expressions/list-expressions.adoc[]: information about list concatenation operators (`||`, `+`), list element access, list slicing, and list as well as pattern comprehensions. * xref:expressions/map-expressions.adoc[]: information about map operators (`.`, `[]`) and map projection. * xref:expressions/conditional-expressions.adoc[] -* xref:values-and-types/graph-references.adoc[] The following expressions are documented elsewhere in the Cypher Manual: From d1e8340c942ce46d439cab61a3bc8b3229bc918b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jens=20Pryce-=C3=85klundh?= <112686610+JPryce-Aklundh@users.noreply.github.com> Date: Thu, 24 Apr 2025 10:15:03 +0200 Subject: [PATCH 5/5] delete overview --- modules/ROOT/pages/expressions/expressions-overview.adoc | 1 - 1 file changed, 1 deletion(-) delete mode 100644 modules/ROOT/pages/expressions/expressions-overview.adoc diff --git a/modules/ROOT/pages/expressions/expressions-overview.adoc b/modules/ROOT/pages/expressions/expressions-overview.adoc deleted file mode 100644 index 8b1378917..000000000 --- a/modules/ROOT/pages/expressions/expressions-overview.adoc +++ /dev/null @@ -1 +0,0 @@ -