Document VECTOR type and new vector functions (#1299)

See also: #1325

Co-authored-by: Stefano Ottolenghi <[email protected]>

Author: JPryce-Aklundh

modules/ROOT/content-nav.adoc

@@ -64,6 +64,7 @@
 ** xref::values-and-types/spatial.adoc[]
 ** xref::values-and-types/lists.adoc[]
 ** xref::values-and-types/maps.adoc[]
+** xref::values-and-types/vector.adoc[]
 ** xref:values-and-types/graph-references.adoc[]
 ** xref::values-and-types/working-with-null.adoc[]
 ** xref::values-and-types/casting-data.adoc[]

modules/ROOT/pages/appendix/gql-conformance/additional-cypher.adoc

@@ -52,11 +52,14 @@ Either the pattern already exists, or it needs to be created.
 | Cypher feature
 | Description
 
+| xref:values-and-types/maps.adoc#query-operators-list[`MAP` values].
+| Map values - the GQL equivalent is Records.
+
 | xref:values-and-types/spatial.adoc[`POINT` values]
 | Spatial values.
 
-| xref:values-and-types/maps.adoc#query-operators-list[`MAP` values].
-| Map values - the GQL equivalent is Records.
+| xref:values-and-types/vector.adoc[`VECTOR<TYPE>(DIMENSION)` values]
+| Vector values, defined with a coordinate type and dimension.
 
 |===
 

modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc

@@ -26,6 +26,67 @@ For more information, see xref:queries/select-version.adoc[].
 [[cypher-deprecations-additions-removals-2025.10]]
 == Neo4j 2025.10
 
+=== New in Cypher 25
+
+[cols="2", options="header"]
+|===
+| Feature
+| Details
+
+a|
+label:functionality[]
+label:new[]
+[source, cypher]
+----
+VECTOR([1.05, 0.123, 5], 3, FLOAT32 NOT NULL)
+----
+
+a| Introduced a `VECTOR` value type that can be stored as xref:indexes/semantic-indexes/vector-indexes.adoc#embeddings[embedding] properties on nodes and relationships and utilized for efficient semantic retrieval using Neo4j's xref:indexes/semantic-indexes/vector-indexes.adoc[vector indexes] and xref:genai-integrations.adoc[GenAI plugin].
+For more information, see xref:values-and-types/vector.adoc[Values and types -> Vectors].
+
+a|
+label:functionality[]
+label:new[]
+[source, cypher]
+----
+WITH vector([1, 2, 3], 3, INTEGER) AS vector
+RETURN vector, valueType(vector) AS vectorType
+----
+
+a| New xref:functions/vector.adoc#functions-vector[`vector()`] function for the construction of xref:values-and-types/vector.adoc[`VECTOR`] values.
+
+a|
+label:functionality[]
+label:new[]
+[source, cypher]
+----
+RETURN vector_dimension_count(vector([1, 2, 3], 3, INTEGER)) AS size
+----
+
+a| New xref:functions/vector.adoc#functions-vector_dimension_count[`vector_dimension_count()`] function, which returns the dimension of a xref:values-and-types/vector.adoc[`VECTOR`] value.
+
+a|
+label:functionality[]
+label:new[]
+[source, cypher]
+----
+RETURN vector_distance(vector([1, 2, 3], 3, INT), vector([1, 2, 4], 3, INT), COSINE) AS distance
+----
+
+a| New xref:functions/vector.adoc#functions-vector_distance[`vector_distance()`] function, which returns the distance between two xref:values-and-types/vector.adoc[`VECTOR`] values based on the selected `vectorDistanceMetric` algorithm.
+
+a|
+label:functionality[]
+label:new[]
+[source, cypher]
+----
+RETURN vector_norm(vector([1.0, 5.0, 3.0, 6.7], 4, FLOAT), EUCLIDEAN) AS norm
+----
+
+a| New xref:functions/vector.adoc#functions-vector_norm[`vector_norm()`] function, which returns the distance between the given vector and an origin vector, which is a vector with the same dimension with all coordinates set to zero, calculated using the specified `vectorDistanceMetric`.
+
+|===
+
 === Updated in Cypher 25
 
 [cols="2", options="header"]
@@ -36,7 +97,20 @@ For more information, see xref:queries/select-version.adoc[].
 a|
 label:functionality[]
 label:updated[]
-[source, cypher, role="noheader"]
+[source, cypher]
+----
+RETURN toFloatList(Vector([1, 2, 3], 3, INTEGER64)),
+       toIntegerList(Vector([1, 2, 3], 3, INTEGER8)),
+       vector.similarity.cosine(vector([3, 5, 7], 3, INT), vector([-1, -2, -3], 3, INT)),
+       vector.similarity.euclidean(vector([3, 5, 7], 3, INT), vector([-1, -2, -3], 3, INT))
+----
+
+a| The xref:functions/list.adoc#functions-tofloatlist[`toFloatList()`], xref:functions/list.adoc#functions-tointegerlist[`toIntegerList()`], xref:functions/vector.adoc#functions-similarity-cosine[`vector.similarity.cosine()`], and xref:functions/vector.adoc#functions-similarity-euclidean[`vector.similarity.euclidean()`] functions now accept `VECTOR` values as input arguments.
+
+a|
+label:functionality[]
+label:updated[]
+[source, cypher]
 ----
 RETURN datetime('11/18/1986', "MM/dd/yyyy") AS dt
 ----
@@ -68,7 +142,7 @@ RETURN format(dt, "MM/dd/yyyy") AS US, format(dt, "dd/MM/yyyy") AS EU
 
 | Cypher's new xref:functions/temporal/format.adoc[`format()`] function can create dynamically formatted string representations of temporal instance and duration types.
 
-a| 
+a|
 label:functionality[]
 label:new[]
 
@@ -119,7 +193,7 @@ label:functionality[]
 label:updated[]
 [source, cypher]
 ----
-PROFILE 
+PROFILE
 WITH "Person" AS label
 MATCH (people:$(label))
 RETURN people.name
@@ -143,7 +217,7 @@ label:new[]
 ----
 MATCH (()-->(n))+
 WHERE allReduce(acc = 0, node IN n \| acc + node.x, 6 < acc < 30)
-RETURN [i IN n \| i.x] AS sequence 
+RETURN [i IN n \| i.x] AS sequence
 ORDER BY head(n).x, size(n)
 ----
 
@@ -517,10 +591,10 @@ label:new[]
 ----
 CREATE ALIAS `remote-with-default-language`
 FOR DATABASE `northwind-graph-2020`
-	AT "neo4j+s://location:7687"
-	USER alice
-	PASSWORD 'example_secret'
-	DEFAULT LANGUAGE CYPHER 25
+    AT "neo4j+s://location:7687"
+    USER alice
+    PASSWORD 'example_secret'
+    DEFAULT LANGUAGE CYPHER 25
 ----
 
 a| Set the default Cypher version for a remote database alias when creating it.
@@ -942,7 +1016,7 @@ CASE x ... WHEN contains - 1 THEN ... END
 a| Using a variable named `contains` (or any casing variant, like `CONTAINS`) in addition or subtraction operations within a `WHEN` operand of a xref:expressions/conditional-expressions.adoc#case-simple[simple `CASE`] expression is deprecated.
 To continue using variables with this name, use backticks to quote the variable name:
 
-* Additions: `CASE x ... WHEN ++`contains`++ + 1 THEN ... END` 
+* Additions: `CASE x ... WHEN ++`contains`++ + 1 THEN ... END`
 * Subtractions: `CASE x ... WHEN ++`contains`++ - 1 THEN ... END`
 
 a|
@@ -957,8 +1031,8 @@ CASE x ... WHEN in["abc"] THEN ... END
 ----
 a| Using the `[]` operator on a variable named `in` (or any casing variant, like `IN`) within a `WHEN` operand of a xref:expressions/conditional-expressions.adoc#case-simple[simple `CASE`] expression is deprecated.
 To continue using variables with this name, use backticks to quote the variable name:
-	
-* `CASE x ... WHEN ++`in`++[1] THEN ... END` 
+
+* `CASE x ... WHEN ++`in`++[1] THEN ... END`
 * `CASE x ... WHEN ++`in`++["abc"] THEN ... END`
 
 
@@ -1157,7 +1231,7 @@ label:functionality[]
 label:updated[]
 [source, cypher, role="noheader"]
 ----
-CREATE (n:Label {property: 'name'}), 
+CREATE (n:Label {property: 'name'}),
 ()-[r:REL_TYPE]->()
 ----
 | Neo4j's link:{neo4j-docs-base-uri}/operations-manual/current/database-internals/store-formats/#store-format-overview[block format] now implements xref:appendix/gql-conformance/index.adoc[GQL's] limit on the maximum length of identifiers.
