revise pages

Author: stefano-ottolenghi

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

@@ -61,7 +61,7 @@ RETURN vector IS :: VECTOR<INTEGER8>(3) AS isVector
 1+d|Rows: 1
 |===
 
-Although 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.
+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]

modules/ROOT/pages/genai-integrations.adoc

@@ -214,11 +214,12 @@ WITH collect(m) AS moviesList // <1>
 WITH moviesList, [movie IN moviesList | movie.title || ': ' || movie.plot] AS batch // <2>
 CALL genai.vector.encodeBatch(batch, 'OpenAI', { token: $openaiToken }) YIELD index, vector
 WITH moviesList, index, vector
-SET moviesList[index].embedding = vector(vector, 1536, FLOAT32)  // <3>
+MATCH (toUpdate:Movie {title: moviesList[index]['title']})
+SET toUpdate.embedding = vector(vector, 1536, FLOAT32)  // <3>
 ----
 
 <1> xref:functions/aggregating.adoc#functions-collect[Collect] all  20 `Movie` nodes into a `LIST<NODE>`.
-<2> Use a xref:expressions/list-expressions.adoc#list-comprehension[list comprehension] (`[]`) to extract the `title` and `plot` properties of the movies in `moviesList` into a new `LIST<STRING>`.
+<2> A xref:expressions/list-expressions.adoc#list-comprehension[list comprehension] (`[]`) extracts the `title` and `plot` properties of the movies in `moviesList` into a new `LIST<STRING>`.
 <3> `db.create.setNodeVectorProperty` is run for each `vector` returned by `genai.vector.encodeBatch()`, and stores that vector as a property named `embedding` on the corresponding node.
 
 .Create embeddings from a large number properties and store them as `VECTOR` properties
@@ -232,7 +233,8 @@ UNWIND range(0, total-1, batchSize) AS batchStart // <3>
 CALL (moviesList, batchStart, batchSize) { // <4>
     WITH [movie IN moviesList[batchStart .. batchStart + batchSize] | movie.title || ': ' || movie.plot] AS batch // <5>
     CALL genai.vector.encodeBatch(batch, 'OpenAI', { token: $openaiToken }) YIELD index, vector
-    SET moviesList[batchStart + index].embedding = vector(vector, 1536, FLOAT32) // <6>
+    MATCH (toUpdate:Movie {title: moviesList[batchStart + index]['title']})
+    SET toUpdate.embedding = vector(vector, 1536, FLOAT32) // <6>
 } IN CONCURRENT TRANSACTIONS OF 1 ROW // <7>
 ----
 
@@ -295,7 +297,7 @@ CALL db.create.setNodeVectorProperty(moviesList[index], 'embedding', vector) //
 ----
 
 <1> xref:functions/aggregating.adoc#functions-collect[Collect] all  20 `Movie` nodes into a `LIST<NODE>`.
-<2> Use a xref:expressions/list-expressions.adoc#list-comprehension[list comprehension] (`[]`) to extract the `title` and `plot` properties of the movies in `moviesList` into a new `LIST<STRING>`.
+<2> A xref:expressions/list-expressions.adoc#list-comprehension[list comprehension] (`[]`) extracts the `title` and `plot` properties of the movies in `moviesList` into a new `LIST<STRING>`.
 <3> `db.create.setNodeVectorProperty` is run for each `vector` returned by `genai.vector.encodeBatch()`, and stores that vector as a property named `embedding` on the corresponding node.
 
 .Create embeddings from a large number properties and store them as `LIST<FLOAT>` values

modules/ROOT/pages/indexes/semantic-indexes/vector-indexes.adoc

