diff --git a/antora.yml b/antora.yml index 3efd4c638..c48e579e0 100644 --- a/antora.yml +++ b/antora.yml @@ -7,5 +7,5 @@ nav: asciidoc: attributes: neo4j-version: '5' - neo4j-version-minor: '5.23' - neo4j-version-exact: '5.23.0' + neo4j-version-minor: '5.24' + neo4j-version-exact: '5.24.0' diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index 9a786276e..2eabb7c4c 100644 --- a/modules/ROOT/content-nav.adoc +++ b/modules/ROOT/content-nav.adoc @@ -64,22 +64,23 @@ ** xref:values-and-types/type-predicate.adoc[] * xref:functions/index.adoc[] -** xref:functions/predicate.adoc[] -** xref:functions/scalar.adoc[] ** xref:functions/aggregating.adoc[] +** xref:functions/database.adoc[] +** xref:functions/graph.adoc[] ** xref:functions/list.adoc[] -** xref:functions/mathematical-numeric.adoc[] +** xref:functions/load-csv.adoc[] ** xref:functions/mathematical-logarithmic.adoc[] +** xref:functions/mathematical-numeric.adoc[] ** xref:functions/mathematical-trigonometric.adoc[] +** xref:functions/predicate.adoc[] +** xref:functions/scalar.adoc[] +** xref:functions/spatial.adoc[] ** xref:functions/string.adoc[] -** xref:functions/temporal/index.adoc[] ** xref:functions/temporal/duration.adoc[] -** xref:functions/spatial.adoc[] -** xref:functions/vector.adoc[] -** xref:functions/load-csv.adoc[] -** xref:functions/graph.adoc[] -** xref:functions/database.adoc[] +** xref:functions/temporal/index.adoc[] ** xref:functions/user-defined.adoc[] +** xref:functions/vector.adoc[] + * xref:genai-integrations.adoc[] * xref:indexes/index.adoc[] diff --git a/modules/ROOT/images/graph_limit_clause.svg b/modules/ROOT/images/graph_limit_clause.svg index 10d6ef05f..5a21cdd1b 100644 --- a/modules/ROOT/images/graph_limit_clause.svg +++ b/modules/ROOT/images/graph_limit_clause.svg @@ -1,71 +1 @@ - - - - - - -L - - - -N0 - -name = 'A' - - - -N4 - -name = 'E' - - - -N0->N4 - - -KNOWS - - - -N3 - -name = 'D' - - - -N0->N3 - - -KNOWS - - - -N2 - -name = 'C' - - - -N0->N2 - - -KNOWS - - - -N1 - -name = 'B' - - - -N0->N1 - - -KNOWS - - - +KNOWSKNOWSKNOWSKNOWSPersonname:'Erika'Personname:'Andy'Personname:'David'Personname:'Charlotte'Personname:'Bernard' \ No newline at end of file diff --git a/modules/ROOT/images/graph_list_functions.svg b/modules/ROOT/images/graph_list_functions.svg index 88b6c8672..82ad32e38 100644 --- a/modules/ROOT/images/graph_list_functions.svg +++ b/modules/ROOT/images/graph_list_functions.svg @@ -1,91 +1 @@ - - - - - - -L - - - -N0 - -Person, Developer - -name = 'Alice' -age = 38 -eyes = 'brown' - - - -N2 - -name = 'Charlie' -age = 53 -eyes = 'green' - - - -N0->N2 - - -KNOWS - - - -N1 - -name = 'Bob' -age = 25 -eyes = 'blue' - - - -N0->N1 - - -KNOWS - - - -N3 - -name = 'Daniel' -age = 54 -eyes = 'brown' - - - -N2->N3 - - -KNOWS - - - -N1->N3 - - -KNOWS - - - -N4 - -eyes = 'blue' -array = ['one', 'two', 'three'] -name = 'Eskil' -age = 41 - - - -N1->N4 - - -MARRIED - - - +KNOWSKNOWSKNOWSKNOWSMARRIEDAdministratorname:'Charlie'age:53eyes:'Green'Administratorname:'Bob'age:25eyes:'Blue'Developername:'Alice'age:38eyes:'Brown'Administratorname:'Daniel'age:53eyes:'Brown'Designername:'Eskil'age:41eyes:'Blue'likedColors:['Pink', 'Yellow', 'Black'] \ No newline at end of file diff --git a/modules/ROOT/images/graph_numeric_functions.svg b/modules/ROOT/images/graph_numeric_functions.svg index 78b904b14..82ad32e38 100644 --- a/modules/ROOT/images/graph_numeric_functions.svg +++ b/modules/ROOT/images/graph_numeric_functions.svg @@ -1,99 +1 @@ - - - - - - -L - - - -N0 - -A - -name = 'Alice' -age = 38 -eyes = 'brown' - - - -N2 - -C - -name = 'Charlie' -age = 53 -eyes = 'green' - - - -N0->N2 - - -KNOWS - - - -N1 - -B - -name = 'Bob' -age = 25 -eyes = 'blue' - - - -N0->N1 - - -KNOWS - - - -N3 - -D - -name = 'Daniel' -age = 54 -eyes = 'brown' - - - -N2->N3 - - -KNOWS - - - -N1->N3 - - -KNOWS - - - -N4 - -E - -eyes = 'blue' -array = ['one', 'two', 'three'] -name = 'Eskil' -age = 41 - - - -N1->N4 - - -MARRIED - - - +KNOWSKNOWSKNOWSKNOWSMARRIEDAdministratorname:'Charlie'age:53eyes:'Green'Administratorname:'Bob'age:25eyes:'Blue'Developername:'Alice'age:38eyes:'Brown'Administratorname:'Daniel'age:53eyes:'Brown'Designername:'Eskil'age:41eyes:'Blue'likedColors:['Pink', 'Yellow', 'Black'] \ No newline at end of file diff --git a/modules/ROOT/images/graph_order_by_clause.svg b/modules/ROOT/images/graph_order_by_clause.svg index 71ffc6faf..a42046fcc 100644 --- a/modules/ROOT/images/graph_order_by_clause.svg +++ b/modules/ROOT/images/graph_order_by_clause.svg @@ -1,50 +1 @@ - - - - - - -L - - - -N0 - -name = 'A' -age = 34 -length = 170 - - - -N1 - -name = 'B' -age = 36 - - - -N0->N1 - - -KNOWS - - - -N2 - -name = 'C' -age = 32 -length = 185 - - - -N1->N2 - - -KNOWS - - - +KNOWSKNOWSPersonname:'Charlotte'age:32length:185Personname:'Bernard'age:36Personname:'Andy'age:34length:170 \ No newline at end of file diff --git a/modules/ROOT/images/graph_remove_clause.svg b/modules/ROOT/images/graph_remove_clause.svg index fccb1b2c7..534698e78 100644 --- a/modules/ROOT/images/graph_remove_clause.svg +++ b/modules/ROOT/images/graph_remove_clause.svg @@ -1,54 +1 @@ - - - - - - -L - - - -N0 - -Swedish - -age = 36 -name = 'Andy' - - - -N2 - -Swedish, German - -age = 34 -name = 'Peter' - - - -N0->N2 - - -KNOWS - - - -N1 - -Swedish - -age = 25 -name = 'Timothy' - - - -N0->N1 - - -KNOWS - - - +KNOWSKNOWSSwedishname:'Andy'age:36propTestValue2:42Swedishname:'Timothy'age:25propTestValue2:42SwedishGermanname:'Peter'age:34 \ No newline at end of file diff --git a/modules/ROOT/images/graph_scalar_functions.svg b/modules/ROOT/images/graph_scalar_functions.svg index 549084a40..82ad32e38 100644 --- a/modules/ROOT/images/graph_scalar_functions.svg +++ b/modules/ROOT/images/graph_scalar_functions.svg @@ -1,91 +1 @@ - - - - - - -L - - - -N0 - -Developer - -name = 'Alice' -age = 38 -eyes = 'brown' - - - -N2 - -name = 'Charlie' -age = 53 -eyes = 'green' - - - -N0->N2 - - -KNOWS - - - -N1 - -name = 'Bob' -age = 25 -eyes = 'blue' - - - -N0->N1 - - -KNOWS - - - -N3 - -name = 'Daniel' -age = 54 -eyes = 'brown' - - - -N2->N3 - - -KNOWS - - - -N1->N3 - - -KNOWS - - - -N4 - -eyes = 'blue' -liked_colors = ['pink', 'yellow', 'black'] -name = 'Eskil' -age = 41 - - - -N1->N4 - - -MARRIED - - - +KNOWSKNOWSKNOWSKNOWSMARRIEDAdministratorname:'Charlie'age:53eyes:'Green'Administratorname:'Bob'age:25eyes:'Blue'Developername:'Alice'age:38eyes:'Brown'Administratorname:'Daniel'age:53eyes:'Brown'Designername:'Eskil'age:41eyes:'Blue'likedColors:['Pink', 'Yellow', 'Black'] \ No newline at end of file diff --git a/modules/ROOT/images/graph_set_clause.svg b/modules/ROOT/images/graph_set_clause.svg index 35e27e288..61126d48d 100644 --- a/modules/ROOT/images/graph_set_clause.svg +++ b/modules/ROOT/images/graph_set_clause.svg @@ -1,63 +1 @@ - - - - - - -L - - - -N0 - -Swedish - -name = 'Andy' -age = 36 -hungry = true - - - -N2 - -name = 'Peter' -age = 34 - - - -N0->N2 - - -KNOWS - - - -N1 - -name = 'Stefan' - - - -N1->N0 - - -KNOWS - - - -N3 - -name = 'George' - - - -N3->N2 - - -KNOWS - - - +KNOWSKNOWSKNOWSname:'Stefan'Swedishname:'Andy'age:36hungry:truename:'George'name:'Peter'age:34 \ No newline at end of file diff --git a/modules/ROOT/images/graph_skip_clause.svg b/modules/ROOT/images/graph_skip_clause.svg index 10d6ef05f..5a21cdd1b 100644 --- a/modules/ROOT/images/graph_skip_clause.svg +++ b/modules/ROOT/images/graph_skip_clause.svg @@ -1,71 +1 @@ - - - - - - -L - - - -N0 - -name = 'A' - - - -N4 - -name = 'E' - - - -N0->N4 - - -KNOWS - - - -N3 - -name = 'D' - - - -N0->N3 - - -KNOWS - - - -N2 - -name = 'C' - - - -N0->N2 - - -KNOWS - - - -N1 - -name = 'B' - - - -N0->N1 - - -KNOWS - - - +KNOWSKNOWSKNOWSKNOWSPersonname:'Erika'Personname:'Andy'Personname:'David'Personname:'Charlotte'Personname:'Bernard' \ No newline at end of file diff --git a/modules/ROOT/images/graph_spatial_functions.svg b/modules/ROOT/images/graph_spatial_functions.svg index b9d6b4db3..180186928 100644 --- a/modules/ROOT/images/graph_spatial_functions.svg +++ b/modules/ROOT/images/graph_spatial_functions.svg @@ -1,40 +1 @@ - - - - - - -L - - - -N0 - -TrainStation - -latitude = 55.672874 -longitude = 12.56459 -city = 'Copenhagen' - - - -N1 - -Office - -latitude = 55.611784 -longitude = 12.994341 -city = 'Malmo' - - - -N0->N1 - - -TRAVEL_ROUTE - - - +TRAVEL_ROUTETrainStationlatitude:55.672874longitude:12.564590city:'Copenhagen'Officelatitude:55.611784longitude:12.994341city:'Malmö' \ No newline at end of file diff --git a/modules/ROOT/pages/appendix/gql-conformance/supported-mandatory.adoc b/modules/ROOT/pages/appendix/gql-conformance/supported-mandatory.adoc index 478988f85..e2d4fa6f7 100644 --- a/modules/ROOT/pages/appendix/gql-conformance/supported-mandatory.adoc +++ b/modules/ROOT/pages/appendix/gql-conformance/supported-mandatory.adoc @@ -57,9 +57,8 @@ The only way to guarantee row order in Neo4j is to use xref:clauses/order-by.ado | 14.9 | -| xref:clauses/skip.adoc[`SKIP`] -| Cypher only supports `SKIP`, which is a GQL-supported synonym to `OFFSET`. - +| xref:clauses/order-by.adoc[`ORDER BY`], xref:clauses/skip.adoc[`SKIP`], xref::clauses/skip.adoc#offset-synonym[`OFFSET`], xref:clauses/limit.adoc[`LIMIT`] +| | 14.10 | @@ -118,8 +117,8 @@ The only way to guarantee row order in Neo4j is to use xref:clauses/order-by.ado | 16.19 | -| xref:clauses/skip.adoc[`SKIP`] -| Cypher only supports `SKIP` , which is a GQL-supported synonym to `OFFSET`. +| xref:clauses/skip.adoc[`SKIP`], xref::clauses/skip.adoc#offset-synonym[`OFFSET`] +| | 19.3 | diff --git a/modules/ROOT/pages/clauses/clause-composition.adoc b/modules/ROOT/pages/clauses/clause-composition.adoc index 5b56aa926..fa560590f 100644 --- a/modules/ROOT/pages/clauses/clause-composition.adoc +++ b/modules/ROOT/pages/clauses/clause-composition.adoc @@ -572,6 +572,10 @@ Later invocations of the subquery can observe writes made by earlier invocations ====== Using the same example graph as above, this example shows the table of intermediate results and the state of the graph after each clause for the following query: +[NOTE] +The below query uses a xref:subqueries/call-subquery.adoc#variable-scope-clause[variable scope clause] (introduced in Neo4j 5.23) to import variables into the `CALL` subquery. +If you are using an older version of Neo4j, use an xref:subqueries/call-subquery.adoc#importing-with[importing `WITH` clause] instead. + [source,cypher] ---- MATCH (john:Person {name: 'John'}) @@ -579,9 +583,8 @@ SET john.friends = [] WITH john MATCH (john)-[:FRIEND]->(friend) WITH john, friend -CALL { - WITH john, friend - WITH *, john.friends AS friends +CALL (john, friend) { + WITH john.friends AS friends SET john.friends = friends + friend.name } ---- @@ -756,7 +759,7 @@ label = "{Person\|name = \'Maria\'\l}" | First invocation of ---- -WITH *, john.friends AS friends +WITH john.friends AS friends ---- | [options="header",cols="2m, 1m, 1m"] @@ -850,7 +853,7 @@ label = "{Person\|name = \'Maria\'\l}" | Second invocation of ---- -WITH *, john.friends AS friends +WITH john.friends AS friends ---- | [options="header",cols="2m, 1m, 1m"] diff --git a/modules/ROOT/pages/clauses/delete.adoc b/modules/ROOT/pages/clauses/delete.adoc index c386f4175..0f6c13678 100644 --- a/modules/ROOT/pages/clauses/delete.adoc +++ b/modules/ROOT/pages/clauses/delete.adoc @@ -9,7 +9,11 @@ The `DELETE` clause is used to delete nodes, relationships or paths. For removing properties and labels, see the xref::clauses/remove.adoc[REMOVE] clause. It is not possible to delete nodes with relationships connected to them without also deleting the relationships. -This can be done by either explicitly deleting specific relationships, or by using the `DETACH DELETE` clause. +This can be done by either explicitly deleting specific relationships, or by using the `DETACH DELETE` clause. + +[NOTE] +While the `DELETE` clause renders the deleted objects no longer accessible, the space occupied by the deleted nodes and relationships remain on the disk and is reserved for future transactions creating data. +For information about how to clear and reuse the space occupied by deleted objects, see link:{neo4j-docs-base-uri}/operations-manual/{page-version}/performance/space-reuse/[Operations Manual -> Space reuse]. == Example graph diff --git a/modules/ROOT/pages/clauses/index.adoc b/modules/ROOT/pages/clauses/index.adoc index 36d0f19a4..d0e421713 100644 --- a/modules/ROOT/pages/clauses/index.adoc +++ b/modules/ROOT/pages/clauses/index.adoc @@ -63,12 +63,15 @@ m| xref::clauses/where.adoc[WHERE] m| xref::clauses/order-by.adoc[ORDER BY [ASC[ENDING\] \| DESC[ENDING\]\]] | A sub-clause following `RETURN` or `WITH`, specifying that the output should be sorted in either ascending (the default) or descending order. +As of Neo4j 5.24, it can also be used as a standalone clause. -m| xref::clauses/skip.adoc[SKIP] +m| xref::clauses/skip.adoc[SKIP] / xref::clauses/skip.adoc#offset-synonym[`OFFSET`] | Defines from which row to start including the rows in the output. +As of Neo4j 5.24, it can be used as a standalone clause. m| xref::clauses/limit.adoc[LIMIT] | Constrains the number of rows in the output. +As of Neo4j 5.24, it can be used as a standalone clause. |=== diff --git a/modules/ROOT/pages/clauses/limit.adoc b/modules/ROOT/pages/clauses/limit.adoc index 056fa5cae..cc29cf861 100644 --- a/modules/ROOT/pages/clauses/limit.adoc +++ b/modules/ROOT/pages/clauses/limit.adoc @@ -5,29 +5,41 @@ `LIMIT` constrains the number of returned rows. -`LIMIT` accepts any expression that evaluates to a positive integer and does not refer to nodes or relationships. +`LIMIT` accepts any expression that evaluates to a positive `INTEGER` and does not refer to nodes or relationships. -image:graph_limit_clause.svg[] +[NOTE] +Neo4j does not guarantee the results generated by `LIMIT`. +The only clause that guarantees a specific row order is xref:clauses/order-by.adoc[`ORDER BY`]. + +[[example-graph]] +== Example graph + +The following graph is used for the examples below: + +image::graph_limit_clause.svg[width="600", role="middle"] + +To recreate it, run the following query against an empty Neo4j database: -//// [source, cypher, role=test-setup] ---- CREATE - (a {name: 'A'}), - (b {name: 'B'}), - (c {name: 'C'}), - (d {name: 'D'}), - (e {name: 'E'}), - (a)-[:KNOWS]->(b), - (a)-[:KNOWS]->(c), - (a)-[:KNOWS]->(d), - (a)-[:KNOWS]->(e) + (andy: Person {name: 'Andy'}), + (bernard: Person {name: 'Bernard'}), + (charlotte: Person {name: 'Charlotte'}), + (david: Person {name: 'David'}), + (erika: Person {name: 'Erika'}), + (andy)-[:KNOWS]->(bernard), + (andy)-[:KNOWS]->(charlotte), + (andy)-[:KNOWS]->(david), + (andy)-[:KNOWS]->(erika) ---- -//// +[[examples]] +== Examples -[[limit-subset-rows]] -== Return a limited subset of the rows + +.Return a limited subset of the rows +==== To return a limited subset of the rows, use this syntax: @@ -46,15 +58,16 @@ Limit to 3 rows by the example query. [role="queryresult",options="header,footer",cols="1*(b), - (b)-[:KNOWS]->(c) + (andy: Person {name: 'Andy', age: 34, length: 170}), + (bernard: Person {name: 'Bernard', age: 36}), + (charlotte: Person {name: 'Charlotte', age: 32, length: 185}), + (andy)-[:KNOWS]->(bernard), + (bernard)-[:KNOWS]->(charlotte) ---- -//// - -[NOTE] -==== -Strings that contain special characters can have inconsistent or non-deterministic ordering in Neo4j. -For details, see xref::values-and-types/property-structural-constructed.adoc#property-types-sip-note[Sorting of special characters]. -==== [[order-nodes-by-property]] == Order nodes by property @@ -41,7 +40,7 @@ For details, see xref::values-and-types/property-structural-constructed.adoc#pro `ORDER BY` is used to sort the output. .Query -[source, cypher, indent=0] +[source, cypher] ---- MATCH (n) RETURN n.name, n.age @@ -54,9 +53,9 @@ The nodes are returned, sorted by their name. [role="queryresult",options="header,footer",cols="2* -| "A" | 34 | 170 -| "C" | 32 | 185 +| "Bernard" | 36 | +| "Andy" | 34 | 170 +| "Charlotte" | 32 | 185 3+d|Rows: 3 |=== @@ -153,7 +149,7 @@ The nodes are returned, sorted by their properties. By adding `DESC[ENDING]` after the variable to sort on, the sort will be done in reverse order. .Query -[source, cypher, indent=0] +[source, cypher] ---- MATCH (n) RETURN n.name, n.age @@ -166,9 +162,9 @@ The example returns the nodes, sorted by their name in reverse order. [role="queryresult",options="header,footer",cols="2* | "B" | 36 +| 170 | "Andy" | 34 +| 185 | "Charlotte" | 32 +| | "Bernard" | 36 3+d|Rows: 3 |=== @@ -209,7 +205,7 @@ For example, this can be used to control the order of items in the list produced The `MERGE` and `SET` clauses also have ordering dependencies which can be controlled this way. .Query -[source, cypher, indent=0] +[source, cypher] ---- MATCH (n) WITH n ORDER BY n.age @@ -222,7 +218,7 @@ The list of names built from the `collect` aggregating function contains the nam [role="queryresult",options="header,footer",cols="1*(t), (a)-[:KNOWS]->(p) ---- -//// [[remove-remove-a-property]] @@ -66,6 +68,45 @@ Properties set: 1 `REMOVE` cannot be used to remove all existing properties from a node or relationship. Instead, using xref::clauses/set.adoc#set-remove-properties-using-empty-map[`SET` with `=` and an empty map as the right operand] will clear all properties from the node or relationship. +[role=label--new-5.24] +[[remove-remove-a-property-dynamically]] +== Dynamically removing a property + +`REMOVE` can be used to remove a property on a node or relationship even when the property key name is not statically known. + +[source, syntax] +---- +REMOVE n[key] +---- + +The dynamically calculated key must evaluate to a `STRING` value. +This query creates a copy of every property on the nodes: + + +.Query +[source, cypher, indent=0] +---- +MATCH (n) +WITH n, [k IN keys(n) WHERE k CONTAINS "Test" | k] as propertyKeys // <1> +FOREACH (i IN propertyKeys | REMOVE n[i]) // <2> +RETURN n.name, keys(n); +---- + +<1> The xref:functions/list.adoc#functions-keys[keys()] function retrieves all property keys of the matched nodes, and a xref:values-and-types/lists.adoc#cypher-list-comprehension[list comprehension] filters these keys to include only those that contain the substring "Test", assigning the resulting list to the variable `propertyKeys`. +<2> The xref:clauses/foreach.adoc[`FOREACH`] clause iterates over each key in the `propertyKeys` list and removes the corresponding property using the `REMOVE` clause. + +All properties with the word "Test" in them are removed: + +.Result +[role="queryresult",options="header,footer",cols="2* +REMOVE n:$(label) +RETURN n.name, labels(n) +---- + +<1> xref:clauses/unwind.adoc[`UNWIND`] is used here to transform the list of labels from the xref:functions/list.adoc#functions-labels[`labels()]` function into separate rows, allowing subsequent operations to be performed on each label individually. + +.Result +[role="queryresult",options="header,footer",cols="2*` and/or by chaining them separately with a `:`: + +.Query +[source, cypher, indent=0] +---- +MATCH (n {name: 'Peter'}) +REMOVE n:$(labels(n)) +RETURN n.name, labels(n) +---- + +.Result +[role="queryresult",options="header,footer",cols="2*(a), (d)-[:KNOWS]->(c) ---- -//// - [[set-set-a-property]] == Set a property @@ -160,6 +161,47 @@ Properties set: 1 |=== +[role=label--new-5.24] +[[set-dynamically-a-property]] +== Dynamically setting or updating a property + +`SET` can be used to set or update a property on a node or relationship even when the property key name is not statically known. + +[source, syntax] +---- +SET n[key] = expression +---- + +The dynamically calculated key must evaluate to a `STRING` value. +This query creates a copy of every property on the nodes: + +.Query +[source, cypher] +---- +MATCH (n) +FOREACH (k IN keys(n) | SET n[k + "Copy"] = n[k]) // <1> +RETURN n.name, keys(n); +---- + + +<1> The xref:clauses/foreach.adoc[`FOREACH`] clause iterates over each property key `k` obtained from the xref::functions/list.adoc#functions-keys[`keys()`] function. +For each key, it sets a new property on the nodes with a key name of `k` + "Copy" and copies the value from the original property. + +The nodes now have copies of all their properties. + +.Result +[role="queryresult",options="header,footer",cols="2*` and/or by chaining them separately with a `:`: + +.Query +[source, cypher] +---- +WITH COLLECT { UNWIND range(0,3) AS id RETURN "Label" + id } as labels // <1> +MATCH (n {name: 'George'}) +SET n:$(labels) +RETURN n.name, labels(n) AS labels +---- + +<1> A xref:subqueries/collect.adoc[`COLLECT`] subquery aggregates the results of `UNWIND range(0,3) AS id RETURN "Label" + id`, which generates a `LIST` strings ("Label0", "Label1", "Label2", "Label3"), and assigns it to the variable `labels`. + +The newly-labeled node is returned by the query. + +.Result +[role="queryresult",options="header,footer",cols="2*(b), - (a)-[:KNOWS]->(c), - (a)-[:KNOWS]->(d), - (a)-[:KNOWS]->(e) + (andy: Person {name: 'Andy'}), + (bernard: Person {name: 'Bernard'}), + (charlotte: Person {name: 'Charlotte'}), + (david: Person {name: 'David'}), + (erika: Person {name: 'Erika'}), + (andy)-[:KNOWS]->(bernard), + (andy)-[:KNOWS]->(charlotte), + (andy)-[:KNOWS]->(david), + (andy)-[:KNOWS]->(erika) ---- -//// +[[examples]] +== Examples -[[skip-first-three-rows]] -== Skip first three rows +.Skip the first three rows +==== -To return a subset of the result, starting from the fourth result, use the following syntax: +The following query returns a subset of the result, starting from the fourth result. .Query -[source, cypher, indent=0] +[source, cypher] ---- MATCH (n) RETURN n.name @@ -43,25 +52,24 @@ ORDER BY n.name SKIP 3 ---- -The first three nodes are skipped, and only the last two are returned in the result. - .Result [role="queryresult",options="header,footer",cols="1*` |=== - -*Considerations:* - +.Considerations |=== | Any `null` values are ignored and will not be added to the list. @@ -224,8 +145,8 @@ All the values are collected and returned in a single list: [role="queryresult",options="header,footer",cols="1*` +|=== + +.Considerations +|=== +| `graph.names()` is only supported on link:{neo4j-docs-base-uri}/operations-manual/{page-version}/composite-databases[composite databases]. +|=== .+graph.names()+ ====== @@ -48,8 +58,20 @@ The names of all graphs on the current composite database are returned. [[functions-graph-propertiesByName]] == graph.propertiesByName() -Returns a map containing the properties associated with the given graph. The properties are set on the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/database-administration/aliases/manage-aliases-standard-databases/[alias]that adds the graph as a constituent of a composite database. -It is only supported on link:{neo4j-docs-base-uri}/operations-manual/{page-version}/composite-databases[composite databases]. +.Details +|=== +| *Syntax* 3+| `graph.propertiesByName(graphName)` +| *Description* 3+| Returns the `MAP` of properties associated with a graph. +.2+| *Arguments* | *Name* | *Type* | *Description* +| `graphName` | `STRING` | The name of the graph from which all associated properties will be returned. +| *Returns* 3+| `MAP` +|=== + +.Considerations +|=== +| `graph.propertiesByName()` is only supported on link:{neo4j-docs-base-uri}/operations-manual/{page-version}/composite-databases[composite databases]. +| The properties in the returned `MAP` are set on the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/database-administration/aliases/manage-aliases-standard-databases/[alias]that adds the graph as a constituent of a composite database. +|=== .+graph.propertiesByName()+ ====== @@ -110,16 +132,20 @@ Returns all nodes from a subset of graphs that have a `tags` property containing [[functions-graph-byname]] == graph.byName() -Resolves a constituent graph by name. -It is only supported in the xref:clauses/use.adoc[`USE` clause], on link:{neo4j-docs-base-uri}/operations-manual/{page-version}/composite-databases[composite databases]. +.Details +|=== +| *Syntax* 3+| `graph.byName(name)` +| *Description* 3+| Returns the graph reference of the given name. It is only supported in the `USE` clause, on composite databases. +.2+| *Arguments* | *Name* | *Type* | *Description* +| `name` | `STRING` | The name of the graph to be resolved. +| *Returns* 3+| `GRAPH` +|=== .+graph.byName()+ ====== .Query [source, cypher, indent=0] - -[source, cypher, role=noplay] ---- UNWIND graph.names() AS graphName CALL { @@ -138,8 +164,19 @@ Returns all nodes from all graphs on the current composite database. [[functions-graph-by-elementid]] == graph.byElementId() -The `graph.byElementId()` function is used in the xref:clauses/use.adoc[] clause to resolve a constituent graph to which a given element id belongs. -If the constituent database is not a standard database in the DBMS, an error will be thrown. +.Details +|=== +| *Syntax* 3+| `graph.byElementId(elementId)` +| *Description* 3+| Returns the graph reference with the given element id. It is only supported in the `USE` clause, on composite databases. +.2+| *Arguments* | *Name* | *Type* | *Description* +| `elementId` | `STRING` | An element id of a node or relationship. +| *Returns* 3+| `GRAPH` +|=== + +.Considerations +|=== +| If the constituent database is not a standard database in the DBMS, an error will be thrown. +|=== .+graph.byElementId()+ ====== diff --git a/modules/ROOT/pages/functions/index.adoc b/modules/ROOT/pages/functions/index.adoc index 0e970cae0..315171f5c 100644 --- a/modules/ROOT/pages/functions/index.adoc +++ b/modules/ROOT/pages/functions/index.adoc @@ -3,213 +3,26 @@ [[query-function]] = Functions -This section contains information on all functions in the Cypher query language. - -* Predicate functions [xref::functions/index.adoc#header-query-functions-predicate[Summary]|xref::functions/predicate.adoc[Detail]] -* Scalar functions [xref::functions/index.adoc#header-query-functions-scalar[Summary]|xref::functions/scalar.adoc[Detail]] -* Aggregating functions [xref::functions/index.adoc#header-query-functions-aggregating[Summary]|xref::functions/aggregating.adoc[Detail]] -* List functions [xref::functions/index.adoc#header-query-functions-list[Summary]|xref::functions/list.adoc[Detail]] -* Mathematical functions - numeric [xref::functions/index.adoc#header-query-functions-numeric[Summary]|xref::functions/mathematical-numeric.adoc[Detail]] -* Mathematical functions - logarithmic [xref::functions/index.adoc#header-query-functions-logarithmic[Summary]|xref::functions/mathematical-logarithmic.adoc[Detail]] -* Mathematical functions - trigonometric [xref::functions/index.adoc#header-query-functions-trigonometric[Summary]|xref::functions/mathematical-trigonometric.adoc[Detail]] -* String functions [xref::functions/index.adoc#header-query-functions-string[Summary]|xref::functions/string.adoc[Detail]] -* Temporal functions - instant types [xref::functions/index.adoc#header-query-functions-temporal-instant-types[Summary]|xref::functions/temporal/index.adoc[Detail]] -* Temporal functions - duration [xref::functions/index.adoc#header-query-functions-temporal-duration[Summary]|xref::functions/temporal/duration.adoc[Detail]] -* Spatial functions [xref::functions/index.adoc#header-query-functions-spatial[Summary]|xref::functions/spatial.adoc[Detail]] -* Vector functions [xref::functions/index.adoc#header-query-functions-vector[Summary]|xref::functions/vector.adoc[Detail]] label:new[Introduced in 5.18] -* LOAD CSV functions [xref::functions/index.adoc#header-query-functions-load-csv[Summary]|xref::functions/load-csv.adoc[Detail]] -* Graph functions [xref::functions/index.adoc#header-query-functions-graph[Summary]|xref::functions/graph.adoc[Detail]] -* Database functions [xref::functions/index.adoc#header-query-functions-database[Summary]|xref::functions/database.adoc[Detail]] label:new[Introduced in 5.12] -* GenAI function [xref::functions/index.adoc#header-query-functions-genai[Summary]|xref::genai-integrations.adoc#single-embedding[Detail]] label:new[Introduced in 5.17] -* User-defined functions [xref::functions/index.adoc#header-query-functions-user-defined[Summary]|xref::functions/user-defined.adoc[Detail]] - -Related information may be found in xref::syntax/operators.adoc[Operators]. - -[NOTE] -==== -* Functions in Cypher return `null` if an input parameter is `null`. -* Functions taking a `STRING` as input all operate on _Unicode characters_ rather than on a standard `char[]`. - For example, the `size()` function applied to any _Unicode character_ will return `1`, even if the character does not fit in the 16 bits of one `char`. -==== +This section contains a summary of all functions in Cypher. +To list all functions, run the following query: -.List available functions -====== -To list the available functions, run the following xref::clauses/listing-functions.adoc[Cypher query]: - +.List all functions [source, cypher, indent=0] ---- SHOW FUNCTIONS ---- -====== - - -[[header-query-functions-predicate]] -**xref::functions/predicate.adoc[Predicate functions]** - -These functions return either true or false for the given arguments. - -[options="header"] -|=== -| Function | Signature | Description - -1.1+| xref::functions/predicate.adoc#functions-all[`all()`] -| `all(variable :: VARIABLE IN list :: LIST WHERE predicate :: ANY) :: BOOLEAN` -| Returns true if the predicate holds for all elements in the given `LIST`. - -1.1+| xref::functions/predicate.adoc#functions-any[`any()`] -| `any(variable :: VARIABLE IN list :: LIST WHERE predicate :: ANY) :: BOOLEAN` -| Returns true if the predicate holds for at least one element in the given `LIST`. - -1.1+| xref::functions/predicate.adoc#functions-exists[`exists()`] -| `exists(input :: ANY) :: BOOLEAN` -| Returns `true` if a match for the pattern exists in the graph. - -1.3+| xref::functions/predicate.adoc#functions-isempty[`isEmpty()`] -| `isEmpty(input :: LIST) :: BOOLEAN` -| Checks whether a `LIST` is empty. -| `isEmpty(input :: MAP) :: BOOLEAN` -| Checks whether a `MAP` is empty. -| `isEmpty(input :: STRING) :: BOOLEAN` -| Checks whether a `STRING` is empty. - -1.1+| xref::functions/predicate.adoc#functions-none[`none()`] -| `none(variable :: VARIABLE IN list :: LIST WHERE predicate :: ANY) :: BOOLEAN` -| Returns true if the predicate holds for no element in the given `LIST`. - -1.1+| xref::functions/predicate.adoc#functions-single[`single()`] -| `single(variable :: VARIABLE IN list :: LIST WHERE predicate :: ANY) :: BOOLEAN` -| Returns true if the predicate holds for exactly one of the elements in the given `LIST`. - -|=== - - -[[header-query-functions-scalar]] -**xref::functions/scalar.adoc[Scalar functions]** - -These functions return a single value. - -[options="header"] -|=== -| Function | Signature | Description - -1.1+| xref::functions/scalar.adoc#functions-char_length[`char_length()`] -| `char_length(input :: STRING) :: INTEGER` -| Returns the number of Unicode characters in a `STRING`. -label:new[Introduced in 5.13] - -1.1+| xref::functions/scalar.adoc#functions-character_length[`character_length()`] -| `character_length(input :: STRING) :: INTEGER` -| Returns the number of Unicode characters in a `STRING`. -label:new[Introduced in 5.13] -1.1+| xref::functions/scalar.adoc#functions-coalesce[`coalesce()`] -| `coalesce(input :: ANY) :: ANY` -| Returns the first non-null value in a list of expressions. - -1.2+| xref::functions/scalar.adoc#functions-elementid[`elementId()`] -| `elementId(input :: NODE) :: STRING` -| Returns a node identifier, unique within a specific transaction and DBMS. -| `elementId(input :: RELATIONSHIP) :: STRING` -| Returns a relationship identifier, unique within a specific transaction and DBMS. - -1.1+| xref::functions/scalar.adoc#functions-endnode[`endNode()`] -| `endNode(input :: RELATIONSHIP) :: NODE` -| Returns the end `NODE` of a `RELATIONSHIP`. - -1.1+| xref::functions/scalar.adoc#functions-head[`head()`] -| `head(list :: LIST) :: ANY` -| Returns the first element in a `LIST`. - -1.2+| xref::functions/scalar.adoc#functions-id[`id()`] -| `id(input :: NODE) :: INTEGER` -| label:deprecated[] Returns the id of a `NODE`. -Replaced by xref:functions/scalar.adoc#functions-elementid[`elementId()`]. -| `id(input :: RELATIONSHIP) :: INTEGER` -| label:deprecated[] Returns the id of a `RELATIONSHIP`. -Replaced by xref:functions/scalar.adoc#functions-elementid[`elementId()`]. - - -1.1+| xref::functions/scalar.adoc#functions-last[`last()`] -| `last(list :: LIST) :: ANY` -| Returns the last element in a `LIST`. - -1.1+| xref::functions/scalar.adoc#functions-length[`length()`] -| `length(input :: PATH) :: INTEGER` -| Returns the length of a `PATH`. - -1.1+| xref::functions/scalar.adoc#functions-nullIf[`nullIf()`] -| `nullIf(v1 :: ANY, v2 :: ANY) :: ANY` -| Returns null if the two given parameters are equivalent, otherwise returns the value of the first parameter. - -1.3+| xref::functions/scalar.adoc#functions-properties[`properties()`] -| `properties(input :: MAP) :: MAP` -| Returns a `MAP` containing all the properties of a `MAP`. -| `properties(input :: NODE) :: MAP` -| Returns a `MAP` containing all the properties of a `NODE`. -| `properties(input :: RELATIONSHIP) :: MAP` -| Returns a `MAP` containing all the properties of a `RELATIONSHIP`. - -1.1+| xref::functions/scalar.adoc#functions-randomuuid[`randomUUID()`] -| `randomUUID() :: STRING` -| Generates a random UUID. - -1.2+| xref::functions/scalar.adoc#functions-size[`size()`] -| `size(input :: LIST) :: INTEGER` -| Returns the number of items in a `LIST`. -| `size(input :: STRING) :: INTEGER` -| Returns the number of Unicode characters in a `STRING`. - -1.1+| xref::functions/scalar.adoc#functions-startnode[`startNode()`] -| `startNode(input :: RELATIONSHIP) :: NODE` -| Returns the start `NODE` of a `RELATIONSHIP`. - -1.3+| xref::functions/scalar.adoc#functions-toboolean[`toBoolean()`] -| `toBoolean(input :: STRING) :: BOOLEAN` -| Converts a `STRING` value to a `BOOLEAN` value. -| `toBoolean(input :: BOOLEAN) :: BOOLEAN` -| Converts a `BOOLEAN` value to a `BOOLEAN` value. -| `toBoolean(input :: INTEGER) :: BOOLEAN` -| Converts an `INTEGER` value to a `BOOLEAN` value. - -1.1+| xref::functions/scalar.adoc#functions-tobooleanornull[`toBooleanOrNull()`] -| `toBooleanOrNull(input :: ANY) :: BOOLEAN` -| Converts a value to a `BOOLEAN` value, or null if the value cannot be converted. - -1.2+| xref::functions/scalar.adoc#functions-tofloat[`toFloat()`] -| `toFloat(input :: INTEGER \| FLOAT) :: FLOAT` -| Converts an `INTEGER` value to a `FLOAT` value. -| `toFloat(input :: STRING) :: FLOAT` -| Converts a `STRING` value to a `FLOAT` value. - -1.1+| xref::functions/scalar.adoc#functions-tofloatornull[`toFloatOrNull()`] -| `toFloatOrNull(input :: ANY) :: FLOAT` -| Converts a value to a `FLOAT` value, or null if the value cannot be converted. - -1.3+| xref::functions/scalar.adoc#functions-tointeger[`toInteger()`] -| `toInteger(input :: INTEGER \| FLOAT) :: INTEGER` -| Converts a `FLOAT` value to an `INTEGER` value. -| `toInteger(input :: BOOLEAN) :: INTEGER` -| Converts a `BOOLEAN` value to an `INTEGER` value. -| `toInteger(input :: STRING) :: INTEGER` -| Converts a `STRING` value to an `INTEGER` value. -1.1+| xref::functions/scalar.adoc#functions-tointegerornull[`toIntegerOrNull()`] -| `toIntegerOrNull(input :: ANY) :: INTEGER` -| Converts a value to an `INTEGER` value, or null if the value cannot be converted. - -1.1+| xref::functions/scalar.adoc#functions-type[`type()`] -| `type(input :: RELATIONSHIP) :: STRING` -| Returns a `STRING` representation of the `RELATIONSHIP` type. - -1.1+| xref::functions/scalar.adoc#functions-valueType[`valueType()`] -| `valueType(input :: ANY) :: STRING` -| Returns a `STRING` representation of the most precise value type that the given expression evaluates to. - -|=== +For more information about this command, see xref::clauses/listing-functions.adoc[]. +[NOTE] +==== +Functions taking a `STRING` as input all operate on _Unicode characters_ rather than on a standard `char[]`. +For example, the `size()` function applied to any _Unicode character_ will return `1`, even if the character does not fit in the 16 bits of one `char`. +==== [[header-query-functions-aggregating]] -**xref::functions/aggregating.adoc[Aggregating functions]** +== Aggregating functions These functions take multiple values as arguments, and calculate and return an aggregated value from them. @@ -217,13 +30,9 @@ These functions take multiple values as arguments, and calculate and return an a |=== | Function | Signature | Description -1.3+| xref::functions/aggregating.adoc#functions-avg[`avg()`] -| `avg(input :: DURATION) :: DURATION` -| Returns the average of a set of `DURATION` values. -| `avg(input :: FLOAT) :: FLOAT` -| Returns the average of a set of `FLOAT` values. -| `avg(input :: INTEGER) :: INTEGER` -| Returns the average of a set of `INTEGER` values. +1.1+| xref::functions/aggregating.adoc#functions-avg[`avg()`] +| `avg(input :: INTEGER \| FLOAT \| DURATION) :: INTEGER \| FLOAT \| DURATION` +| Returns the average of a set of `INTEGER`, `FLOAT`, or `DURATION` values. 1.1+| xref::functions/aggregating.adoc#functions-collect[`collect()`] | `collect(input :: ANY) :: LIST` @@ -245,33 +54,71 @@ These functions take multiple values as arguments, and calculate and return an a | `percentileCont(input :: FLOAT, percentile :: FLOAT) :: FLOAT` | Returns the percentile of a value over a group using linear interpolation. -1.2+| xref::functions/aggregating.adoc#functions-percentiledisc[`percentileDisc()`] -| `percentileDisc(input :: FLOAT, percentile :: FLOAT) :: FLOAT` -| Returns the nearest `FLOAT` value to the given percentile over a group using a rounding method. -| `percentileDisc(input :: INTEGER, percentile :: FLOAT) :: INTEGER` -| Returns the nearest `INTEGER` value to the given percentile over a group using a rounding method. +1.1+| xref::functions/aggregating.adoc#functions-percentiledisc[`percentileDisc()`] +| `percentileDisc(input :: INTEGER \| FLOAT, percentile :: FLOAT) :: FLOAT` +| Returns the nearest `INTEGER` or `FLOAT` value to the given percentile over a group using a rounding method. -1.1+| xref::functions/aggregating.adoc#functions-stdev[`stdev()`] -| `stdev(input :: FLOAT) :: FLOAT` +1.1+| xref::functions/aggregating.adoc#functions-stdev[`stDev()`] +| `stDev(input :: FLOAT) :: FLOAT` | Returns the standard deviation for the given value over a group for a sample of a population. -1.1+| xref::functions/aggregating.adoc#functions-stdevp[`stdevp()`] -| `stdevp(input :: FLOAT) :: FLOAT` +1.1+| xref::functions/aggregating.adoc#functions-stdevp[`stDevP()`] +| `stDevP(input :: FLOAT) :: FLOAT` | Returns the standard deviation for the given value over a group for an entire population. -1.3+| xref::functions/aggregating.adoc#functions-sum[`sum()`] -| `sum(input :: DURATION) :: DURATION` -| Returns the sum of a set of `DURATION` values. -| `sum(input :: FLOAT) :: FLOAT` -| Returns the sum of a set of `FLOAT` values. -| `sum(input :: INTEGER) :: INTEGER` -| Returns the sum of a set of `INTEGER` values. +1.1+| xref::functions/aggregating.adoc#functions-sum[`sum()`] +| `sum(input :: INTEGER \| FLOAT \| DURATION) :: INTEGER \| FLOAT \| DURATION` +| Returns the sum of a set of `INTEGER`, `FLOAT`, or `DURATION` values. + |=== +[role=label--new-5.12] +[[header-query-functions-database]] +== Database functions + +Database functions provide information about databases. + +[options="header"] +|=== +| Function | Signature | Description +1.1+| xref:functions/database.adoc#functions-database-nameFromElementId[`db.nameFromElementId()`] +| `db.nameFromElementId(elementId :: STRING) :: STRING` +| Resolves the database name from the given element id. +|=== + + +[role=label--new-5.12] +[[header-query-functions-genai]] +== GenAI functions + +[options="header"] +|=== +| Function | Signature | Description +1.1+| xref:genai-integrations.adoc#single-embedding[`genai.vector.encode()`] | `genai.vector.encode(resource :: STRING, provider :: STRING, configuration :: MAP = {}) :: LIST` | Encode a given resource as a vector using the named provider. +|=== + + +[[header-query-functions-graph]] +== Graph functions + +Graph functions provide information about the constituent graphs in composite databases. + +[options="header"] +|=== +| Function | Signature | Description +1.1+| xref:functions/graph.adoc#functions-graph-by-elementid[`graph.byElementId()`] +| `USE graph.byElementId(elementId :: STRING)` +| Resolves the constituent graph to which a given element id belongs. +label:new[Introduced in 5.13] +1.1+| xref:functions/graph.adoc#functions-graph-byname[`graph.byName()`] | `USE graph.byName(name :: STRING)` | Resolves a constituent graph by name. +1.1+| xref:functions/graph.adoc#functions-graph-names[`graph.names()`] | `graph.names() :: LIST` | Returns a list containing the names of all graphs in the current composite database. +1.1+| xref:functions/graph.adoc#functions-graph-names[`graph.propertiesByName()`] | `graph.propertiesByName(name :: STRING) :: MAP` | Returns a map containing the properties associated with the given graph. +|=== + [[header-query-functions-list]] -**xref::functions/list.adoc[List functions]** +== List functions These functions return lists of other values. Further details and examples of lists may be found in xref::values-and-types/lists.adoc[Lists]. @@ -281,13 +128,9 @@ Further details and examples of lists may be found in xref::values-and-types/lis | Function | Signature | Description -1.3+| xref::functions/list.adoc#functions-keys[`keys()`] -| `keys(input :: MAP) :: LIST` -| Returns a `LIST` containing the `STRING` representations for all the property names of a `MAP`. -| `keys(input :: NODE) :: LIST` -| Returns a `LIST` containing the `STRING` representations for all the property names of a `NODE`. -| `keys(input :: RELATIONSHIP) :: LIST` -| Returns a `LIST` containing the `STRING` representations for all the property names of a `RELATIONSHIP`. +1.1+| xref::functions/list.adoc#functions-keys[`keys()`] +| `keys(input :: NODE \| RELATIONSHIP \| MAP) :: LIST` +| Returns a `LIST` containing the `STRING` representations for all the property names of a `MAP`, `NODE`, or `RELATIONSHIP`. 1.1+| xref::functions/list.adoc#functions-labels[`labels()`] | `labels(input :: NODE) :: LIST` @@ -297,14 +140,12 @@ Further details and examples of lists may be found in xref::values-and-types/lis | `nodes(input :: PATH) :: LIST` | Returns a `LIST` containing all the `NODE` values in a `PATH`. -1.2+| xref::functions/list.adoc#functions-range[`range()`] -| `range(start :: INTEGER, end :: INTEGER) :: LIST` -| Returns a `LIST` comprising all `INTEGER` values within a specified range. -| `range(start :: INTEGER, end :: INTEGER, step :: INTEGER) :: LIST` -| Returns a `LIST` comprising all `INTEGER` values within a specified range created with step length. +1.1+| xref::functions/list.adoc#functions-range[`range()`] +| `range(start :: INTEGER, end :: INTEGER [, step :: INTEGER]) :: LIST` +| Returns a `LIST` comprising all `INTEGER` values within a specified range, optionally specifying a step length. 1.1+| xref::functions/list.adoc#functions-reduce[`reduce()`] -| `reduce(accumulator :: VARIABLE = initial :: ANY, variable :: VARIABLE IN list :: LIST \| expression :: ANY) :: ANY` +| `reduce(accumulator :: VARIABLE = initial :: ANY, variable :: VARIABLE IN list :: LIST expression :: ANY) :: ANY` | Runs an expression against individual elements of a `LIST`, storing the result of the expression in an accumulator. 1.1+| xref::functions/list.adoc#functions-relationships[`relationships()`] @@ -346,52 +187,22 @@ If any values are not convertible to `STRING` they will be null in the `LIST, predicate :: ANY) :: BOOLEAN` +| Returns true if the predicate holds for all elements in the given `LIST`. + +1.1+| xref::functions/predicate.adoc#functions-any[`any()`] +| `any(variable :: ANY, list :: LIST, predicate :: ANY) :: BOOLEAN` +| Returns true if the predicate holds for at least one element in the given `LIST`. + +1.1+| xref::functions/predicate.adoc#functions-exists[`exists()`] +| `exists(input :: ANY) :: BOOLEAN` +| Returns `true` if a match for the pattern exists in the graph. + +1.1+| xref::functions/predicate.adoc#functions-isempty[`isEmpty()`] +| `isEmpty(input :: LIST \| MAP \| STRING ) :: BOOLEAN` +| Checks whether the given `LIST`, `MAP`, or `STRING` is empty. + +1.1+| xref::functions/predicate.adoc#functions-none[`none()`] +| `none(variable :: ANY, list :: LIST, predicate :: ANY) :: BOOLEAN` +| Returns true if the predicate holds for no element in the given `LIST`. + +1.1+| xref::functions/predicate.adoc#functions-single[`single()`] +| `single(variable :: ANY, list :: LIST, predicate :: ANY) :: BOOLEAN` +| Returns true if the predicate holds for exactly one of the elements in the given `LIST`. + +|=== + + +[[header-query-functions-scalar]] +== Scalar functions + +These functions return a single value. + +[options="header"] +|=== +| Function | Signature | Description + +1.1+| xref::functions/scalar.adoc#functions-char_length[`char_length()`] +| `char_length(input :: STRING) :: INTEGER` +| Returns the number of Unicode characters in a `STRING`. +label:new[Introduced in 5.13] + +1.1+| xref::functions/scalar.adoc#functions-character_length[`character_length()`] +| `character_length(input :: STRING) :: INTEGER` +| Returns the number of Unicode characters in a `STRING`. +label:new[Introduced in 5.13] + +1.1+| xref::functions/scalar.adoc#functions-coalesce[`coalesce()`] +| `coalesce(input :: ANY) :: ANY` +| Returns the first non-null value in a list of expressions. + +1.+| xref::functions/scalar.adoc#functions-elementid[`elementId()`] +| `elementId(input :: NODE \| RELATIONSHIP) :: STRING` +| Returns a node or relationship identifier, unique within a specific transaction and DBMS. + +1.1+| xref::functions/scalar.adoc#functions-endnode[`endNode()`] +| `endNode(input :: RELATIONSHIP) :: NODE` +| Returns the end `NODE` of a `RELATIONSHIP`. + +1.1+| xref::functions/scalar.adoc#functions-head[`head()`] +| `head(list :: LIST) :: ANY` +| Returns the first element in a `LIST`. + +1.1+| xref::functions/scalar.adoc#functions-id[`id()`] +| `id(input :: NODE \| RELATIONSHIP) :: INTEGER` +| label:deprecated[] Returns the id of a `NODE` or a `RELATIONSHIP`. +Replaced by xref:functions/scalar.adoc#functions-elementid[`elementId()`]. + +1.1+| xref::functions/scalar.adoc#functions-last[`last()`] +| `last(list :: LIST) :: ANY` +| Returns the last element in a `LIST`. + +1.1+| xref::functions/scalar.adoc#functions-length[`length()`] +| `length(input :: PATH) :: INTEGER` +| Returns the length of a `PATH`. + +1.1+| xref::functions/scalar.adoc#functions-nullIf[`nullIf()`] +| `nullIf(v1 :: ANY, v2 :: ANY) :: ANY` +| Returns `null` if the two given parameters are equivalent, otherwise returns the value of the first parameter. + +1.1+| xref::functions/scalar.adoc#functions-properties[`properties()`] +| `properties(input :: NODE \| RELATIONSHIP \| MAP) :: MAP` +| Returns a `MAP` containing all the properties of a `NODE` or `RELATIONSHIP`. + +1.1+| xref::functions/scalar.adoc#functions-randomuuid[`randomUUID()`] +| `randomUUID() :: STRING` +| Generates a random UUID. + +1.1+| xref::functions/scalar.adoc#functions-size[`size()`] +| `size(input STRING \| LIST) :: INTEGER` +| Returns the number of items in a `LIST` or the number of Unicode characters in a `STRING`. + +1.1+| xref::functions/scalar.adoc#functions-startnode[`startNode()`] +| `startNode(input :: RELATIONSHIP) :: NODE` +| Returns the start `NODE` of a `RELATIONSHIP`. + +1.1+| xref::functions/scalar.adoc#functions-toboolean[`toBoolean()`] +| `toBoolean(input :: BOOLEAN \| STRING \| INTEGER) :: BOOLEAN` +| Converts a `BOOLEAN`, `STRING`, or an `INTEGER` value to a `BOOLEAN` value. + +1.1+| xref::functions/scalar.adoc#functions-tobooleanornull[`toBooleanOrNull()`] +| `toBooleanOrNull(input :: ANY) :: BOOLEAN` +| Converts a value to a `BOOLEAN` value, or null if the value cannot be converted. + +1.1+| xref::functions/scalar.adoc#functions-tofloat[`toFloat()`] +| `toFloat(input :: STRING \| INTEGER \| FLOAT) :: FLOAT` +| Converts a `STRING` or `INTEGER` value to a `FLOAT` value. + +1.1+| xref::functions/scalar.adoc#functions-tofloatornull[`toFloatOrNull()`] +| `toFloatOrNull(input :: ANY) :: FLOAT` +| Converts a value to a `FLOAT` value, or null if the value cannot be converted. + +1.1+| xref::functions/scalar.adoc#functions-tointeger[`toInteger()`] +| `toInteger(input :: BOOLEAN \| STRING \| INTEGER \| FLOAT) :: INTEGER` +| Converts a `BOOLEAN, `STRING`, or `FLOAT` value to an `INTEGER` value. + +1.1+| xref::functions/scalar.adoc#functions-tointegerornull[`toIntegerOrNull()`] +| `toIntegerOrNull(input :: ANY) :: INTEGER` +| Converts a value to an `INTEGER` value, or null if the value cannot be converted. + +1.1+| xref::functions/scalar.adoc#functions-type[`type()`] +| `type(input :: RELATIONSHIP) :: STRING` +| Returns a `STRING` representation of the `RELATIONSHIP` type. + +1.1+| xref::functions/scalar.adoc#functions-valueType[`valueType()`] +| `valueType(input :: ANY) :: STRING` +| Returns a `STRING` representation of the most precise value type that the given expression evaluates to. + +|=== + + [[header-query-functions-string]] -**xref::functions/string.adoc[String functions]** +== String functions These functions are used to manipulate `STRING` values or to create a `STRING` representation of another value. @@ -499,11 +489,9 @@ These functions are used to manipulate `STRING` values or to create a `STRING` r |=== | Function | Signature | Description -1.2+| xref::functions/string.adoc#functions-btrim[`btrim()`] -| `btrim(original :: STRING) :: STRING` -| Returns the given `STRING` with leading and trailing whitespace removed. label:new[Introduced in 5.20] -| `btrim(input :: STRING, trimCharacterString :: STRING) :: STRING` -| Returns the given `STRING` with leading and trailing `trimCharacterString` characters removed. label:new[Introduced in 5.20] +1.1+| xref::functions/string.adoc#functions-btrim[`btrim()`] +| `btrim(original :: STRING [, trimCharacterString :: STRING ]) :: STRING` +| Returns the given `STRING` with leading and trailing whitespace removed, optionally specifying a `trimCharacterString` value to remove. label:new[Introduced in 5.20] 1.1+| xref::functions/string.adoc#functions-left[`left()`] | `left(original :: STRING, length :: INTEGER) :: STRING` @@ -513,17 +501,13 @@ These functions are used to manipulate `STRING` values or to create a `STRING` r | `lower(input :: STRING) :: STRING` | Returns the given `STRING` in lowercase. This function is an alias to the xref:functions/string.adoc#functions-tolower[`toLower()`] function, and it was introduced as part of Cypher's xref:appendix/gql-conformance/index.adoc[]. label:new[Introduced in 5.21] -1.2+| xref::functions/string.adoc#functions-ltrim[`ltrim()`] -| `ltrim(input :: STRING) :: STRING` -| Returns the given `STRING` with leading whitespace removed. -| `ltrim(input :: STRING, trimCharacterString :: STRING) :: STRING` -| Returns the given `STRING` with leading `trimCharacterString` characters removed. label:new[Introduced in 5.20] +1.1+| xref::functions/string.adoc#functions-ltrim[`ltrim()`] +| `ltrim(input :: STRING [, trimCharacterString :: STRING]) :: STRING` +| Returns the given `STRING` with leading whitespace removed, optionally specifying a `trimCharacterString` to remove. -1.2+| xref::functions/string.adoc#functions-normalize[`normalize()`] -| `normalize(input :: STRING) :: STRING` -| Returns the given `STRING` normalized according to the normalization form `NFC`. label:new[Introduced in 5.17] -| `normalize(input :: STRING, normalForm = NFC :: [NFC, NFD, NFKC, NFKD]) :: STRING` -| Returns the given `STRING` normalized according to the specified normalization form. label:new[Introduced in 5.17] +1.1+| xref::functions/string.adoc#functions-normalize[`normalize()`] +| `normalize(input :: STRING [,normalForm = NFC :: [NFC, NFD, NFKC, NFKD]]) :: STRING` +| Normalizes a `STRING`, optionally specifying a normalization form. label:new[Introduced in 5.17] 1.1+| xref::functions/string.adoc#functions-replace[`replace()`] | `replace(original :: STRING, search :: STRING, replace :: STRING) :: STRING` @@ -537,22 +521,16 @@ These functions are used to manipulate `STRING` values or to create a `STRING` r | `right(original :: STRING, length :: INTEGER) :: STRING` | Returns a `STRING` containing the specified number of rightmost characters in the given `STRING`. -1.2+| xref::functions/string.adoc#functions-rtrim[`rtrim()`] -| `rtrim(input :: STRING) :: STRING` -| Returns the given `STRING` with trailing whitespace removed. -| `rtrim(input :: STRING, trimCharacterString :: STRING) :: STRING` -| Returns the given `STRING` with trailing `trimCharacterString` characters removed. label:new[Introduced in 5.20] +1.1+| xref::functions/string.adoc#functions-rtrim[`rtrim()`] +| `rtrim(input :: STRING [, trimCharacterString :: STRING]) :: STRING` +| Returns the given `STRING` with trailing whitespace removed, optionally specifying a `trimCharacterString` of characters to remove. -1.2+| xref::functions/string.adoc#functions-split[`split()`] -| `split(original :: STRING, splitDelimiter :: STRING) :: LIST` -| Returns a `LIST` resulting from the splitting of the given `STRING` around matches of the given delimiter. +1.1+| xref::functions/string.adoc#functions-split[`split()`] | `split(original :: STRING, splitDelimiters :: LIST) :: LIST` | Returns a `LIST` resulting from the splitting of the given `STRING` around matches of any of the given delimiters. -1.2+| xref::functions/string.adoc#functions-substring[`substring()`] -| `substring(original :: STRING, start :: INTEGER) :: STRING` -| Returns a substring of the given `STRING`, beginning with a 0-based index start. -| `substring(original :: STRING, start :: INTEGER, length :: INTEGER) :: STRING` +1.1+| xref::functions/string.adoc#functions-substring[`substring()`] +| `substring(original :: STRING, start :: INTEGER length :: INTEGER) :: STRING` | Returns a substring of a given `length` from the given `STRING`, beginning with a 0-based index start. 1.1+| xref::functions/string.adoc#functions-tolower[`toLower()`] @@ -571,20 +549,72 @@ These functions are used to manipulate `STRING` values or to create a `STRING` r | `toUpper(input :: STRING) :: STRING` | Returns the given `STRING` in uppercase. -1.2+| xref::functions/string.adoc#functions-trim[`trim()`] -| `trim(input :: STRING) :: STRING` -| Returns the given `STRING` with leading and trailing whitespace removed. -| `trim([[LEADING \| TRAILING \| BOTH] [trimCharacterString :: STRING] FROM] input :: STRING) :: STRING` -| Returns the given `STRING` with the leading and/or trailing `trimCharacterString` character removed. label:new[Introduced in 5.20] +1.1+| xref::functions/string.adoc#functions-trim[`trim()`] +| `trim(trimCharacterString :: STRING, trimSpecification :: STRING, input :: STRING) :: STRING` +| Returns the given `STRING` with the leading and/or trailing `trimCharacterString` character removed. 1.1+| xref::functions/string.adoc#functions-upper[`upper()`] | `upper(input :: STRING) :: STRING` | Returns the given `STRING` in uppercase. This function is an alias to the xref:functions/string.adoc#functions-toupper[`toUpper()`] function, and it was introduced as part of Cypher's xref:appendix/gql-conformance/index.adoc[]. label:new[Introduced in 5.21] |=== +[[header-query-functions-spatial]] +== Spatial functions + +These functions are used to specify 2D or 3D points in a geographic or cartesian Coordinate Reference System and to calculate the geodesic distance between two points. + +[options="header"] +|=== +| Function | Signature | Description + +1.1+| xref::functions/spatial.adoc#functions-point-cartesian-2d[`point()`] +| `point(input :: MAP) :: POINT` +| Returns a 2D or 3D point object, given two or respectively three coordinate values in the Cartesian coordinate system or WGS 84 geographic coordinate system. + +1.1+| xref::functions/spatial.adoc#functions-distance[`point.distance()`] +| `point.distance(from :: POINT, to :: POINT) :: FLOAT` +| Returns a `FLOAT` representing the geodesic distance between any two points in the same CRS. + +1.1+| xref::functions/spatial.adoc#functions-withinBBox[`point.withinBBox()`] +| `point.withinBBox(point :: POINT, lowerLeft :: POINT, upperRight :: POINT) :: BOOLEAN` +| Returns `true` if the provided point is within the bounding box defined by the two provided points, `lowerLeft` and `upperRight`. + +|=== + + +[[header-query-functions-temporal-duration]] +== Temporal duration functions + +`DURATION` values of the xref::values-and-types/temporal.adoc[temporal types] can be created manipulated using the following functions: + +[options="header"] +|=== +| Function | Signature | Description + +1.1+| xref::functions/temporal/duration.adoc#functions-duration[`duration()`] +| `duration(input :: ANY) :: DURATION` +| Constructs a `DURATION` value. + +1.1+| xref::functions/temporal/duration.adoc#functions-duration-between[`duration.between()`] +| `duration.between(from :: ANY, to :: ANY) :: DURATION` +| Computes the `DURATION` between the `from` instant (inclusive) and the `to` instant (exclusive) in logical units. + +1.1+| xref::functions/temporal/duration.adoc#functions-duration-indays[`duration.inDays()`] +| `duration.inDays(from :: ANY, to :: ANY) :: DURATION` +| Computes the `DURATION` between the `from` instant (inclusive) and the `to` instant (exclusive) in days. + +1.1+| xref::functions/temporal/duration.adoc#functions-duration-inmonths[`duration.inMonths()`] +| `duration.inMonths(from :: ANY, to :: ANY) :: DURATION` +| Computes the `DURATION` between the `from` instant (inclusive) and the `to` instant (exclusive) in months. + +1.1+| xref::functions/temporal/duration.adoc#functions-duration-inseconds[`duration.inSeconds()`] +| `duration.inSeconds(from :: ANY, to :: ANY) :: DURATION` +| Computes the `DURATION` between the `from` instant (inclusive) and the `to` instant (exclusive) in seconds. + +|=== [[header-query-functions-temporal-instant-types]] -**xref::functions/temporal/index.adoc[Temporal instant types functions]** +== Temporal instant types functions Values of the xref::values-and-types/temporal.adoc[temporal types] -- `DATE`, `ZONED TIME`, `LOCAL TIME`, `ZONED DATETIME`, and `LOCAL DATETIME` -- can be created manipulated using the following functions: @@ -703,76 +733,31 @@ Values of the xref::values-and-types/temporal.adoc[temporal types] -- `DATE`, `Z |=== -[[header-query-functions-temporal-duration]] -**xref::functions/temporal/duration.adoc[Temporal duration functions]** - -`DURATION` values of the xref::values-and-types/temporal.adoc[temporal types] can be created manipulated using the following functions: - -[options="header"] -|=== -| Function | Signature | Description - -1.1+| xref::functions/temporal/duration.adoc#functions-duration[`duration()`] -| `duration(input :: ANY) :: DURATION` -| Constructs a `DURATION` value. - -1.1+| xref::functions/temporal/duration.adoc#functions-duration-between[`duration.between()`] -| `duration.between(from :: ANY, to :: ANY) :: DURATION` -| Computes the `DURATION` between the `from` instant (inclusive) and the `to` instant (exclusive) in logical units. - -1.1+| xref::functions/temporal/duration.adoc#functions-duration-indays[`duration.inDays()`] -| `duration.inDays(from :: ANY, to :: ANY) :: DURATION` -| Computes the `DURATION` between the `from` instant (inclusive) and the `to` instant (exclusive) in days. - -1.1+| xref::functions/temporal/duration.adoc#functions-duration-inmonths[`duration.inMonths()`] -| `duration.inMonths(from :: ANY, to :: ANY) :: DURATION` -| Computes the `DURATION` between the `from` instant (inclusive) and the `to` instant (exclusive) in months. - -1.1+| xref::functions/temporal/duration.adoc#functions-duration-inseconds[`duration.inSeconds()`] -| `duration.inSeconds(from :: ANY, to :: ANY) :: DURATION` -| Computes the `DURATION` between the `from` instant (inclusive) and the `to` instant (exclusive) in seconds. - -|=== - - -[[header-query-functions-spatial]] -**xref::functions/spatial.adoc[Spatial functions]** +[[header-query-functions-user-defined]] +== User-defined functions -These functions are used to specify 2D or 3D points in a geographic or cartesian Coordinate Reference System and to calculate the geodesic distance between two points. +User-defined functions are written in Java, deployed into the database and are called in the same way as any other Cypher function. +There are two main types of functions that can be developed and used: [options="header"] |=== -| Function | Signature | Description - -1.1+| xref::functions/spatial.adoc#functions-distance[`point.distance()`] -| `point.distance(from :: POINT, to :: POINT) :: FLOAT` -| Returns a `FLOAT` representing the geodesic distance between any two points in the same CRS. - -1.1+| xref::functions/spatial.adoc#functions-point-cartesian-2d[`point()` - Cartesian 2D] -| `point(input :: MAP) :: POINT` -| Returns a 2D point object, given two coordinate values in the Cartesian coordinate system. - -1.1+| xref::functions/spatial.adoc#functions-point-cartesian-3d[`point()` - Cartesian 3D] -| `point(input :: MAP) :: POINT` -| Returns a 3D point object, given three coordinate values in the Cartesian coordinate system. - -1.1+| xref::functions/spatial.adoc#functions-point-wgs84-2d[`point()` - WGS 84 2D] -| `point(input :: MAP) :: POINT` -| Returns a 2D point object, given two coordinate values in the WGS 84 geographic coordinate system. +| Type | Description | Usage | Developing -1.1+| xref::functions/spatial.adoc#functions-point-wgs84-3d[`point()` - WGS 84 3D] -| `point(input :: MAP) :: POINT` -| Returns a 3D point object, given three coordinate values in the WGS 84 geographic coordinate system. +| Scalar +| For each row the function takes parameters and returns a result. +| xref::functions/user-defined.adoc#query-functions-udf[Using UDF] +| link:{neo4j-docs-base-uri}/java-reference/{page-version}/extending-neo4j/functions#extending-neo4j-functions[Extending Neo4j (UDF)] -1.1+| xref::functions/spatial.adoc#functions-withinBBox[`point.withinBBox()`] -| `point.withinBBox(point :: POINT, lowerLeft :: POINT, upperRight :: POINT) :: BOOLEAN` -| Returns `true` if the provided point is within the bounding box defined by the two provided points, `lowerLeft` and `upperRight`. +| Aggregating +| Consumes many rows and produces an aggregated result. +| xref::functions/user-defined.adoc#query-functions-user-defined-aggregation[Using aggregating UDF] +| link:{neo4j-docs-base-uri}/java-reference/{page-version}/extending-neo4j/aggregation-functions#extending-neo4j-aggregation-functions[Extending Neo4j (Aggregating UDF)] |=== - +[role=label--new-5.18] [[header-query-functions-vector]] -**xref::functions/vector.adoc[Vector functions]** label:new[Introduced in 5.18] +== Vector functions Vector functions allow you to compute the similarity scores of vector pairs. @@ -789,85 +774,3 @@ Vector functions allow you to compute the similarity scores of vector pairs. | Returns a `FLOAT` representing the similarity between the argument vectors based on their Euclidean distance. |=== - - -[[header-query-functions-load-csv]] -**xref::functions/load-csv.adoc[LOAD CSV functions]** - -LOAD CSV functions can be used to get information about the file that is processed by `LOAD CSV`. - -[options="header"] -|=== -| Function | Signature | Description - -1.1+| xref::functions/load-csv.adoc#functions-file[`file()`] -| `file() :: STRING` -| Returns the absolute path of the file that LOAD CSV is using. - -1.1+| xref::functions/load-csv.adoc#functions-linenumber[`linenumber()`] -| `linenumber() :: INTEGER` -| Returns the line number that LOAD CSV is currently using. - -|=== - - -[[header-query-functions-graph]] -**xref::functions/graph.adoc[Graph functions]** - -Graph functions provide information about the constituent graphs in composite databases. - -[options="header"] -|=== -| Function | Signature | Description -1.1+| xref:functions/graph.adoc#functions-graph-by-elementid[`graph.byElementId()`] | `USE graph.byElementId(elementId :: STRING)` | Resolves the constituent graph to which a given element id belongs. -label:new[Introduced in 5.13] -1.1+| xref:functions/graph.adoc#functions-graph-byname[`graph.byName()`] | `USE graph.byName(name :: STRING)` | Resolves a constituent graph by name. -1.1+| xref:functions/graph.adoc#functions-graph-names[`graph.names()`] | `graph.names() :: LIST` | Returns a list containing the names of all graphs in the current composite database. -1.1+| xref:functions/graph.adoc#functions-graph-names[`graph.propertiesByName()`] | `graph.propertiesByName(name :: STRING) :: MAP` | Returns a map containing the properties associated with the given graph. -|=== - -[[header-query-functions-database]] -**xref::functions/database.adoc[Database functions]** label:new[Introduced in 5.12] - -Database functions provide information about databases. - -[options="header"] -|=== -| Function | Signature | Description -1.1+| xref:functions/database.adoc#functions-database-nameFromElementId[`db.nameFromElementId()`] | `db.nameFromElementId(name :: STRING) :: STRING` | Resolves the database name from the given element id. -label:new[Introduced in 5.12] -|=== - -[[header-query-functions-genai]] -**xref::genai-integrations.adoc#single-embedding[GenAI function]** label:new[Introduced in 5.17] - -This function is used to generate a vector embedding for a single value. - -[options="header"] -|=== -| Function | Signature | Description -1.1+| xref:genai-integrations.adoc#single-embedding[`genai.vector.encode()`] | `genai.vector.encode(resource :: STRING, provider :: STRING, configuration :: MAP = {}) :: LIST` | Encode a given resource as a vector using the named provider. -|=== - -[[header-query-functions-user-defined]] -**xref::functions/user-defined.adoc[User-defined functions]** - -User-defined functions are written in Java, deployed into the database and are called in the same way as any other Cypher function. -There are two main types of functions that can be developed and used: - -[options="header"] -|=== -| Type | Description | Usage | Developing - -| Scalar -| For each row the function takes parameters and returns a result. -| xref::functions/user-defined.adoc#query-functions-udf[Using UDF] -| link:{neo4j-docs-base-uri}/java-reference/{page-version}/extending-neo4j/functions#extending-neo4j-functions[Extending Neo4j (UDF)] - -| Aggregating -| Consumes many rows and produces an aggregated result. -| xref::functions/user-defined.adoc#query-functions-user-defined-aggregation[Using aggregating UDF] -| link:{neo4j-docs-base-uri}/java-reference/{page-version}/extending-neo4j/aggregation-functions#extending-neo4j-aggregation-functions[Extending Neo4j (Aggregating UDF)] - -|=== - diff --git a/modules/ROOT/pages/functions/list.adoc b/modules/ROOT/pages/functions/list.adoc index b118c9d60..1ff0cd547 100644 --- a/modules/ROOT/pages/functions/list.adoc +++ b/modules/ROOT/pages/functions/list.adoc @@ -1,4 +1,5 @@ :description: List functions return lists of things -- nodes in a path, and so on. +:table-caption!: [[query-functions-list]] = List functions @@ -7,22 +8,23 @@ List functions return lists of different data entities. Further details and examples of lists may be found in xref::values-and-types/lists.adoc[Lists] and xref::syntax/operators.adoc#query-operators-list[List operators]. +[[example-graph]] == Example graph The following graph is used for the examples below: -image:graph_list_functions.svg[] +image::graph_list_functions.svg[role="middle", width="700"] -To recreate the graph, run the following query in an empty Neo4j database: +To recreate the graph, run the following query against an empty Neo4j database: [source, cypher, role=test-setup] ---- CREATE - (alice:Person:Developer {name:'Alice', age: 38, eyes: 'brown'}), - (bob {name: 'Bob', age: 25, eyes: 'blue'}), - (charlie {name: 'Charlie', age: 53, eyes: 'green'}), - (daniel {name: 'Daniel', age: 54, eyes: 'brown'}), - (eskil {name: 'Eskil', age: 41, eyes: 'blue', array: ['one', 'two', 'three']}), + (alice:Developer {name:'Alice', age: 38, eyes: 'Brown'}), + (bob:Administrator {name: 'Bob', age: 25, eyes: 'Blue'}), + (charlie:Administrator {name: 'Charlie', age: 53, eyes: 'Green'}), + (daniel:Adminstrator {name: 'Daniel', age: 54, eyes: 'Brown'}), + (eskil:Designer {name: 'Eskil', age: 41, eyes: 'blue', likedColors: ['Pink', 'Yellow', 'Black']}), (alice)-[:KNOWS]->(bob), (alice)-[:KNOWS]->(charlie), (bob)-[:KNOWS]->(daniel), @@ -33,36 +35,16 @@ CREATE [[functions-keys]] == keys() -`keys` returns a `LIST` containing the `STRING` representations for all the property names of a `NODE`, `RELATIONSHIP`, or `MAP`. - -*Syntax:* - -[source, syntax, role="noheader"] ----- -keys(expression) ----- - -*Returns:* - -|=== - -| `LIST` - -|=== - -*Arguments:* - -[options="header"] +.Details |=== -| Name | Description - -| `expression` -| An expression that returns a `NODE`, `RELATIONSHIP`, or `MAP`. - +| *Syntax* 3+| `keys(input)` +| *Description* 3+| Returns a `LIST` containing the `STRING` representations for all the property names of a `NODE`, `RELATIONSHIP` or `MAP`. +.2+| *Arguments* | *Name* | *Type* | *Description* +| `input` | `NODE \| RELATIONSHIP \| MAP` | A node or relationship from which the names of all properties will be returned. +| *Returns* 3+| `LIST` |=== -*Considerations:* - +.Considerations |=== | `keys(null)` returns `null`. @@ -86,8 +68,8 @@ A `LIST` containing the names of all the properties on the node bound to [role="queryresult",options="header,footer",cols="1*` containing the names of all the properties on the node bound to [[functions-labels]] == labels() -`labels` returns a `LIST` containing the string representations for all the labels of a `NODE`. - -[NOTE] -The order of the returned labels is not guanteed when using the `labels()` function. - -*Syntax:* - -[source, syntax, role="noheader"] ----- -labels(node) ----- - -*Returns:* - +.Details |=== - -| `LIST` - +| *Syntax* 3+| `labels(input)` +| *Description* 3+| Returns a `LIST` containing the `STRING` representations for all the labels of a `NODE`. +.2+| *Arguments* | *Name* | *Type* | *Description* +| `input` | `NODE` | A node whose labels will be returned. +| *Returns* 3+| `LIST` |=== -*Arguments:* - -[options="header"] -|=== -| Name | Description - -| `node` -| An expression that returns a single `NODE`. - -|=== - -*Considerations:* +.Considerations |=== | `labels(null)` returns `null`. +| The order of the returned labels is not guaranteed when using the `labels()` function. |=== @@ -154,8 +115,8 @@ A `LIST` containing all the labels of the node bound to `a` is returned. [role="queryresult",options="header,footer",cols="1*` containing all the labels of the node bound to `a` is returned. [[functions-nodes]] == nodes() -`nodes()` returns a `LIST` containing all the `NODE` values in a `PATH`. - -*Syntax:* - -[source, syntax, role="noheader"] ----- -nodes(path) ----- - -*Returns:* - +.Details |=== - -| `LIST` - -|=== - -*Arguments:* - -[options="header"] +| *Syntax* 3+| `nodes(input)` +| *Description* 3+| Returns a `LIST` containing all the `NODE` values in a `PATH`. +.2+| *Arguments* | *Name* | *Type* | *Description* +| `input` | `PATH` | A path whose nodes will be returned. +| *Returns* 3+| `LIST` |=== -| Name | Description - -| `path` -| An expression that returns a `PATH`. - -|=== - -*Considerations:* +.Considerations |=== | `nodes(null)` returns `null`. @@ -220,8 +161,8 @@ A `LIST` containing all the nodes in the path `p` is returned. [role="queryresult",options="header,footer",cols="1*` containing all the nodes in the path `p` is returned. [[functions-range]] == range() -`range()` returns a `LIST` comprising all `INTEGER` values within a range bounded by a `start` value and an `end` value, where the difference `step` between any two consecutive values is constant; i.e. an arithmetic progression. -To create ranges with decreasing `INTEGER` values, use a negative value `step`. -The range is inclusive for non-empty ranges, and the arithmetic progression will therefore always contain `start` and -- depending on the values of `start`, `step` and `end` -- `end`. -The only exception where the range does not contain `start` are empty ranges. -An empty range will be returned if the value `step` is negative and `start - end` is positive, or vice versa, e.g. `range(0, 5, -1)`. - -*Syntax:* - -[source, syntax, role="noheader"] ----- -range(start, end [, step]) ----- - -*Returns:* - +.Details |=== - -| `LIST` - +| *Syntax* 3+| `range(start, end [, step])` +| *Description* 3+| Returns a `LIST` comprising all `INTEGER` values within a specified range created with step length, optionally specifying a step length. +.4+| *Arguments* | *Name* | *Type* | *Description* +| `start` | `INTEGER` | The start value of the range. +| `end` | `INTEGER` | The end value of the range. +| `step` | `INTEGER` | The size of the increment (default value: 1). +| *Returns* 3+| `LIST` |=== -*Arguments:* - -[options="header"] +.Considerations |=== -| Name | Description - -| `start` -| An expression that returns an `INTEGER` value. - -| `end` -| An expression that returns an `INTEGER` value. - -| `step` -| A numeric expression defining the difference between any two consecutive values, with a default of `1`. - +| To create ranges with decreasing `INTEGER` values, use a negative value `step`. +| The range is inclusive for non-empty ranges, and the arithmetic progression will therefore always contain `start` and -- depending on the values of `start`, `step` and `end` -- `end`. +The only exception where the range does not contain `start` are empty ranges. +| An empty range will be returned if the value `step` is negative and `start - end` is positive, or vice versa, e.g. `range(0, 5, -1)`. |=== @@ -286,8 +208,8 @@ Three lists of numbers in the given ranges are returned. [role="queryresult",options="header,footer",cols="3*`, storing the result of the expression in an accumulator. +.3+| *Arguments* | *Name* | *Type* | *Description* +| `accumulator` | `ANY` | A variable that holds the result as the list is iterated. +| `variable` | `LIST` | A variable that can be used within the reducing expression. +| *Returns* 3+| `ANY` |=== -*Arguments:* - -[options="header"] -|=== -| Name | Description - -| `accumulator` -| A variable that will hold the result and the partial results as the list is iterated. - -| `initial` -| An expression that runs once to give a starting value to the accumulator. - -| `list` -| An expression that returns a `LIST`. - -| `variable` -| The closure will have a variable introduced in its context. We decide here which variable to use. - -| `expression` -| This expression will run once per value in the list, and produce the result value. - -|=== +This function is analogous to the `fold` or `reduce` method in functional languages such as Lisp and Scala. .+reduce()+ @@ -358,8 +250,8 @@ The `age` property of all `NODE` values in the `PATH` are summed and returned as [role="queryresult",options="header,footer",cols="1*` containing all the `RELATIONSHIP` values in a `PATH`.. - -*Syntax:* - -[source, syntax, role="noheader"] ----- -relationships(path) ----- - -*Returns:* - +.Details |=== - -| `LIST` - +| *Syntax* 3+| `relationships(input)` +| *Description* 3+| Returns a `LIST` containing all the `RELATIONSHIP` values in a `PATH`. +.2+| *Arguments* | *Name* | *Type* | *Description* +| `input` | `PATH` | The path from which all relationships will be returned. +| *Returns* 3+| `LIST` |=== -*Arguments:* - -[options="header"] -|=== -| Name | Description - -| `path` -| An expression that returns a `PATH`. - -|=== - -*Considerations:* - +.Considerations |=== | `relationships(null)` returns `null`. @@ -436,38 +308,20 @@ A `LIST` containing all the `RELATIONSHIP` values in the `PATH` `p [[functions-reverse-list]] == reverse() -`reverse()` returns a `LIST` in which the order of all elements in the given `LIST` have been reversed. - -*Syntax:* - -[source, syntax, role="noheader"] ----- -reverse(original) ----- - -*Returns:* - +.Details |=== - -| A `LIST` containing homogeneous or heterogeneous elements; the types of the elements are determined by the elements within `original`. - -|=== - -*Arguments:* -[options="header"] -|=== -| Name | Description - -| `original` -| An expression that returns a `LIST`. - +| *Syntax* 3+| `reverse(input)` +| *Description* 3+| Returns a `STRING` or `LIST` in which the order of all characters or elements in the given `STRING` or `LIST` have been reversed. +.2+| *Arguments* | *Name* | *Type* | *Description* +| `input` | `STRING \| LIST` | The string or list to be reversed. +| *Returns* 3+| `STRING \| LIST` |=== -*Considerations:* - +.Considerations |=== | Any `null` element in `original` is preserved. +| See also xref:functions/string.adoc#functions-reverse[String functions -> reverse]. |=== @@ -486,8 +340,8 @@ RETURN reverse(ids) [role="queryresult",options="header,footer",cols="1*,521,"abc",4923]+ +| reverse(ids) +| [487,,521,"abc",4923] 1+d|Rows: 1 |=== @@ -498,33 +352,14 @@ RETURN reverse(ids) [[functions-tail]] == tail() -`tail()` returns a `LIST` `l~result~` containing all the elements, excluding the first one, from a list `list`. - -*Syntax:* - -[source, syntax, role="noheader"] ----- -tail(list) ----- - -*Returns:* - -|=== - -| A `LIST` containing heterogeneous elements; the types of the elements are determined by the elements in `list`. - +.Details |=== - -*Arguments:* -[options="header"] +| *Syntax* 3+| `tail(input)` +| *Description* 3+| Returns all but the first element in a `LIST`. +.2+| *Arguments* | *Name* | *Type* | *Description* +| `input` | `LIST` | A list from which all but the first element will be returned. +| *Returns* 3+| `LIST` |=== -| Name | Description - -| `list` -| An expression that returns a `LIST`. - -|=== - .+tail()+ ====== @@ -533,17 +368,17 @@ tail(list) [source, cypher] ---- MATCH (a) WHERE a.name = 'Eskil' -RETURN a.array, tail(a.array) +RETURN a.likedColors, tail(a.likedColors) ---- -The property named `array` and a `LIST` comprising all but the first element of the `array` property are returned. +The property named `likedColors` and a `LIST` comprising all but the first element of the `likedColors` property are returned. .Result [role="queryresult",options="header,footer",cols="2*` comprising all but the first elemen [[functions-tobooleanlist]] == toBooleanList() -`toBooleanList()` converts a `LIST` and returns a `LIST`. -If any values are not convertible to `BOOLEAN` they will be `null` in the `LIST` returned. - -*Syntax:* - -[source, syntax, role="noheader"] ----- -toBooleanList(list) ----- - -*Returns:* - +.Details |=== - -| A `LIST` containing the converted elements; depending on the input value a converted value is either a `BOOLEAN` value or `null`. - +| *Syntax* 3+| `toBooleanList(input)` +| *Description* 3+| Converts a `LIST` of values to a `LIST` values. If any values are not convertible to `BOOLEAN` they will be null in the `LIST` returned. +.2+| *Arguments* | *Name* | *Type* | *Description* +| `input` | `LIST` | A list of values to be converted into a list of booleans. +| *Returns* 3+| `LIST` |=== -*Arguments:* -[options="header"] +.Considerations |=== -| Name | Description -| `list` -| An expression that returns a `LIST`. - -|=== - -*Considerations:* - -|=== - -| Any `null` element in `list` is preserved. -| Any `BOOLEAN` value in `list` is preserved. -| If the `list` is `null`, `null` will be returned. -| If the `list` is not a `LIST`, an error will be returned. +| Any `null` element in `input` is preserved. +| Any `BOOLEAN` value in `input` is preserved. +| If the `input` is `null`, `null` will be returned. +| If the `input` is not a `LIST`, an error will be returned. | The conversion for each value in `list` is done according to the xref::functions/scalar.adoc#functions-tobooleanornull[`toBooleanOrNull()` function]. |=== @@ -610,8 +425,8 @@ toBooleanList(['a string', true, 'false', null, ['A','B']]) as mixedList [role="queryresult",options="header,footer",cols="3*+ | +[,]+ | +[,true,false,,]+ +| noList | nullsInList | mixedList +| | [,] | [,true,false,,] 3+d|Rows: 1 |=== @@ -622,43 +437,23 @@ toBooleanList(['a string', true, 'false', null, ['A','B']]) as mixedList [[functions-tofloatlist]] == toFloatList() -`toFloatList()` converts a `LIST` of values and returns a `LIST`. -If any values are not convertible to `FLOAT` they will be `null` in the `LIST` returned. - -*Syntax:* - -[source, syntax, role="noheader"] ----- -toFloatList(list) ----- - -*Returns:* - -|=== - -| A `LIST` containing the converted elements; depending on the input value a converted value is either a `FLOAT` value or `null`. - -|=== - -*Arguments:* -[options="header"] +.Details |=== -| Name | Description - -| `list` -| An expression that returns a `LIST`. - +| *Syntax* 3+| `toFloatList(input)` +| *Description* 3+| Converts a `LIST` to a `LIST` values. If any values are not convertible to `FLOAT` they will be null in the `LIST` returned. +.2+| *Arguments* | *Name* | *Type* | *Description* +| `input` | `LIST` | A list of values to be converted into a list of floats. +| *Returns* 3+| `LIST` |=== -*Considerations:* - +.Considerations |=== | Any `null` element in `list` is preserved. | Any `FLOAT` value in `list` is preserved. -| If the `list` is `null`, `null` will be returned. -| If the `list` is not a `LIST`, an error will be returned. -| The conversion for each value in `list` is done according to the xref::functions/scalar.adoc#functions-tofloatornull[`toFloatOrNull()` function]. +| If the `input` is `null`, `null` will be returned. +| If the `input` is not a `LIST`, an error will be returned. +| The conversion for each value in `input` is done according to the xref::functions/scalar.adoc#functions-tofloatornull[`toFloatOrNull()` function]. |=== @@ -678,8 +473,8 @@ toFloatList(['a string', 2.5, '3.14159', null, ['A','B']]) as mixedList [role="queryresult",options="header,footer",cols="3*+ | +[,]+ | +[,2.5,3.14159,,]+ +| noList | nullsInList | mixedList +| | [,] | [,2.5,3.14159,,] 3+d|Rows: 1 |=== @@ -690,42 +485,22 @@ toFloatList(['a string', 2.5, '3.14159', null, ['A','B']]) as mixedList [[functions-tointegerlist]] == toIntegerList() -`toIntegerList()` converts a `LIST` of values and returns a `LIST`. -If any values are not convertible to `INTEGER` they will be `null` in the `LIST` returned. - -*Syntax:* - -[source, syntax, role="noheader"] ----- -toIntegerList(list) ----- - -*Returns:* - -|=== - -| A `LIST` containing the converted elements; depending on the input value a converted value is either an `INTEGER` value or `null`. - +.Details |=== - -*Arguments:* - -[options="header"] -|=== -| Name | Description - -| `list` -| An expression that returns a `LIST`. - +| *Syntax* 3+| `toIntegerList(input)` +| *Description* 3+| Converts a `LIST` to a `LIST` values. If any values are not convertible to `INTEGER` they will be null in the `LIST` returned. +.2+| *Arguments* | *Name* | *Type* | *Description* +| `input` | `LIST` | A list of values to be converted into a list of integers. +| *Returns* 3+| `LIST` |=== -*Considerations:* +.Considerations |=== -| Any `null` element in `list` is preserved. -| Any `INTEGER` value in `list` is preserved. -| If the `list` is `null`, `null` will be returned. -| If the `list` is not a `LIST`, an error will be returned. +| Any `null` element in `input` is preserved. +| Any `INTEGER` value in `input` is preserved. +| If the `input` is `null`, `null` will be returned. +| If the `input` is not a `LIST`, an error will be returned. | The conversion for each value in `list` is done according to the xref::functions/scalar.adoc#functions-tointegerornull[`toIntegerOrNull()` function]. |=== @@ -746,8 +521,8 @@ toIntegerList(['a string', 2, '5', null, ['A','B']]) as mixedList [role="queryresult",options="header,footer",cols="3*+ | +[,]+ | +[,2,5,,]+ +| noList | nullsInList | mixedList +| | [,] | [,2,5,,] 3+d|Rows: 1 |=== @@ -758,37 +533,16 @@ toIntegerList(['a string', 2, '5', null, ['A','B']]) as mixedList [[functions-tostringlist]] == toStringList() -`toStringList()` converts a `LIST` of values and returns a `LIST`. -If any values are not convertible to `STRING` they will be `null` in the `LIST` returned. - -*Syntax:* - -[source, syntax, role="noheader"] ----- -toStringList(list) ----- - -*Returns:* - +.Details |=== - -| A `LIST` containing the converted elements; depending on the input value a converted value is either a `STRING` value or `null`. - +| *Syntax* 3+| `toStringList(input)` +| *Description* 3+| Converts a `LIST` to a `LIST` values. If any values are not convertible to `STRING` they will be null in the `LIST` returned. +.2+| *Arguments* | *Name* | *Type* | *Description* +| `input` | `LIST` | A list of values to be converted into a list of strings. +| *Returns* 3+| `LIST` |=== -*Arguments:* - -[options="header"] -|=== -| Name | Description - -| `list` -| An expression that returns a `LIST`. - -|=== - -*Considerations:* - +.Considerations |=== | Any `null` element in `list` is preserved. @@ -815,8 +569,8 @@ toStringList(['already a string', 2, date({year:1955, month:11, day:5}), null, [ [role="queryresult",options="header,footer",cols="3*+ | +[,]+ | +["already a string","2","1955-11-05",,]+ +| noList | nullsInList | mixedList +| | [,] | ["already a string","2","1955-11-05",,] 3+d|Rows: 1 |=== diff --git a/modules/ROOT/pages/functions/load-csv.adoc b/modules/ROOT/pages/functions/load-csv.adoc index bb651f179..53a99f265 100644 --- a/modules/ROOT/pages/functions/load-csv.adoc +++ b/modules/ROOT/pages/functions/load-csv.adoc @@ -1,9 +1,10 @@ :description: LOAD CSV functions can be used to get information about the file that is processed by `LOAD CSV`. +:table-caption!: [[query-functions-load-csv]] = LOAD CSV functions -LOAD CSV functions can be used to get information about the file that is processed by the `LOAD CSV` clause. +LOAD CSV functions can be used to get information about the file that is processed by the xref:clauses/load-csv.adoc[`LOAD CSV`] clause. [IMPORTANT] ==== @@ -15,25 +16,14 @@ In all other contexts they will always return `null`. [[functions-linenumber]] == linenumber() -`linenumber()` returns the line number that `LOAD CSV` is currently using. - -*Syntax:* - -[source, syntax, role="noheader"] ----- -linenumber() ----- - -*Returns:* - +.Details |=== - -| `INTEGER` - +| *Syntax* 3+| `linenumber()` +| *Description* 3+| Returns the line number that LOAD CSV is currently using. +| *Returns* 3+| `INTEGER` |=== -*Considerations:* - +.Considerations |=== | `null` will be returned if this function is called without a `LOAD CSV` context. @@ -44,28 +34,16 @@ linenumber() [[functions-file]] == file() -`file()` returns the absolute path of the file that `LOAD CSV` is using. - -*Syntax:* - -[source, syntax, role="noheader"] ----- -file() ----- - -*Returns:* - +.Details |=== - -| `STRING` - +| *Syntax* 3+| `file()` +| *Description* 3+| Returns the absolute path of the file that LOAD CSV is using. +| *Returns* 3+| `STRING` |=== -*Considerations:* - +.Considerations |=== | `null` will be returned if this function is called without a `LOAD CSV` context. |=== - diff --git a/modules/ROOT/pages/functions/mathematical-logarithmic.adoc b/modules/ROOT/pages/functions/mathematical-logarithmic.adoc index 964a0c1bd..8186d42cc 100644 --- a/modules/ROOT/pages/functions/mathematical-logarithmic.adoc +++ b/modules/ROOT/pages/functions/mathematical-logarithmic.adoc @@ -1,4 +1,5 @@ :description: Logarithmic functions operate on numeric expressions only, and will return an error if used on any other values. +:table-caption!: [[query-functions-logarithmic]] = Mathematical functions - logarithmic @@ -9,24 +10,13 @@ Logarithmic mathematical functions operate on numeric expressions only, and will [[functions-e]] == e() -`e()` returns the base of the natural logarithm, `e`. - -*Syntax:* - -[source, syntax, role="noheader"] ----- -e() ----- - -*Returns:* - +.Details |=== - -| `FLOAT` - +| *Syntax* 3+| `e()` +| *Description* 3+| Returns the base of the natural logarithm, e. +| *Returns* 3+| `FLOAT` |=== - .+e()+ ====== @@ -54,36 +44,16 @@ The base of the natural logarithm, `e`, is returned. [[functions-exp]] == exp() -`exp()` returns `e^n^`, where `e` is the base of the natural logarithm, and `n` is the value of the argument expression. - -*Syntax:* - -[source, syntax, role="noheader"] ----- -e(expression) ----- - -*Returns:* - -|=== - -| `FLOAT` - +.Details |=== - -*Arguments:* - -[options="header"] +| *Syntax* 3+| `exp(input)` +| *Description* 3+| Returns e^n, where e is the base of the natural logarithm, and n is the value of the argument expression. +.2+| *Arguments* | *Name* | *Type* | *Description* +| `input` | `FLOAT` | A value to which the base of the natural logarithm, e, will be raised. +| *Returns* 3+| `FLOAT` |=== -| Name | Description - -| `expression` -| A numeric expression. - -|=== - -*Considerations:* +.Considerations |=== | `exp(null)` returns `null`. @@ -107,8 +77,8 @@ RETURN exp(2) [role="queryresult",options="header,footer",cols="1*(bob), (alice)-[:KNOWS]->(charlie), (bob)-[:KNOWS]->(daniel), (charlie)-[:KNOWS]->(daniel), (bob)-[:MARRIED]->(eskil) ---- -//// - [[functions-abs]] == abs() -`abs()` returns the absolute value of the given number. - -*Syntax:* - -[source, syntax, role="noheader"] ----- -abs(expression) ----- - -*Returns:* - -|=== - -| The type of the value returned will be that of `expression`. - -|=== - -*Arguments:* - -[options="header"] +.Details |=== -| Name | Description - -| `expression` -| A numeric expression. - +| *Syntax* 3+| `abs(input)` +| *Description* 3+| Returns the absolute value of an `INTEGER` or `FLOAT`. +.2+| *Arguments* | *Name* | *Type* | *Description* +| `input` | `INTEGER \| FLOAT` | A numeric value from which the absolute number will be returned. +| *Returns* 3+| `INTEGER \| FLOAT` |=== -*Considerations:* - +.Considerations |=== | `abs(null)` returns `null`. -| If `expression` is negative, `-(expression)` (i.e. the _negation_ of `expression`) is returned. +| If `input` is negative, `-(input)` (i.e. the _negation_ of `input`) is returned. |=== @@ -74,7 +57,8 @@ abs(expression) .Query [source, cypher, indent=0] ---- -MATCH (a), (e) WHERE a.name = 'Alice' AND e.name = 'Eskil' RETURN a.age, e.age, abs(a.age - e.age) +MATCH (a), (e) WHERE a.name = 'Alice' AND e.name = 'Eskil' +RETURN a.age, e.age, abs(a.age - e.age) ---- The absolute value of the age difference is returned. @@ -83,8 +67,8 @@ The absolute value of the age difference is returned. [role="queryresult",options="header,footer",cols="3*> without precision. - -*Syntax:* - -[source, syntax, role="noheader"] ----- -round(expression, precision) ----- - -*Returns:* -|=== - -| `FLOAT` - -|=== - -*Arguments:* - -[options="header"] -|=== -| Name | Description - -| `expression` -| A numeric expression to be rounded. - -| `precision` -| A numeric expression specifying precision. - -|=== - -*Considerations:* - -|=== - -| `round()` returns `null` if any of its input parameters are `null`. - -|=== - +=== round() with precision .+round() with precision+ ====== @@ -466,8 +352,8 @@ RETURN round(3.141592, 3) [role="queryresult",options="header,footer",cols="1* 1), then (`acos(expression)`) returns `NaN`. +| If (`input` < -1) or (`input` > 1), then (`acos(input)`) returns `NaN`. |=== @@ -59,8 +41,8 @@ The arccosine of `0.5` is returned. .Result [role="queryresult",options="header,footer",cols="1* 1), then (`asin(expression)`) returns `NaN`. +| If (`input` < -1) or (`input` > 1), then (`asin(input)`) returns `NaN`. |=== @@ -121,8 +84,8 @@ The arcsine of `0.5` is returned. .Result [role="queryresult",options="header,footer",cols="1*`. +.4+| *Arguments* | *Name* | *Type* | *Description* +| `variable` | `ANY` | A variable that can be used within the `WHERE` clause. +| `list` | `LIST` | A predicate must hold for all elements in this list for the function to return `true`. +| `predicate` | `ANY` | A predicate that is tested against all items in the given list. +| *Returns* 3+| `BOOLEAN` |=== -*Arguments:* - -[options="header"] +.Considerations |=== - -| Name | Description - -| `list` -a| -An expression that returns a list. -A single element cannot be explicitly passed as a literal in the cypher statement. -However, an implicit conversion will happen for single elements when passing node properties during cypher execution. - -| `variable` -| A variable that can be used from within the predicate. - -| `predicate` -| A predicate that is tested against all items in the list. - +| `null` is returned if the `list` is `null` or if the `predicate` evaluates to `null` for at least one element and does not evaluate to false for any other element. |=== - .+all()+ ====== @@ -114,46 +90,22 @@ image::predicate_function_example.svg[width="300",role="middle"] [[functions-any]] == any() -The function `any()` returns `true` if the predicate holds for at least one element in the given list. - -`null` is returned if the list is `null`, or if the predicate evaluates to `null` for at least one element and does not evaluate to `true` for any other element. - -*Syntax:* - -[source, syntax, role="noheader"] ----- -any(variable IN list WHERE predicate) ----- - -*Returns:* - +.Details |=== - -| `BOOLEAN` - +| *Syntax* 3+| `any(variable IN list WHERE predicate)` +| *Description* 3+| Returns true if the predicate holds for at least one element in the given `LIST`. +.4+| *Arguments* | *Name* | *Type* | *Description* +| `variable` | `ANY` | A variable that can be used within the `WHERE` clause. +| `list` | `LIST` | A predicate must hold for all elements in this list for the function to return `true`. +| `predicate` | `ANY` | A predicate that is tested against all items in the given list. +| *Returns* 3+| `BOOLEAN` |=== -*Arguments:* - -[options="header"] +.Considerations |=== -| Name | Description - -| `list` -a| -An expression that returns a list. -A single element cannot be explicitly passed as a literal in the cypher statement. -However, an implicit conversion will happen for single elements when passing node properties during cypher execution. - -| `variable` -| A variable that can be used from within the predicate. - -| `predicate` -| A predicate that is tested against all items in the list. - +| `null` is returned if the `list` is `null` or if the `predicate` evaluates to `null` for at least one element and does not evaluate to false for any other element. |=== - .+any()+ ====== @@ -185,41 +137,24 @@ The query returns the `Person` nodes with the `nationality` property value `Amer [[functions-exists]] == exists() -The function `exists()` returns `true` if a match for the given pattern exists in the graph. - -`null` is returned if the input argument is `null`. - -[NOTE] -==== -To check if a property is not `null` use the xref::syntax/operators.adoc#cypher-comparison[`IS NOT NULL` predicate]. -==== - -*Syntax:* - -[source, syntax, role="noheader"] ----- -exists(pattern) ----- - -*Returns:* - +.Details |=== - -| `BOOLEAN` - +| *Syntax* 3+| `exists(input)` +| *Description* 3+| Returns true if a match for the pattern exists in the graph. +.2+| *Arguments* | *Name* | *Type* | *Description* +| `input` | `ANY` | A pattern to verify the existence of. +| *Returns* 3+| `BOOLEAN` |=== -*Arguments:* - -[options="header"] +.Considerations |=== -| Name | Description - -| `pattern` -| A pattern. - +| `null` is returned if `input` is `null`. |=== +[NOTE] +==== +To check if a property is not `null` use the xref::syntax/operators.adoc#cypher-comparison[`IS NOT NULL` predicate]. +==== .+exists()+ ====== @@ -239,13 +174,13 @@ This query returns the `name` property of every `Person` node, along with a bool [role="queryresult",options="header,footer",cols="2*` is empty. +.2+| *Arguments* | *Name* | *Type* | *Description* +| `input` | `STRING \| MAP \| LIST` | A value to be checked for emptiness. +| *Returns* 3+| `BOOLEAN` |=== - .+isEmpty(list)+ ====== @@ -319,34 +232,6 @@ This query returns every `Person` node in the graph with a set `nationality` pro ====== - -*Syntax:* - -[source, syntax, role="noheader"] ----- -isEmpty(map) ----- - -*Returns:* - -|=== - -| `BOOLEAN` - -|=== - -*Arguments:* - -[options="header"] -|=== -| Name | Description - -| `map` -| An expression that returns a map. - -|=== - - .+isEmpty(map)+ ====== @@ -368,32 +253,6 @@ Because the example graph contains no empty nodes, nothing is returned: ====== -*Syntax:* - -[source, syntax, role="noheader"] ----- -isEmpty(string) ----- - -*Returns:* -|=== - -| `BOOLEAN` - -|=== - -*Arguments:* - -[options="header"] -|=== -| Name | Description - -| `string` -| An expression that returns a `STRING`. - -|=== - - .+isEmpty(string)+ ====== @@ -411,8 +270,8 @@ The `name` property of each node that has an empty `STRING` `address` property i [role="queryresult",options="header,footer",cols="1*`. +.4+| *Arguments* | *Name* | *Type* | *Description* +| `variable` | `ANY` | A variable that can be used within the `WHERE` clause. +| `list` | `LIST` | A predicate must hold for all elements in this list for the function to return `true`. +| `predicate` | `ANY` | A predicate that is tested against all items in the given list. +| *Returns* 3+| `BOOLEAN` |=== -*Arguments:* - -[options="header"] +.Considerations |=== -| Name | Description - -| `list` -a| -An expression that returns a list. -A single element cannot be explicitly passed as a literal in the cypher statement. -However, an implicit conversion will happen for single elements when passing node properties during cypher execution. - -| `variable` -| A variable that can be used from within the predicate. - -| `predicate` -| A predicate that is tested against all items in the list. - +| `null` is returned if the `list` is `null`, or if the `predicate` evaluates to `null` for at least one element and does not evaluate to `true` for any other element. |=== - .+none()+ ====== @@ -492,9 +328,9 @@ image::predicate_function_example.svg[width="300",role="middle"] [role="queryresult",options="header,footer",cols="1*(:Person {nationality: "American",name: "Carrie Anne Moss",age: 55})+ -| +(:Person {nationality: "Canadian",name: "Keanu Reeves",age: 58})-[:KNOWS]->(:Person {nationality: "American",name: "Carrie Anne Moss",age: 55})-[:KNOWS]->(:Person {nationality: "Australian",name: "Guy Pearce",age: 55})+ +| p +| (:Person {nationality: "Canadian",name: "Keanu Reeves",age: 58})-[:KNOWS]->(:Person {nationality: "American",name: "Carrie Anne Moss",age: 55}) +| (:Person {nationality: "Canadian",name: "Keanu Reeves",age: 58})-[:KNOWS]->(:Person {nationality: "American",name: "Carrie Anne Moss",age: 55})-[:KNOWS]->(:Person {nationality: "Australian",name: "Guy Pearce",age: 55}) 1+d|Rows: 2 |=== @@ -505,41 +341,22 @@ image::predicate_function_example.svg[width="300",role="middle"] [[functions-single]] == single() -The function `single()` returns `true` if the predicate holds for exactly _one_ of the elements in the given list. - -`null` is returned if the list is `null`, or if the predicate evaluates to `null` for at least one element and `true` for max one element. - -*Syntax:* - -[source, syntax, role="noheader"] ----- -single(variable IN list WHERE predicate) ----- - -*Returns:* +.Details |=== - -| `BOOLEAN` - +| *Syntax* 3+| `single(variable IN list WHERE predicate)` +| *Description* 3+| Returns true if the predicate holds for exactly one of the elements in the given `LIST`. +.4+| *Arguments* | *Name* | *Type* | *Description* +| `variable` | `ANY` | A variable that can be used within the `WHERE` clause. +| `list` | `LIST` | A predicate must hold for all elements in this list for the function to return `true`. +| `predicate` | `ANY` | A predicate that is tested against all items in the given list. +| *Returns* 3+| `BOOLEAN` |=== -*Arguments:* -[options="header"] +.Considerations |=== -| Name | Description - -| `list` -| An expression that returns a list. - -| `variable` -| A variable that can be used from within the predicate. - -| `predicate` -| A predicate that is tested against all items in the list. - +| `null` is returned if the `list` is `null`, or if the `predicate` evaluates to `null` for at least one element and does not evaluate to `true` for any other element. |=== - .+single()+ ====== @@ -553,14 +370,14 @@ WHERE RETURN p ---- -In every returned path there is exactly one node which the `nationality` property value `Northern Irish`: +In every returned path there is exactly one node which has the `nationality` property value `Northern Irish`: .Result [role="queryresult",options="header,footer",cols="1*(:Person {nationality: "Northern Irish",name: "Liam Neeson",age: 70})+ +| p +| (:Person {nationality: "Canadian",name: "Keanu Reeves",age: 58})-[:KNOWS]->(:Person {nationality: "Northern Irish",name: "Liam Neeson",age: 70}) 1+d|Rows: 1 |=== diff --git a/modules/ROOT/pages/functions/scalar.adoc b/modules/ROOT/pages/functions/scalar.adoc index cb90dd063..459102044 100644 --- a/modules/ROOT/pages/functions/scalar.adoc +++ b/modules/ROOT/pages/functions/scalar.adoc @@ -1,74 +1,51 @@ :description: Scalar functions return a single value. +:table-caption!: [[query-functions-scalar]] = Scalar functions Scalar functions return a single value. +[[example-graph]] +== Example graph -[IMPORTANT] -==== -The `length()` and `size()` functions are quite similar, and so it is important to take note of the difference. +The following graph is used for the examples below: -Function `length()`:: Only works for xref::functions/scalar.adoc#functions-length[paths]. -Function `size()`:: Only works for the three types: xref::functions/scalar.adoc#functions-size-of-string[`STRING` values], xref::functions/scalar.adoc#functions-size[lists], xref::functions/scalar.adoc#functions-size-of-pattern-comprehension[pattern comprehension]. -==== +image::graph_scalar_functions.svg[role="middle", width="700"] -image:graph_scalar_functions.svg[] +To recreate the graph, run the following query against an empty Neo4j database: -//// [source, cypher, role=test-setup] ---- CREATE - (alice:Developer {name:'Alice', age: 38, eyes: 'brown'}), - (bob {name: 'Bob', age: 25, eyes: 'blue'}), - (charlie {name: 'Charlie', age: 53, eyes: 'green'}), - (daniel {name: 'Daniel', age: 54, eyes: 'brown'}), - (eskil {name: 'Eskil', age: 41, eyes: 'blue', liked_colors: ['pink', 'yellow', 'black']}), + (alice:Developer {name:'Alice', age: 38, eyes: 'Brown'}), + (bob:Administrator {name: 'Bob', age: 25, eyes: 'Blue'}), + (charlie:Administrator {name: 'Charlie', age: 53, eyes: 'Green'}), + (daniel:Adminstrator {name: 'Daniel', age: 54, eyes: 'Brown'}), + (eskil:Designer {name: 'Eskil', age: 41, eyes: 'blue', likedColors: ['Pink', 'Yellow', 'Black']}), (alice)-[:KNOWS]->(bob), (alice)-[:KNOWS]->(charlie), (bob)-[:KNOWS]->(daniel), (charlie)-[:KNOWS]->(daniel), (bob)-[:MARRIED]->(eskil) ---- -//// - [role=label--new-5.13] [[functions-char_length]] == char_length() -The function `char_length()` returns the number of Unicode characters in a `STRING`. -This function is an alias of the xref::functions/scalar.adoc#functions-size[`size()`] function, and was introduced as part of Cypher's xref:appendix/gql-conformance/index.adoc[]. - - -*Syntax:* - -[source, syntax, role="noheader"] ----- -char_length(string) ----- - -*Returns:* - +.Details |=== - -| `INTEGER` - +| *Syntax* 3+| `char_length(input)` +| *Description* 3+| Returns the number of Unicode characters in a `STRING`. +.2+| *Arguments* | *Name* | *Type* | *Description* +| `input` | `STRING` | A string value whose length in characters is to be calculated. +| *Returns* 3+| `INTEGER` |=== -*Arguments:* - -[options="header"] -|=== -| Name | Description - -| `string` -| An expression that returns a `STRING`. - -|=== +This function is an alias of the xref::functions/scalar.adoc#functions-size[`size()`] function, and was introduced as part of Cypher's xref:appendix/gql-conformance/index.adoc[]. -*Considerations:* +.Considerations |=== | `char_length(null)` returns `null`. @@ -89,8 +66,8 @@ RETURN char_length('Alice') [role="queryresult",options="header,footer",cols="1*`. +.2+| *Arguments* | *Name* | *Type* | *Description* +| `list` | `LIST` | A list from which the first element will be returned. +| *Returns* 3+| `ANY` |=== -*Arguments:* - -[options="header"] -|=== -| Name | Description - -| `expression` -| An expression that returns a list. - -|=== - -*Considerations:* +.Considerations |=== | `head(null)` returns `null`. @@ -437,7 +316,7 @@ head(expression) ---- MATCH (a) WHERE a.name = 'Eskil' -RETURN a.liked_colors, head(a.liked_colors) +RETURN a.likedColors, head(a.likedColors) ---- The first element in the list is returned. @@ -446,8 +325,8 @@ The first element in the list is returned. [role="queryresult",options="header,footer",cols="2*`. +.2+| *Arguments* | *Name* | *Type* | *Description* +| `list` | `LIST` | A list from which the last element will be returned. +| *Returns* 3+| `ANY` |=== *Considerations:* @@ -606,7 +442,7 @@ last(expression) ---- MATCH (a) WHERE a.name = 'Eskil' -RETURN a.liked_colors, last(a.liked_colors) +RETURN a.likedColors, last(a.likedColors) ---- The last element in the list is returned. @@ -615,8 +451,8 @@ The last element in the list is returned. [role="queryresult",options="header,footer",cols="2*` or the number of Unicode characters in a `STRING`. +.2+| *Arguments* | *Name* | *Type* | *Description* +| `input` | `STRING \| LIST` | A value whose length is to be calculated. +| *Returns* 3+| `INTEGER` |=== -*Arguments:* - -[options="header"] -|=== -| Name | Description - -| `list` -| An expression that returns a list. - -|=== +[NOTE] +To calculate the length of a `PATH`, see xref:functions/scalar.adoc#functions-length[`length()`]. -*Considerations:* +.Considerations |=== | `size(null)` returns `null`. |=== - -.+size()+ +.+size()+ applied to lists ====== .Query @@ -966,8 +714,8 @@ RETURN size(['Alice', 'Bob']) [role="queryresult",options="header,footer",cols="1*`. - -*Syntax:* - -[source, syntax, role="noheader"] ----- -size(pattern comprehension) ----- - -*Arguments:* - -[options="header"] -|=== -| Name | Description - -| `pattern comprehension` -| A pattern comprehension that returns a list. - -|=== - - -.+size()+ +.+size()+ applied to pattern comprehensions ====== .Query @@ -1017,8 +740,8 @@ RETURN size([p=(a)-->()-->() | p]) AS fof [role="queryresult",options="header,footer",cols="1*+ | +false+ +| toBoolean('true') | toBoolean('not a boolean') | toBoolean(0) +| true | | false 3+d|Rows: 1 |=== @@ -1284,43 +916,23 @@ RETURN toBoolean('true'), toBoolean('not a boolean'), toBoolean(0) [[functions-tobooleanornull]] == toBooleanOrNull() -The function `toBooleanOrNull()` converts a `STRING`, `INTEGER` or `BOOLEAN` value to a `BOOLEAN` value. For any other input value, `null` will be returned. - -*Syntax:* - -[source, syntax, role="noheader"] ----- -toBooleanOrNull(expression) ----- - -*Returns:* - -|=== - -| `BOOLEAN` or `null`. - -|=== - -*Arguments:* - -[options="header"] +.Details |=== -| Name | Description - -| `expression` -| Any expression that returns a value. - +| *Syntax* 3+| `toBooleanOrNull(input)` +| *Description* 3+| Converts a value to a `BOOLEAN` value, or null if the value cannot be converted. +.2+| *Arguments* | *Name* | *Type* | *Description* +| `input` | `ANY` | A value to be converted into a boolean or null. +| *Returns* 3+| `BOOLEAN` |=== -*Considerations:* - +.Considerations |=== | `toBooleanOrNull(null)` returns `null`. -| If `expression` is a `BOOLEAN` value, it will be returned unchanged. +| If `input` is a `BOOLEAN` value, it will be returned unchanged. | If the parsing fails, `null` will be returned. -| If `expression` is the `INTEGER` value `0`, `false` will be returned. For any other `INTEGER` value `true` will be returned. -| If the `expression` is not a `STRING`, `INTEGER` or `BOOLEAN` value, `null` will be returned. +| If `input` is the `INTEGER` value `0`, `false` will be returned. For any other `INTEGER` value `true` will be returned. +| If the `input` is not a `STRING`, `INTEGER` or `BOOLEAN` value, `null` will be returned. |=== @@ -1336,8 +948,8 @@ RETURN toBooleanOrNull('true'), toBooleanOrNull('not a boolean'), toBooleanOrNul .Result [role="queryresult",options="header,footer",cols="4*+ | +false+ | ++ +| toBooleanOrNull('true') | toBooleanOrNull('not a boolean') | toBooleanOrNull(0) | toBooleanOrNull(1.5) +| true | | false | 4+d|Rows: 1 |=== @@ -1347,39 +959,20 @@ RETURN toBooleanOrNull('true'), toBooleanOrNull('not a boolean'), toBooleanOrNul [[functions-tofloat]] == toFloat() -The function `toFloat()` converts an `INTEGER`, `FLOAT` or a `STRING` value to a `FLOAT`. - -*Syntax:* - -[source, syntax, role="noheader"] ----- -toFloat(expression) ----- - -*Returns:* +.Details |=== - -| `FLOAT` - +| *Syntax* 3+| `toFloat(input)` +| *Description* 3+| Converts a `STRING`, `INTEGER` or `FLOAT` value to a `FLOAT` value. +.2+| *Arguments* | *Name* | *Type* | *Description* +| `input` | `STRING \| INTEGER \| FLOAT` | A value to be converted into a float. +| *Returns* 3+| `FLOAT` |=== -*Arguments:* - -[options="header"] -|=== -| Name | Description - -| `expression` -| An expression that returns an `INTEGER`, `FLOAT` or a `STRING` value. - -|=== - -*Considerations:* - +.Considerations |=== | `toFloat(null)` returns `null`. -| If `expression` is a `FLOAT`, it will be returned unchanged. +| If `input` is a `FLOAT`, it will be returned unchanged. | If the parsing fails, `null` will be returned. | This function will return an error if provided with an expression that is not an `INTEGER`, `FLOAT` or a `STRING` value. @@ -1397,10 +990,9 @@ RETURN toFloat('11.5'), toFloat('not a number') .Result [role="queryresult",options="header,footer",cols="2*+ +| toFloat('11.5') | toFloat('not a number') +| 11.5 | 2+d|Rows: 1 |=== @@ -1410,46 +1002,25 @@ RETURN toFloat('11.5'), toFloat('not a number') [[functions-tofloatornull]] == toFloatOrNull() -The function `toFloatOrNull()` converts an `INTEGER`, `FLOAT` or a `STRING` value to a `FLOAT`. -For any other input value, `null` will be returned. - -*Syntax:* - -[source, syntax, role="noheader"] ----- -toFloatOrNull(expression) ----- - -*Returns:* -|=== - -| `FLOAT` or `null`. - -|=== - -*Arguments:* - -[options="header"] +.Details |=== -| Name | Description - -| `expression` -| Any expression that returns a value. - +| *Syntax* 3+| `toFloatOrNull(input)` +| *Description* 3+| Converts a value to a `FLOAT` value, or null if the value cannot be converted. +.2+| *Arguments* | *Name* | *Type* | *Description* +| `input` | `ANY` | A value to be converted into a float or null. +| *Returns* 3+| `FLOAT` |=== -*Considerations:* - +.Considerations |=== |`toFloatOrNull(null)` returns `null`. -|If `expression` is a `FLOAT`, it will be returned unchanged. +|If `input` is a `FLOAT`, it will be returned unchanged. |If the parsing fails, `null` will be returned. -|If the `expression` is not an `INTEGER`, `FLOAT` or a `STRING` value, `null` will be returned. +|If the `input` is not an `INTEGER`, `FLOAT` or a `STRING` value, `null` will be returned. |=== - .+toFloatOrNull()+ ====== @@ -1463,8 +1034,8 @@ RETURN toFloatOrNull('11.5'), toFloatOrNull('not a number'), toFloatOrNull(true) [role="queryresult",options="header,footer",cols="3*+ | ++ +| toFloatOrNull('11.5') | toFloatOrNull('not a number') | toFloatOrNull(true) +| 11.5 | | 3+d|Rows: 1 |=== @@ -1475,43 +1046,23 @@ RETURN toFloatOrNull('11.5'), toFloatOrNull('not a number'), toFloatOrNull(true) [[functions-tointeger]] == toInteger() -The function `toInteger()` converts a `BOOLEAN`, `INTEGER`, `FLOAT` or a `STRING` value to an `INTEGER` value. - -*Syntax:* - -[source, syntax, role="noheader"] ----- -toInteger(expression) ----- - -*Returns:* - -|=== - -| `INTEGER` - +.Details |=== - -*Arguments:* - -[options="header"] +| *Syntax* 3+| `toInteger(input)` +| *Description* 3+| Converts a `BOOLEAN`, `STRING`, `INTEGER` or `FLOAT` value to an `INTEGER` value. For `BOOLEAN` values, true is defined to be 1 and false is defined to be 0. +.2+| *Arguments* | *Name* | *Type* | *Description* +| `input` | `BOOLEAN \| STRING \| INTEGER \| FLOAT` | A value to be converted into an integer. +| *Returns* 3+| `INTEGER` |=== -| Name | Description - -| `expression` -| An expression that returns a `BOOLEAN`, `FLOAT`, `INTEGER` or a `STRING` value. - -|=== - -*Considerations:* +.Considerations |=== | `toInteger(null)` returns `null`. -| If `expression` is an integer value, it will be returned unchanged. +| If `input` is an `INTEGER` value, it will be returned unchanged. | If the parsing fails, `null` will be returned. -| If `expression` is the boolean value `false`, `0` will be returned. -| If `expression` is the boolean value `true`, `1` will be returned. +| If `input` is the boolean value `false`, `0` will be returned. +| If `input` is the boolean value `true`, `1` will be returned. | This function will return an error if provided with an expression that is not a `BOOLEAN`, `FLOAT`, `INTEGER` or a `STRING` value. |=== @@ -1530,8 +1081,8 @@ RETURN toInteger('42'), toInteger('not a number'), toInteger(true) [role="queryresult",options="header,footer",cols="3*+ | +1+ +| toInteger('42') | toInteger('not a number') | toInteger(true) +| 42 | | 1 3+d|Rows: 1 |=== @@ -1542,42 +1093,24 @@ RETURN toInteger('42'), toInteger('not a number'), toInteger(true) [[functions-tointegerornull]] == toIntegerOrNull() -The function `toIntegerOrNull()` converts a `BOOLEAN`, `INTEGER`, `FLOAT` or a `STRING` value to an `INTEGER` value. For any other input value, `null` will be returned. - -*Syntax:* - -[source, syntax, role="noheader"] ----- -toIntegerOrNull(expression) ----- - -*Returns:* +.Details |=== - -| `INTEGER` or `null`. - +| *Syntax* 3+| `toIntegerOrNull(input)` +| *Description* 3+| Converts a value to an `INTEGER` value, or null if the value cannot be converted. +.2+| *Arguments* | *Name* | *Type* | *Description* +| `input` | `ANY` | A value to be converted into an integer or null. +| *Returns* 3+| `INTEGER` |=== -*Arguments:* - -[options="header"] -|=== -| Name | Description - -| `expression` | Any expression that returns a value. - -|=== - -*Considerations:* - +.Considerations |=== | `toIntegerOrNull(null)` returns `null`. -| If `expression` is an integer value, it will be returned unchanged. +| If `input` is an `INTEGER` value, it will be returned unchanged. | If the parsing fails, `null` will be returned. -| If `expression` is the `BOOLEAN` value `false`, `0` will be returned. -| If `expression` is the `BOOLEAN` value `true`, `1` will be returned. -| If the `expression` is not a `BOOLEAN`, `FLOAT`, `INTEGER` or a `STRING` value, `null` will be returned. +| If `input` is the `BOOLEAN` value `false`, `0` will be returned. +| If `input` is the `BOOLEAN` value `true`, `1` will be returned. +| If the `input` is not a `BOOLEAN`, `FLOAT`, `INTEGER` or a `STRING` value, `null` will be returned. |=== @@ -1595,8 +1128,8 @@ RETURN toIntegerOrNull('42'), toIntegerOrNull('not a number'), toIntegerOrNull(t [role="queryresult",options="header,footer",cols="4*+ | +1+ | ++ +| toIntegerOrNull('42') | toIntegerOrNull('not a number') | toIntegerOrNull(true) | toIntegerOrNull(['A', 'B', 'C']) +| 42 | | 1 | 4+d|Rows: 1 |=== @@ -1607,35 +1140,16 @@ RETURN toIntegerOrNull('42'), toIntegerOrNull('not a number'), toIntegerOrNull(t [[functions-type]] == type() -The function `type()` returns the `STRING` representation of the `RELATIONSHIP` type. - -*Syntax:* - -[source, syntax, role="noheader"] ----- -type(relationship) ----- - -*Returns:* - +.Details |=== - -| `STRING` - -|=== - -*Arguments:* - -[options="header"] +| *Syntax* 3+| `type(input)` +| *Description* 3+| Returns a `STRING` representation of the `RELATIONSHIP` type. +.2+| *Arguments* | *Name* | *Type* | *Description* +| `input` | `RELATIONSHIP` | A relationship. +| *Returns* 3+| `STRING` |=== -| Name | Description -| `relationship` -| An expression that returns a `RELATIONSHIP`. - -|=== - -*Considerations:* +.Considerations |=== @@ -1661,9 +1175,9 @@ The relationship type of `r` is returned. [role="queryresult",options="header,footer",cols="1* NOT NULL"+ +| result +| "STRING NOT NULL" +| "INTEGER NOT NULL" +| "FLOAT NOT NULL" +| "BOOLEAN NOT NULL" +| "LIST NOT NULL" 1+d|Rows: 5 |=== diff --git a/modules/ROOT/pages/functions/spatial.adoc b/modules/ROOT/pages/functions/spatial.adoc index 7243a0a72..83686c2d0 100644 --- a/modules/ROOT/pages/functions/spatial.adoc +++ b/modules/ROOT/pages/functions/spatial.adoc @@ -1,96 +1,98 @@ :description: Spatial functions are used to specify 2D or 3D points in a Coordinate Reference System (CRS) and to calculate the geodesic distance between two points. +:table-caption!: [[query-functions-spatial]] = Spatial functions Spatial functions are used to specify 2D or 3D `POINT` values in a Coordinate Reference System (CRS) and to calculate the geodesic distance between two `POINT` values. +[[example-graph]] +== Example graph + The following graph is used for some of the examples below. -image:graph_spatial_functions.svg[] +image::graph_spatial_functions.svg[role="middle", width="500"] -To recreate the graph, run the following query in an empty Neo4j database: +To recreate the graph, run the following query against an empty Neo4j database: [source, cypher, role=test-setup] ---- CREATE - (copenhagen:TrainStation {longitude: 12.564590, latitude: 55.672874, city: 'Copenhagen'}), - (malmo:Office {longitude: 12.994341, latitude: 55.611784, city: 'Malmo'}), + (copenhagen:TrainStation {latitude: 55.672874, longitude: 12.564590, city: 'Copenhagen'}), + (malmo:Office {latitude: 55.611784, longitude: 12.994341, city: 'Malmö'}), (copenhagen)-[:TRAVEL_ROUTE]->(malmo) ---- -[[functions-distance]] -== point.distance() - -`point.distance()` returns a `FLOAT` representing the geodesic distance between two points in the same Coordinate Reference System (CRS). - -* If the `POINT` values are in the _Cartesian_ CRS (2D or 3D), then the units of the returned distance will be the same as the units of the points, calculated using Pythagoras' theorem. -* If the `POINT` values are in the _WGS-84_ CRS (2D), then the units of the returned distance will be meters, based on the haversine formula over a spherical earth approximation. -* If the `POINT` values are in the _WGS-84_ CRS (3D), then the units of the returned distance will be meters. - ** The distance is calculated in two steps. - *** First, a haversine formula over a spherical earth is used, at the average height of the two points. - *** To account for the difference in height, Pythagoras' theorem is used, combining the previously calculated spherical distance with the height difference. - ** This formula works well for points close to the earth's surface; for instance, it is well-suited for calculating the distance of an airplane flight. -It is less suitable for greater heights, however, such as when calculating the distance between two satellites. - -[source, syntax] ----- -point.distance(point1, point2) ----- - -*Returns:* - -|=== - -| `FLOAT` - -|=== +[[functions-point]] +== point() -*Arguments:* -[options="header"] +.Details |=== -| Name | Description +| *Syntax* 3+| `point(input)` +| *Description* 3+| Returns a 2D or 3D point object, given two or respectively three coordinate values in the Cartesian coordinate system or WGS 84 geographic coordinate system. +.2+| *Arguments* | *Name* | *Type* | *Description* +| `input` | `MAP` | Cartesian 2D: `{ + +x :: FLOAT, + +y :: FLOAT, + +crs = "cartesian" :: STRING, + +srid = 7203 :: INTEGER + +}` -| `point1` -| A `POINT` in either a geographic or cartesian coordinate system. +Cartesian 3D: `{ + +x :: FLOAT, + +y :: FLOAT, + +z :: FLOAT, + +crs = "cartesian-3D" :: STRING, + +srid = 9157 :: INTEGER + +}` -| `point2` -| A `POINT` in the same CRS as `point1`. +WGS 84 2D: `{ + +longitude \| x :: FLOAT + +latitude \| y :: FLOAT + +crs = "WGS-84-2D" :: STRING + +srid = 4326 :: INTEGER + +}` +WGS 84 3D: `{ + +longitude \| x :: FLOAT, + +latitude \| y :: FLOAT, + +height \| z :: FLOAT, + +crs = "WGS-84-3D" :: STRING, + +srid = 4979 :: INTEGER + +}` +| *Returns* 3+| `POINT` |=== -*Considerations:* +.Considerations |=== -| `point.distance(null, null)` return `null`. -| `point.distance(null, point2)` return `null`. -| `point.distance(point1, null)` return `null`. -| Attempting to use points with different Coordinate Reference Systems (such as WGS 84 2D and WGS 84 3D) will return `null`. +| If any argument provided to `point()` is `null`, `null` will be returned. +| If the coordinates are specified using `latitude` and `longitude`, the `crs` or `srid` fields are optional and inferred to be `'WGS-84'` (`srid:4326`) for 2D points or `'WGS-84-3D'` (`srid:4979`) for 3D points. +| If the coordinates are specified using `x` and `y`, then either the `crs` or `srid` field is required if a geographic CRS is desired. +| If the `height/z` key and value is not provided, a 2D `POINT` will be returned in either the _WGS 84_ or _Cartesian_ CRS, depending on the coordinate system used. +| The `crs` or `srid` fields are optional and default to the _Cartesian_ CRS (which means `srid:7203`) for 2D points or the _3D Cartesian_ CRS (which means `srid:9157`) for 3D points. |=== -.+point.distance()+ +.+point()+ - WGS 84 2D ====== .Query [source, cypher] ---- -WITH - point({x: 2.3, y: 4.5, crs: 'cartesian'}) AS p1, - point({x: 1.1, y: 5.4, crs: 'cartesian'}) AS p2 -RETURN point.distance(p1,p2) AS dist +RETURN point({longitude: 56.7, latitude: 12.78}) AS point ---- -The distance between two 2D points in the _Cartesian_ CRS is returned. +A 2D `POINT` with a `longitude` of `56.7` and a `latitude` of `12.78` in the _WGS 84_ CRS is returned. .Result [role="queryresult",options="header,footer",cols="1*(o:Office) -WITH - point({longitude: t.longitude, latitude: t.latitude}) AS trainPoint, - point({longitude: o.longitude, latitude: o.latitude}) AS officePoint -RETURN round(point.distance(trainPoint, officePoint)) AS travelDistance +MATCH (p:Office) +RETURN point({longitude: p.longitude, latitude: p.latitude}) AS officePoint ---- -The distance between the train station in Copenhagen and the Neo4j office in Malmo is returned. +A 2D `POINT` representing the coordinates of the city of Malmo in the _WGS 84_ CRS is returned. .Result [role="queryresult",options="header,footer",cols="1*+ -1+d|Rows: 1 - -|=== - -====== - - -[[functions-withinBBox]] -== point.withinBBox() - -`point.withinBBox()` takes the following arguments: - -* The `POINT` to check. -* The lower-left (south-west) `POINT` of a bounding box. -* The upper-right (or north-east) `POINT` of a bounding box. - -The return value will be true if the provided point is contained in the bounding box (boundary included), otherwise the return value will be false. - -[source, syntax] ----- -point.withinBBox(point, lowerLeft, upperRight) ----- - -*Returns:* - -|=== - -| `BOOLEAN` - -|=== - -*Arguments:* - -[options="header"] -|=== -| Name | Description - -| `point` -| A `POINT` in either a geographic or cartesian coordinate system. - -| `lowerLeft` -| A `POINT` in the same CRS as 'point'. - -| `upperRight` -| A `POINT` in the same CRS as 'point'. - -|=== - -*Considerations:* - -|=== - -| `point.withinBBox(p1, p2, p3)` will return `null` if any of the arguments evaluate to `null`. -| Attempting to use `POINT` values with different Coordinate Reference Systems (such as WGS 84 2D and WGS 84 3D) will return `null`. -| `point.withinBBox` will handle crossing the 180th meridian in geographic coordinates. -| Switching the longitude of the `lowerLeft` and `upperRight` in geographic coordinates will switch the direction of the resulting bounding box. -| Switching the latitude of the `lowerLeft` and `upperRight` in geographic coordinates so that the former is north of the latter will result in an empty range. - -|=== - - -.+point.withinBBox()+ -====== - -.Query -[source, cypher] ----- -WITH - point({x: 0, y: 0, crs: 'cartesian'}) AS lowerLeft, - point({x: 10, y: 10, crs: 'cartesian'}) AS upperRight -RETURN point.withinBBox(point({x: 5, y: 5, crs: 'cartesian'}), lowerLeft, upperRight) AS result +RETURN point({longitude: 56.7, latitude: 12.78, height: 8}) AS point ---- -Checking if a point in _Cartesian_ CRS is contained in the bounding box. +A 3D `POINT` with a `longitude` of `56.7`, a `latitude` of `12.78` and a height of `8` meters in the _WGS 84_ CRS is returned. .Result [role="queryresult",options="header,footer",cols="1*+ +| p +| 1+d|Rows: 1 |=== @@ -343,75 +244,59 @@ If `null` is provided as any of the arguments, `null` is returned. ====== -[[functions-point-wgs84-2d]] -== point() - WGS 84 2D - -`point({longitude | x, latitude | y [, crs][, srid]})` returns a 2D `POINT` in the _WGS 84_ CRS corresponding to the given coordinate values. - -[source, syntax] ----- -point({longitude | x, latitude | y [, crs][, srid]}) ----- - -*Returns:* - -|=== - -| A 2D `POINT` in _WGS 84_. - -|=== - -*Arguments:* +[[functions-distance]] +== point.distance() -[options="header"] +.Details |=== -| Name | Description - -| `A single map consisting of the following:` -| - -| `longitude/x` -| A numeric expression that represents the longitude/x value in decimal degrees. - -| `latitude/y` -| A numeric expression that represents the latitude/y value in decimal degrees. - -| `crs` -| The optional `STRING` `'WGS-84'`. - -| `srid` -| The optional `INTEGER` `4326`. - +| *Syntax* 3+| `point.distance(from, to)` +| *Description* 3+| Returns a `FLOAT` representing the geodesic distance between any two points in the same CRS. +.3+| *Arguments* | *Name* | *Type* | *Description* +| `from` | `POINT` | A start point. +| `to` | `POINT` | An end point in the same CRS as the start point. +| *Returns* 3+| `FLOAT` |=== -*Considerations:* +* If the `POINT` values are in the _Cartesian_ CRS (2D or 3D), then the units of the returned distance will be the same as the units of the points, calculated using Pythagoras' theorem. +* If the `POINT` values are in the _WGS-84_ CRS (2D), then the units of the returned distance will be meters, based on the haversine formula over a spherical Earth approximation. +* If the `POINT` values are in the _WGS-84_ CRS (3D), then the units of the returned distance will be meters. + ** The distance is calculated in two steps. + *** First, a haversine formula over a spherical Earth is used, at the average height of the two points. + *** To account for the difference in height, Pythagoras' theorem is used, combining the previously calculated spherical distance with the height difference. + ** This formula works well for points close to the earth's surface; for instance, it is well-suited for calculating the distance of an airplane flight. +It is less suitable for greater heights, however, such as when calculating the distance between two satellites. +.Considerations |=== -| If any argument provided to `point()` is `null`, `null` will be returned. -| If the coordinates are specified using `latitude` and `longitude`, the `crs` or `srid` fields are optional and inferred to be `'WGS-84'` (`srid:4326`). -| If the coordinates are specified using `x` and `y`, then either the `crs` or `srid` field is required if a geographic CRS is desired. +| `point.distance(null, null)` return `null`. +| `point.distance(null, to)` return `null`. +| `point.distance(from, null)` return `null`. +| Attempting to use points with different Coordinate Reference Systems (such as WGS 84 2D and WGS 84 3D) will return `null`. |=== -.+point()+ +.+point.distance()+ ====== .Query [source, cypher] ---- -RETURN point({longitude: 56.7, latitude: 12.78}) AS point +WITH + point({x: 2.3, y: 4.5, crs: 'cartesian'}) AS p1, + point({x: 1.1, y: 5.4, crs: 'cartesian'}) AS p2 +RETURN point.distance(p1,p2) AS dist ---- -A 2D `POINT` with a `longitude` of `56.7` and a `latitude` of `12.78` in the _WGS 84_ CRS is returned. +The distance between two 2D points in the _Cartesian_ CRS is returned. .Result [role="queryresult",options="header,footer",cols="1*(o:Office) +WITH + point({longitude: t.longitude, latitude: t.latitude}) AS trainPoint, + point({longitude: o.longitude, latitude: o.latitude}) AS officePoint +RETURN round(point.distance(trainPoint, officePoint)) AS travelDistance ---- -A 2D `POINT` representing the coordinates of the city of Malmo in the _WGS 84_ CRS is returned. +The distance between the train station in Copenhagen and the Neo4j office in Malmo is returned. .Result [role="queryresult",options="header,footer",cols="1*+ +| d +| null 1+d|Rows: 1 |=== @@ -492,79 +383,52 @@ If `null` is provided as the argument, `null` is returned. ====== -[[functions-point-wgs84-3d]] -== point() - WGS 84 3D - -`point({longitude | x, latitude | y, height | z, [, crs][, srid]})` returns a 3D `POINT` in the _WGS 84_ CRS corresponding to the given coordinate values. - -[source, syntax] ----- -point({longitude | x, latitude | y, height | z, [, crs][, srid]}) ----- - -*Returns:* - -|=== - -| A 3D `POINT` in _WGS 84_. - -|=== - -*Arguments:* +[[functions-withinBBox]] +== point.withinBBox() -[options="header"] +.Details |=== -| Name | Description - -| `A single map consisting of the following:` -| - -| `longitude/x` -| A numeric expression that represents the longitude/x value in decimal degrees. - -| `latitude/y` -| A numeric expression that represents the latitude/y value in decimal degrees. - -| `height/z` -| A numeric expression that represents the height/z value in meters. - -| `crs` -| The optional `STRING` `'WGS-84-3D'`. - -| `srid` -| The optional `INTEGER` `4979`. - +| *Syntax* 3+| `point.withinBBox(point, lowerLeft, upperRight)` +| *Description* 3+| Returns true if the provided point is within the bounding box defined by the two provided points. +.4+| *Arguments* | *Name* | *Type* | *Description* +| `point` | `POINT` | A point to be confirmed in the bounding box. +| `lowerLeft` | `POINT` | The lower left side point of the bounding box. +| `upperRight` | `POINT` | The upper right side point of the bounding box. +| *Returns* 3+| `BOOLEAN` |=== -*Considerations:* - +.Considerations |=== -| If any argument provided to `point()` is `null`, `null` will be returned. -| If the `height/z` key and value is not provided, a 2D `POINT` in the _WGS 84_ CRS will be returned. -| If the coordinates are specified using `latitude` and `longitude`, the `crs` or `srid` fields are optional and inferred to be `'WGS-84-3D'` (`srid:4979`). -| If the coordinates are specified using `x` and `y`, then either the `crs` or `srid` field is required if a geographic CRS is desired. +| `point.withinBBox(point, lowerLeft, upperRight)` will return `null` if any of the arguments evaluate to `null`. +| Attempting to use `POINT` values with different Coordinate Reference Systems (such as WGS 84 2D and WGS 84 3D) will return `null`. +| `point.withinBBox` will handle crossing the 180th meridian in geographic coordinates. +| Switching the longitude of the `lowerLeft` and `upperRight` in geographic coordinates will switch the direction of the resulting bounding box. +| Switching the latitude of the `lowerLeft` and `upperRight` in geographic coordinates so that the former is north of the latter will result in an empty range. |=== -.+point()+ +.+point.withinBBox()+ ====== .Query [source, cypher] ---- -RETURN point({longitude: 56.7, latitude: 12.78, height: 8}) AS point +WITH + point({x: 0, y: 0, crs: 'cartesian'}) AS lowerLeft, + point({x: 10, y: 10, crs: 'cartesian'}) AS upperRight +RETURN point.withinBBox(point({x: 5, y: 5, crs: 'cartesian'}), lowerLeft, upperRight) AS result ---- -A 3D `POINT` with a `longitude` of `56.7`, a `latitude` of `12.78` and a height of `8` meters in the _WGS 84_ CRS is returned. +Checking if a point in _Cartesian_ CRS is contained in the bounding box. .Result [role="queryresult",options="header,footer",cols="1*` in which the order of all characters or elements in the given `STRING` or `LIST` have been reversed. +.2+| *Arguments* | *Name* | *Type* | *Description* +| `input` | `STRING \| LIST` | The string or list to be reversed. +| *Returns* 3+| `STRING \| LIST` |=== -| Name | Description - -| `original` -| An expression that returns a `STRING`. - -|=== - -*Considerations:* +.Considerations |=== | `reverse(null)` returns `null`. +| See also xref:functions/list.adoc#functions-reverse[List functions -> reverse]. |=== @@ -578,8 +388,8 @@ RETURN reverse('anagram') [role="queryresult",options="header,footer",cols="1*` resulting from the splitting of the given `STRING` around matches of the given delimiter. - -*Syntax:* - -[source, syntax, role="noheader"] ----- -split(original, splitDelimiter) ----- - -*Returns:* - -|=== - -| `LIST` - +.Details |=== - -*Arguments:* -[options="header"] -|=== -| Name | Description - -| `original` -| An expression that returns a `STRING`. - -| `splitDelimiter` -| The `STRING` with which to split `original`. - +| *Syntax* 3+| `split(original, splitDelimiters)` +| *Description* 3+| Returns a `LIST` resulting from the splitting of the given `STRING` around matches of the given delimiter(s). +.3+| *Arguments* | *Name* | *Type* | *Description* +| `original` | `STRING` | The string to be split. +| `splitDelimiters` | `STRING \| LIST` | The string with which to split the original string. +| *Returns* 3+| `LIST` |=== -*Considerations:* - +.Considerations |=== | `split(null, splitDelimiter)` return `null`. @@ -783,8 +529,8 @@ RETURN split('one,two', ',') [role="queryresult",options="header,footer",cols="1*+ +| toStringOrNull(11.5) | toStringOrNull('already a string') | toStringOrNull(true) | dateString | datetimeString | durationString | list +| "11.5" | "already a string" | "true" | "1984-10-11" | "1984-10-11T12:31:14.341+01:00[Europe/Stockholm]" | "PT11M" | 7+d|Rows: 1 |=== @@ -1061,36 +727,16 @@ toStringOrNull(['A', 'B', 'C']) AS list [[functions-toupper]] == toUpper() -`toUpper()` returns the given `STRING` in uppercase. - -*Syntax:* - -[source, syntax, role="noheader"] ----- -toUpper(original) ----- - -*Returns:* - -|=== - -| `STRING` - +.Details |=== - -*Arguments:* - -[options="header"] -|=== -| Name | Description - -| `input` -| A string to be converted into uppercase. - +| *Syntax* 3+| `toUpper(input)` +| *Description* 3+| Returns the given `STRING` in uppercase. +.2+| *Arguments* | *Name* | *Type* | *Description* +| `input` | `STRING` | A string to be converted into uppercase. +| *Returns* 3+| `STRING` |=== -*Considerations:* - +.Considerations |=== | `toUpper(null)` returns `null`. @@ -1111,8 +757,8 @@ RETURN toUpper('hello') [role="queryresult",options="header,footer",cols="1*` | A list representing the first vector. +| `b` | `LIST` | A list representing the second vector. +| *Returns* 3+| `FLOAT` +|=== + +For more details, see the {link-vector-indexes}#similarity-functions[vector index documentation]. + +.Considerations +|=== + +| `vector.similarity.cosine(NULL, NULL)` returns `NULL`. +| `vector.similarity.cosine(NULL, b)` returns `NULL`. +| `vector.similarity.cosine(a, NULL)` returns `NULL`. +| Both vectors must be of the same dimension. +| Both vectors must be {link-vector-indexes}#indexes-vector-similarity-cosine[*valid*] with respect to cosine similarity. +| The implementation is identical to that of the latest available vector index provider (`vector-2.0`). + +|=== + + +[[functions-similarity-euclidean]] +== vector.similarity.euclidean() + +.Details +|=== +| *Syntax* 3+| `vector.similarity.euclidean(a, b)` +| *Description* 3+| Returns a `FLOAT` representing the similarity between the argument vectors based on their Euclidean distance. +.3+| *Arguments* | *Name* | *Type* | *Description* +| `a` | `LIST` | A list representing the first vector. +| `b` | `LIST` | A list representing the second vector. +| *Returns* 3+| `FLOAT` +|=== + +For more details, see the {link-vector-indexes}#similarity-functions[vector index documentation]. + +.Considerations +|=== + +| `vector.similarity.euclidean(NULL, NULL)` returns `NULL`. +| `vector.similarity.euclidean(NULL, b)` returns `NULL`. +| `vector.similarity.euclidean(a, NULL)` returns `NULL`. +| Both vectors must be of the same dimension. +| Both vectors must be {link-vector-indexes}#indexes-vector-similarity-euclidean[*valid*] with respect to Euclidean similarity. +| The implementation is identical to that of the latest available vector index provider (`vector-2.0`). + +|=== + + + +.k-Nearest Neighbors +====== + +_k_-nearest neighbor queries return the _k_ entities with the highest similarity scores based on comparing their associated vectors with a query vector. Such queries can be run against vector indexes in the form of _approximate_ _k_-nearest neighbor (k-ANN) queries, whose returned entities have a high probability of being among the true _k_ nearest neighbors. However, they can also be expressed as an exhaustive search using vector similarity functions directly. While this is typically significantly slower than using an index, it is exact rather than approximate and does not require an existing index. This can be useful for one-off queries on small sets of data. -.k-Nearest Neighbors -====== To create the graph used in this example, run the following query in an empty Neo4j database: [source, cypher, role=test-setup] @@ -46,8 +106,8 @@ This returns the two nearest neighbors. [role="queryresult",options="header,footer",cols="2*` representing the first vector. - -| `b` -| A `LIST` representing the second vector. - -|=== - -*Considerations:* -|=== - -| `vector.similarity.cosine(NULL, NULL)` returns `NULL`. -| `vector.similarity.cosine(NULL, b)` returns `NULL`. -| `vector.similarity.cosine(a, NULL)` returns `NULL`. -| Both vectors must be of the same dimension. -| Both vectors must be {link-vector-indexes}#indexes-vector-similarity-cosine[*valid*] with respect to cosine similarity. -| The implementation is identical to that of the latest available vector index provider (`vector-2.0`). - -|=== - -[[functions-similarity-euclidean]] -== vector.similarity.euclidean() - -`vector.similarity.euclidean()` returns a `FLOAT` representing the similarity between the argument vectors based on their Euclidean distance. For more details, see the {link-vector-indexes}#indexes-vector-similarity-euclidean[vector index documentation]. - -[source, syntax] ----- -vector.similarity.euclidean(a, b) ----- - -*Returns:* - -|=== - -| `FLOAT` - -|=== - -*Arguments:* - -[options="header"] -|=== -| Name | Description - -| `a` -| A `LIST` representing the first vector. - -| `b` -| A `LIST` representing the second vector. - -|=== - -*Considerations:* -|=== - -| `vector.similarity.euclidean(NULL, NULL)` returns `NULL`. -| `vector.similarity.euclidean(NULL, b)` returns `NULL`. -| `vector.similarity.euclidean(a, NULL)` returns `NULL`. -| Both vectors must be of the same dimension. -| Both vectors must be {link-vector-indexes}#indexes-vector-similarity-euclidean[*valid*] with respect to Euclidean similarity. -| The implementation is identical to that of the latest available vector index provider (`vector-2.0`). - -|===