@@ -1208,7 +1282,7 @@ RETURN t AS team, players
 
 [source, cypher, role="noheader"]
 ----
-OPTIONAL CALL db.labels() YIELD label 
+OPTIONAL CALL db.labels() YIELD label
 RETURN label
 ----
 
@@ -1559,7 +1633,7 @@ MATCH SHORTEST 2 GROUPS (:A)-[:R]->{0,10}(:B)
 
 a| Introduced new graph pattern matching keywords to find variations of the xref:patterns/shortest-paths.adoc[shortest paths] between nodes.
 
-a| 
+a|
 label:functionality[]
 label:new[]
 
@@ -4757,4 +4831,4 @@ MATCH (n:N {prop1: 42} WHERE n.prop2 > 42)
 a|
 New syntax that enables inlining of `WHERE` clauses inside node patterns.
 
-|===
+|===

modules/ROOT/pages/expressions/predicates/type-predicate-expressions.adoc

@@ -38,6 +38,122 @@ RETURN val, val IS :: INTEGER AS isInteger
 2+d|Rows: 4
 |===
 
+[role=label--new-Neo4j-2025.10 label--cypher-25-only]
+[[type-predicate-vector]]
+=== Vector values and supertypes
+
+The following examples use `VECTOR` values (constructed using the xref:functions/vector.adoc#functions-vector[`vector()` function]) with `3` dimensions and `INTEGER8` coordinate type.
+
+.Verify a `VECTOR<TYPE>(DIMENSION)` value against a `VECTOR` the same coordinate type and dimension
+[source, cypher]
+----
+WITH vector([1, 2, 3], 3, INTEGER8) AS vector
+RETURN vector IS :: VECTOR<INTEGER8>(3) AS isVector
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| isVector
+
+| true
+
+1+d|Rows: 1
+|===
+
+Although it is not possible to store xref:values-and-types/vector.adoc[`VECTOR`] values without a coordinate type and dimension, it is possible to use the `VECTOR` supertype (encompassing all combinations of `VECTOR<TYPE>(DIMENSION)`) in type predicate expressions.
+
+.Verify a `VECTOR<TYPE>(DIMENSION)` value against the `VECTOR` supertype
+[source, cypher]
+----
+WITH vector([1, 2, 3], 3, INTEGER8) AS vector
+RETURN vector IS :: VECTOR AS isVector
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| isVector
+
+| true
+
+1+d|Rows: 1
+|===
+
+The same is true for the supertypes `VECTOR<TYPE>` (which encompasses all `VECTOR` values with the same coordinate type regardless of the dimension) and `VECTOR(DIMENSION)` (which encompasses all `VECTOR` values with the same dimension regardless of the coordinate type).
+
+.Verify a `VECTOR<TYPE>(DIMENSION)` value against the `VECTOR<TYPE>` supertype
+[source, cypher]
+----
+WITH vector([1, 2, 3], 3, INTEGER8) AS vector
+RETURN vector IS :: VECTOR<INTEGER8> AS isInteger8Vector
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| isInteger8Vector
+
+| true
+
+1+d|Rows: 1
+|===
+
+.Verify a `VECTOR<TYPE>(DIMENSION)` value against the `VECTOR(DIMENSION)` supertype
+[source, cypher]
+----
+WITH vector([1, 2, 3], 3, INTEGER8) AS vector
+RETURN vector IS :: VECTOR(3) AS isDimension3Vector
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| isDimension3Vector
+
+| true
+
+1+d|Rows: 1
+|===
+
+If the coordinate type or dimension in the `VECTOR` does not match what is specified in the type predicate expression, the result will be `false`.
+
+.Verify a `VECTOR<TYPE>(DIMENSION)` value against a `VECTOR` with a different dimension
+[source, cypher]
+----
+WITH vector([1, 2, 3], 3, INTEGER8) AS vector
+RETURN vector IS :: VECTOR(5) AS isDimension5Vector
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| isDimension5Vector
+
+| false
+
+1+d|Rows: 1
+|===
+
+
+.Verify a `VECTOR<TYPE>(DIMENSION)` value against a `VECTOR` with a different coordinate type
+[source, cypher]
+----
+WITH vector([1, 2, 3], 3, INTEGER8) AS vector
+RETURN vector IS :: VECTOR<INTEGER16> AS isInteger16Vector
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| isInteger16Vector
+
+| false
+
+1+d|Rows: 1
+|===
+
+
 [[type-predicate-not]]
 == Type predicate expressions with NOT
 
@@ -189,7 +305,16 @@ Cypher will therefore regard any exact numerical parameter as an `INTEGER` regar
 For example, an `INT16` or an `INT32` passed through from a link:https://neo4j.com/docs/create-applications/[language library] will both be treated by Cypher as an `INTEGER`.
 Note that any exact numerical parameter used must fit within the range of an `INT64`.
 
-[source, cypher, role=test-skip]
+////
+[source, parameters]
+----
+{
+  "int16param": 65537
+}
+----
+////
+
+[source, cypher]
 ----
 RETURN $int16param IS :: INTEGER AS isInteger
 ----
@@ -205,6 +330,9 @@ RETURN $int16param IS :: INTEGER AS isInteger
 
 More information about parameters can be found xref::syntax/parameters.adoc[here].
 
+[NOTE]
+The xref:values-and-types/vector.adoc#vector-type[vector-only coordinate types] cannot be used as the numeric type to verify against in type predicate expressions.
+
 [[type-predicate-syntax-variation]]
 == Syntactical variations of type predicate expressions