@@ -41,7 +41,7 @@ Each word or token in a text is typically represented as high-dimensional vector
 
 The embedding for a particular data object can be created by both proprietary (such as https://cloud.google.com/vertex-ai[Vertex AI] or https://openai.com/[OpenAI]) and open source (such as https://github.com/UKPLab/sentence-transformers[sentence-transformers]) embedding generators, which can produce vector embeddings with dimensions such as 256, 768, 1536, and 3072.
 Vector embeddings are stored as `LIST<INTEGER | FLOAT>` properties on a node or relationship.
-As of Neo4j 2025.xx, they can also be more efficiently stored as xref:values-and-types/vector.adoc[`VECTOR`] properties using Cypher 25.
+As of Neo4j 2025.10, they can also be more efficiently stored as xref:values-and-types/vector.adoc[`VECTOR`] properties using Cypher 25.
 
 [NOTE]
 ====
@@ -82,7 +82,7 @@ A newly created index is not immediately available but is created in the backgro
 [NOTE]
 Creating indexes requires link:{neo4j-docs-base-uri}/operations-manual/current/authentication-authorization/database-administration/#access-control-database-administration-index[the `CREATE INDEX` privilege].
 
-.Create vector index for `Movie` nodes on the `embedding` property 
+.Create vector index for `Movie` nodes on the `embedding` property
 [source, cypher]
 ----
 CREATE VECTOR INDEX moviePlots IF NOT EXISTS // <1>
@@ -105,7 +105,7 @@ To read more about the available similarity functions, see xref:indexes/semantic
 
 You can also create a vector index for relationships with a particular type on a given property using the following syntax:
 
-.Create a vector index for a relationship type on a single property 
+.Create a vector index for a relationship type on a single property
 [source, cypher, role=test-skip]
 ----
 CREATE VECTOR INDEX name IF NOT EXISTS
@@ -229,7 +229,7 @@ If the query vector itself is not wanted, adding the predicate `WHERE score < 1`
 
 To query a relationship vector index, use the link:{neo4j-docs-base-uri}/operations-manual/current/procedures/#procedure_db_index_vector_queryRelationships[`db.index.vector.queryRelationships`] procedure.
 
-.Signature for `db.index.vector.queryRelationships()` 
+.Signature for `db.index.vector.queryRelationships()`
 [source,syntax]
 ----
 db.index.vector.queryRelationships(indexName :: STRING, numberOfNearestNeighbours :: INTEGER, query :: ANY) :: (relationship :: RELATIONSHIP, score :: FLOAT)
@@ -479,7 +479,7 @@ Returns the requested number of approximate nearest neighbor nodes and their sim
 | Use relationship vector index.
 | link:{neo4j-docs-base-uri}/operations-manual/current/procedures/#procedure_db_index_vector_queryRelationships[`db.index.vector.queryRelationships()`]
 | Query the given relationship vector index.
-Returns the requested number of approximate nearest neighbor relationships and their similarity score, ordered by score. 
+Returns the requested number of approximate nearest neighbor relationships and their similarity score, ordered by score.
 
 | Set node vector property.
 | link:{neo4j-docs-base-uri}/operations-manual/current/procedures/#procedure_db_create_setNodeVectorProperty[`db.create.setNodeVectorProperty()`]

modules/ROOT/pages/values-and-types/vector.adoc

@@ -2,64 +2,49 @@
 :description: Information about Cypher's `VECTOR` type.
 :page-role: new-neo4j-2025.10
 
-Cypher supports the construction of a `VECTOR` value that can be stored as xref:indexes/semantic-indexes/vector-indexes.adoc#embeddings[embedding] properties on nodes and relationships and used for efficient semantic retrieval using Neo4j's xref:indexes/semantic-indexes/vector-indexes.adoc[vector indexes] and xref:genai-integrations.adoc[GenAI plugin].
-`VECTOR` values can also be measured and compared (in terms of similarity, distance, and norm) using Cypher's xref:functions/vector.adoc[vector functions].
+`VECTOR` values can be created and stored as xref:indexes/semantic-indexes/vector-indexes.adoc#embeddings[embedding] properties on nodes and relationships, and used for efficient semantic retrieval using xref:indexes/semantic-indexes/vector-indexes.adoc[vector indexes] and the xref:genai-integrations.adoc[GenAI plugin].
+`VECTOR` values can also be measured and compared (in terms of similarity, distance, and norm) using xref:functions/vector.adoc[vector functions].
 
 [[vector-type]]
 == The vector type
 
-The `VECTOR` type is a fixed-length, ordered collection of numeric coordinate values (`INTEGER` or `FLOAT`) stored as a single unit.
-It is defined by its dimension, which sets how many numeric values it holds, and its coordinate type, which specifies the specific numeric data type for those numbers.
-Each numeric value in the list represents a coordinate along one of the vector’s defined dimensions.
-The coordinate type controls the type of each coordinate in the `VECTOR`, influencing precision and storage size.
-A `VECTOR` value must have a dimension and a coordinate type.
+The `VECTOR` type is a fixed-length, ordered collection of numeric values (`INTEGER` or `FLOAT`) stored as a single unit.
+The type of a value is defined by:
 
-.Example `VECTOR` type
+- *Dimension* -- The number of values it contains.
+- *Coordinate type* -- The data type of the entries, determining precision and storage size.
+
+.An example `VECTOR` value
 [source]
 ----
-VECTOR([1.05, 0.123, 5], 3, FLOAT32 NOT NULL)
+vector([1.05, 0.123, 5], 3, FLOAT32)
 ----
 
-In this example, `[1.05, 0.123, 5]` is the coordinates of the `VECTOR`, `3` its dimensionality, and `FLOAT32` the data type for each coordinate value.
-
-.`VECTOR` and `LIST` values
-[NOTE]
-The dimensions and the formatting of a `VECTOR` is similar to a xref:values-and-types/lists.adoc[`LIST`] value.
-However, whereas elements in `LIST` values can be accessed individually with xref:expressions/list-expressions.adoc[list expressions], operations on a `VECTOR` must operate on the entire `VECTOR`: it is not possible to access or slice individual elements of a `VECTOR` value.
-Additionally, Neo4j cannot store lists containing `VECTOR` values.
+In this example, `[1.05, 0.123, 5]` is the list of values, `3` its dimension, and `FLOAT32` the data type of the individual entries. +
+Each number in the list can also be seen as a coordinate along one of the vector's dimensions.
 
-The dimension of a `VECTOR` value must be larger than `0` and less than or equal to `4096`.
 
-The following coordinate types are supported:
+[[valid-values]]
+=== Valid values
 
-.Vector coordinate types
+- A `VECTOR` value must have a dimension and a coordinate type.
+- The dimension of a `VECTOR` value must be larger than `0` and less than or equal to `4096`.
+- Vectors cannot contain lists as elements.
+- Supported coordinate types are: +
++
 [options="header",cols="2*<m"]
 |===
 | Default name | Alias
 
 | `FLOAT` | `FLOAT64`
 | `FLOAT32` |
-| `INTEGER` | `INT`, `INT64`, `SIGNED INTEGER`, `INTEGER64`
+| `INTEGER` | `INT`, `INT64`, `INTEGER64`, `SIGNED INTEGER`
 | `INTEGER8` | `INT8`
 | `INTEGER16`| `INT16`
 | `INTEGER32` | `INT8`
 
 |===
 
-`VECTOR` is a supertype of `VECTOR<TYPE>(DIMENSION)` types.
-The same applies for `VECTOR` types that define only a coordinate type or a dimension:
-
-- `VECTOR` with only a defined dimension is a supertype of all `VECTOR` values of that dimension regardless of the coordinate type.
-For example, `VECTOR(4)` is a supertype of `VECTOR<FLOAT>(4)` and `VECTOR<INT8>(4)`.
-- `VECTOR` with only a defined coordinate type is a supertype of all `VECTOR` values with that coordinate type regardless of the dimension.
-For example, `VECTOR<INT>` is a supertype of `VECTOR<INT>(3)` and `VECTOR<INT>(1024)`.
-
-All of these supertypes can be used in xref:expressions/predicates/type-predicate-expressions.adoc#type-predicate-vector[type predicate expressions] to verify `VECTOR` type values.
-
-See also:
-
-* xref:values-and-types/ordering-equality-comparison.adoc#ordering-and-comparison[Equality, ordering, and comparison of value types -> Ordering vector types]
-* xref:values-and-types/property-structural-constructed.adoc#vector-type-normalization[Property, structural, and constructed values -> Vector type normalization]
 
 [[construct-vector-values]]
 == Construct vector values
@@ -88,26 +73,6 @@ RETURN vector
 
 ====
 
-
-[IMPORTANT]
-====
-Running a query that returns a `VECTOR` value via a link:{neo4j-docs-base-uri}/create-applications/[driver] version < 6.0 does not yield a `VECTOR`, but rather a placeholder `MAP` value.
-A warning will also be attached.
-
-.Result of returning a `VECTOR` with a driver older than 6.0
-[source]
-----
-+----------------------------------------------------------------+
-| n.vector                                                      |
-+----------------------------------------------------------------+
-| {originalType: "VECTOR(1, INTEGER64)", reason: "UNKNOWN_TYPE"} |
-+----------------------------------------------------------------+
-warn: One or more values returned could not be handled by this version of the driver and were replaced with placeholder map values. Please upgrade your driver!
-03N95 (Neo.ClientNotification.UnknownType)
-----
-====
-
-
 .Create a `VECTOR` value using parameters
 ====
 
@@ -143,10 +108,11 @@ RETURN vector
 [[store-vector-properties]]
 == Store vector values as properties
 
-To store a `VECTOR` value as a node or relationship property, use the `vector()` function together with a write clause.
+To store a `VECTOR` value as a node or relationship property, use the `vector()` function and a write clause.
 
 [NOTE]
-Storing `VECTOR` values on an on-prem instance requires the database to be on link:{neo4j-docs-base-uri}/operations-manual/current/database-internals/store-formats/#store-format-overview[block format].
+Storing `VECTOR` values on requires the database to be on link:{neo4j-docs-base-uri}/operations-manual/current/database-internals/store-formats/#store-format-overview[block format].
+This is the default on Aura instances.
 
 .Create a node and a `VECTOR` property
 ====
@@ -200,22 +166,96 @@ RETURN n.vectorProp AS vectorProp
 
 ====
 
-[NOTE]
-It is not possible to store lists of `VECTOR` values.
 
+[[drivers-fallback]]
+== Vectors and client libraries (drivers)
+
+Working with vectors via link:{neo4j-docs-base-uri}/create-applications/[Neo4j's client libraries] results in a different behavior depending on the library version.
+
+- *Versions >= 6.0* -- Vectors are fully supported and mapped into client types (see the _Data types_ page of each language manual).
+- *Versions < 6.0* -- Vectors can be created, attached, and manipulated in queries via Cypher functions, but cannot be returned nor created in the application. +
+It is possible to create and store values as shown in the xref:store-vector-properties[Store vector values as properties] examples, but _returning_ a `VECTOR` results in a placeholder `MAP` value and a warning.
++
+.Result of returning a `VECTOR` with a driver older than 6.0
+[source]
+----
++----------------------------------------------------------------+
+| n.vector                                                       |
++----------------------------------------------------------------+
+| {originalType: "VECTOR(1, INTEGER64)", reason: "UNKNOWN_TYPE"} |
++----------------------------------------------------------------+
+warn: One or more values returned could not be handled by this version of the driver and were replaced with placeholder map values. Please upgrade your driver!
+03N95 (Neo.ClientNotification.UnknownType)
+----
+
+
+[[type-coercion]]
+== Type coercion
+
+_Coercion_ is the action of forcing entries of a different (implicit) type into a vector with a different coordinate type.
 
-[[genai-plugin-vector-indexes]]
-== Vector embeddings, the GenAI plugin, and vector indexes
+When the coordinate type is the same as the type of the given elements, no coercion is done.
+When the coordinate type differs, coercion may be done or an error may be raised depending on the situation.
 
-Storing vector embeddings as `VECTOR` properties with a defined coordinate type has the following benefits:
+*An error is raised* if a value does not fit into the coordinate type.
+If the coordinate type is an `INTEGER` type and all the coordinate values are `INTEGER` values, then an error will be raised if and only if one of the coordinate types does not fit into the size of the specified type.
+The same applies for `FLOAT` vector types: if the elements are all `FLOAT` values then an error will only be raised if one value does not fit into the specified type.
 
-* `VECTOR` values are stored on Neo4j's link:{neo4j-docs-base-uri}/operations-manual/current/database-internals/store-formats/#store-format-overview[block format], ensuring efficient retrieval and computation for operations like similarity search or distance calculations.
-* Defining a coordinate type with the `vector()` function allows `VECTOR` values to be stored more efficiently.
-Additionally, reducing a vectors coordinate type (e.g., from `INTEGER16` to `INTEGER8`) reduces storage requirements and improves performance, provided all values remain within the range supported by the smaller type.
+[source, cypher, test-fail]
+----
+RETURN VECTOR([128], 1, INT8)
+// 22N28: data exception - overflow error. The result of the operation 'vector()' has caused an overflow.
+//   22003: data exception - numeric value out of range. The numeric value 128 is outside the required range.
+----
+
+*Coercion (i.e. lossy conversion) is allowed* when:
 
-For information about how to store embeddings generated by Neo4j as `VECTOR` values with the xref:genai-integrations.adoc[GenAI plugin], see:
+- The list contains `INTEGER` values and the specified vector type is of a `FLOAT` type.
+Precision will be lost for values at the higher end of the range (see the link:https://docs.oracle.com/javase/specs/jls/se21/html/jls-5.html[Java type specification]), but an error will be raised only if the value were to overflow/underflow. +
++
+[source, cypher]
+----
+RETURN VECTOR([987374677], 1, FLOAT32)
+// vector([9.8737466E8], 1, FLOAT32 NOT NULL)
+----
+- The list contains `FLOAT` values and the specified type is of an `INTEGER` type.
+Information may be lost, as all values after the decimal point will be truncated, but an error will be raised only if the value were to overflow/underflow. +
++
+[source, cypher]
+----
+RETURN VECTOR([1.2], 1, INT)
+// vector([1], 1, INTEGER NOT NULL)
+----
+
+
+[[supertypes]]
+== Supertypes
+
+`VECTOR` is a supertype of `VECTOR<TYPE>(DIMENSION)` types.
+The same applies for `VECTOR` types with only a coordinate type or a dimension:
+
+- `VECTOR` with only a defined dimension is a supertype of all `VECTOR` values of that dimension, regardless of the coordinate type.
+For example, `VECTOR(4)` is a supertype of `VECTOR<FLOAT>(4)` and `VECTOR<INT8>(4)`.
+- `VECTOR` with only a defined coordinate type is a supertype of all `VECTOR` values with that coordinate type, regardless of the dimension.
+For example, `VECTOR<INT>` is a supertype of `VECTOR<INT>(3)` and `VECTOR<INT>(1024)`.
+
+All of these supertypes can be used in xref:expressions/predicates/type-predicate-expressions.adoc#type-predicate-vector[type predicate expressions].
+For more information, see:
+
+* xref:values-and-types/ordering-equality-comparison.adoc#ordering-and-comparison[Equality, ordering, and comparison of value types -> Ordering vector types]
+* xref:values-and-types/property-structural-constructed.adoc#vector-type-normalization[Property, structural, and constructed values -> Vector type normalization]
+
+
+[[lists-embeddings-vector-indexes]]
+== Lists, vector embeddings, and vector indexes
+
+`VECTOR` and xref:values-and-types/lists.adoc[`LIST`] values are similar and can both be indexed and searched through using xref:indexes/semantic-indexes/vector-indexes.adoc[vector indexes], but have a few key differences:
+
+- Elements in a `LIST` can be accessed individually, whereas operations on a `VECTOR` must operate on the entire `VECTOR`: it is not possible to access or slice individual elements.
+- Storing vector embeddings as `VECTOR` properties with a defined coordinate type allows them to be stored more efficiently.
+Moreover, reducing a vector's coordinate type (e.g., from `INTEGER16` to `INTEGER8`) downsizes storage requirements and improves performance, provided all values remain within the range supported by the smaller type.
+
+For information about how to store embeddings as `VECTOR` values with the xref:genai-integrations.adoc[GenAI plugin], see:
 
 * xref:genai-integrations.adoc#single-embedding[Generate a single embedding and store it]
 * xref:genai-integrations.adoc#multiple-embeddings[Generate multiple embeddings and store them]
-
-Embeddings stored as `VECTOR` properties can be indexed and searched semantically using xref:indexes/semantic-indexes/vector-indexes.adoc[vector indexes].