Document VECTOR type and new vector functions

modules/ROOT/content-nav.adoc

@@ -63,6 +63,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/deprecations-additions-removals-compatibility.adoc

@@ -21,6 +21,91 @@ Replacement syntax for deprecated and removed features are also indicated.
 Cypher 25 was introduced in Neo4j 2025.06 and can only be used on Neo4j 2025.06+ databases.
 Features removed in Cypher 25 are still available on Neo4j 2025.06+ databases either by prepending a query with `CYPHER 5` or by having Cypher 5 as the default language for the database.
 
+[[cypher-deprecations-additions-removals-2025.xx]]
+== Neo4j 2025.xx
+
+=== New in Cypher 25
+
+[cols="2", options="header"]
+|===
+| Feature
+| Details
+
+a|
+label:functionality[]
+label:new[]
+[source, cypher, role="noheader"]
+----
+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, role="noheader"]
+----
+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, role="noheader"]
+----
+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, role="noheader"]
+----
+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, role="noheader"]
+----
+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"]
+|===
+| Feature
+| Details
+
+a|
+label:functionality[]
+label:updated[]
+[source, cypher, role="noheader"]
+----
+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.
+|===
+
 [[cypher-deprecations-additions-removals-2025.06]]
 == Neo4j 2025.06
 

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-2025.xx]
+[[type-predicate-vector]]
+=== Vector values
+
+Whilst it is not possible to store a xref:values-and-types/vector.adoc[`VECTOR`] value 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.
+
+The following examples uses a `VECTOR` (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 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
+|===
+
+.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
+|===
+
+
 [[type-predicate-not]]
 == Type predicate expressions with NOT
 
@@ -205,6 +321,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
 

modules/ROOT/pages/functions/index.adoc

@@ -167,13 +167,13 @@ Converts a `LIST<ANY>` of values to a `LIST<BOOLEAN>` values.
 If any values are not convertible to `BOOLEAN` they will be null in the `LIST<BOOLEAN>` returned.
 
 1.1+| xref::functions/list.adoc#functions-tofloatlist[`toFloatList()`]
-| `toFloatList(input :: LIST<ANY>) :: LIST<FLOAT>`
+| `toFloatList(input :: VECTOR \| LIST<ANY>) :: LIST<FLOAT>`
 a|
 Converts a `LIST<ANY>` to a `LIST<FLOAT>` values.
 If any values are not convertible to `FLOAT` they will be null in the `LIST<FLOAT>` returned.
 
 1.1+| xref::functions/list.adoc#functions-tointegerlist[`toIntegerList()`]
-| `toIntegerList(input :: LIST<ANY>) :: LIST<INTEGER>`
+| `toIntegerList(input :: VECTOR \| LIST<ANY>) :: LIST<INTEGER>`
 a|
 Converts a `LIST<ANY>` to a `LIST<INTEGER>` values.
 If any values are not convertible to `INTEGER` they will be null in the `LIST<INTEGER>` returned.
@@ -791,12 +791,29 @@ Vector functions allow you to compute the similarity scores of vector pairs.
 |===
 | Function | Signature | Description
 
+1.1+| xref::functions/vector.adoc#functions-vector[`vector()`]
+| `vector(vectorValue :: STRING \| LIST<INTEGER \| FLOAT>, dimension :: INTEGER, coordinateType :: [INTEGER64, INTEGER32, INTEGER16, INTEGER8, FLOAT64, FLOAT32]) :: VECTOR`
+| Constructs a `VECTOR` value. label:new[Introduced in Neo4j 2025.xx]
+
 1.1+| xref::functions/vector.adoc#functions-similarity-cosine[`vector.similarity.cosine()`]
-| `vector.similarity.cosine(a :: LIST<INTEGER \| FLOAT>, b :: LIST<INTEGER \| FLOAT>) :: FLOAT`
+| `vector.similarity.cosine(a :: VECTOR \| LIST<INTEGER \| FLOAT>, b :: VECTOR \| LIST<INTEGER \| FLOAT>) :: FLOAT`
 | Returns a `FLOAT` representing the similarity between the argument vectors based on their cosine.
 
 1.1+| xref::functions/vector.adoc#functions-similarity-euclidean[`vector.similarity.euclidean()`]
-| `vector.similarity.euclidean(a :: LIST<INTEGER \| FLOAT>, b :: LIST<INTEGER \| FLOAT>) :: FLOAT`
+| `vector.similarity.euclidean(a :: VECTOR \| LIST<INTEGER \| FLOAT>, b :: VECTOR \| LIST<INTEGER \| FLOAT>) :: FLOAT`
 | Returns a `FLOAT` representing the similarity between the argument vectors based on their Euclidean distance.
 
+1.1+| xref::functions/vector.adoc#functions-vector_dimension_count[`vector_dimension_count()`]
+| `(vector :: VECTOR) :: INTEGER`
+| Returns the dimension of a `VECTOR`. label:new[Introduced in Neo4j 2025.xx]
+
+1.1+| xref::functions/vector.adoc#functions-vector_distance[`vector_distance()`]
+| `(vector1 :: VECTOR, vector2 :: VECTOR, vectorDistanceMetric :: [EUCLIDEAN, EUCLIDEAN_SQUARED, MANHATTAN, COSINE, DOT, HAMMING]) :: FLOAT`
+| Returns a `FLOAT` representing the distance between the two vector values based on the selected `vectorDistanceMetric` algorithm. label:new[Introduced in Neo4j 2025.xx]
+
+1.1+| xref::functions/vector.adoc#functions-vector_norm[`vector_norm()`]
+| `vector_norm(vector :: VECTOR, vectorDistanceMetric :: [EUCLIDEAN, MANHATTAN]) :: FLOAT`
+| Returns a `FLOAT` representing the distance between the given vector and a vector of the same dimension with all coordinates set to zero, calculated using the specified `vectorDistanceMetric`. label:new[Introduced in Neo4j 2025.xx]
+
 |===
+

modules/ROOT/pages/functions/list.adoc

@@ -433,7 +433,7 @@ The property named `likedColors` and a `LIST<ANY>` comprising all but the first
 | Any `BOOLEAN` value in `input` is preserved.
 | If the `input` is `null`, `null` will be returned.
 | If the `input` is not a `LIST<ANY>`, 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].
+| The conversion for each value in `input` is done according to the xref::functions/scalar.adoc#functions-tobooleanornull[`toBooleanOrNull()` function].
 
 |===
 
@@ -470,19 +470,20 @@ toBooleanList(['a string', true, 'false', null, ['A','B']]) as mixedList
 .Details
 |===
 | *Syntax* 3+| `toFloatList(input)`
-| *Description* 3+| Converts a `LIST<ANY>` to a `LIST<FLOAT>` values. If any values are not convertible to `FLOAT` they will be null in the `LIST<FLOAT>` returned.
+| *Description* 3+| Converts a `LIST<ANY>` or a `VECTOR` to a `LIST<FLOAT>` values. If any values are not convertible to `FLOAT` they will be null in the `LIST<FLOAT>` returned.
 .2+| *Arguments* | *Name* | *Type* | *Description*
-| `input` | `LIST<ANY>` | A list of values to be converted into a list of floats.
+| `input` | `VECTOR` \| `LIST<ANY>` | A list of values or a vector value to be converted into a list of floats.
 | *Returns* 3+| `LIST<FLOAT>`
 |===
 
 .Considerations
 |===
 
-| Any `null` element in `list` is preserved.
-| Any `FLOAT` value in `list` is preserved.
+| Any `null` element in `input` is preserved.
+| Any `FLOAT` value in `input` is preserved.
 | If the `input` is `null`, `null` will be returned.
-| If the `input` is not a `LIST<ANY>`, an error will be returned.
+| If the `input` is not a `VECTOR` or `LIST<ANY>`, an error will be returned.
+| `input` accepts `VECTOR` values as of Neo4j 2025.xx
 | The conversion for each value in `input` is done according to the xref::functions/scalar.adoc#functions-tofloatornull[`toFloatOrNull()` function].
 
 |===
@@ -520,9 +521,9 @@ toFloatList(['a string', 2.5, '3.14159', null, ['A','B']]) as mixedList
 .Details
 |===
 | *Syntax* 3+| `toIntegerList(input)`
-| *Description* 3+| Converts a `LIST<ANY>` to a `LIST<INTEGER>` values. If any values are not convertible to `INTEGER` they will be null in the `LIST<INTEGER>` returned.
+| *Description* 3+| Converts a `LIST<ANY>` or a `VECTOR` to a `LIST<INTEGER>` values. If any values are not convertible to `INTEGER` they will be null in the `LIST<INTEGER>` returned.
 .2+| *Arguments* | *Name* | *Type* | *Description*
-| `input` | `LIST<ANY>` | A list of values to be converted into a list of integers.
+| `input` | `VECTOR` \| `LIST<ANY>` | A list of values or a vector value to be converted into a list of integers.
 | *Returns* 3+| `LIST<INTEGER>`
 |===
 
@@ -532,7 +533,8 @@ toFloatList(['a string', 2.5, '3.14159', null, ['A','B']]) as mixedList
 | 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<ANY>`, an error will be returned.
+| If the `input` is not a `VECTOR` or a `LIST<ANY>`, an error will be returned.
+| `input` accepts `VECTOR` values as of Neo4j 2025.xx
 | The conversion for each value in `list` is done according to the xref::functions/scalar.adoc#functions-tointegerornull[`toIntegerOrNull()` function].
 
 |===
@@ -579,11 +581,11 @@ toIntegerList(['a string', 2, '5', null, ['A','B']]) as mixedList
 .Considerations
 |===
 
-| Any `null` element in `list` is preserved.
-| Any `STRING` value in `list` is preserved.
-| If the `list` is `null`, `null` will be returned.
-| If the `list` is not a `LIST<ANY>`, an error will be returned.
-| The conversion for each value in `list` is done according to the xref::functions/string.adoc#functions-tostringornull[`toStringOrNull()` function].
+| Any `null` element in `input` is preserved.
+| Any `STRING` value in `input` is preserved.
+| If the `input` is `null`, `null` will be returned.
+| If the `input` is not a `LIST<ANY>`, an error will be returned.
+| The conversion for each value in `input` is done according to the xref::functions/string.adoc#functions-tostringornull[`toStringOrNull()` function].
 
 |===