diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index 61edc54f4..34b5d4bb3 100644 --- a/modules/ROOT/content-nav.adoc +++ b/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[] diff --git a/modules/ROOT/pages/expressions/predicates/type-predicate-expressions.adoc b/modules/ROOT/pages/expressions/predicates/type-predicate-expressions.adoc index 90eaa9872..2f203d2fc 100644 --- a/modules/ROOT/pages/expressions/predicates/type-predicate-expressions.adoc +++ b/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(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(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*` (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(DIMENSION)` value against the `VECTOR` supertype +[source, cypher] +---- +WITH vector([1, 2, 3], 3, INTEGER8) AS vector +RETURN vector IS :: VECTOR AS isInteger8Vector +---- + +.Result +[role="queryresult",options="header,footer",cols="1*(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*(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*(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 AS isInteger16Vector +---- + +.Result +[role="queryresult",options="header,footer",cols="1*(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(3) AS isVector +---- + +.Result +[role="queryresult",options="header,footer",cols="1*` of values to a `LIST` values. If any values are not convertible to `BOOLEAN` they will be null in the `LIST` returned. 1.1+| xref::functions/list.adoc#functions-tofloatlist[`toFloatList()`] -| `toFloatList(input :: LIST) :: LIST` +| `toFloatList(input :: VECTOR \| LIST) :: LIST` a| Converts a `LIST` to a `LIST` values. If any values are not convertible to `FLOAT` they will be null in the `LIST` returned. 1.1+| xref::functions/list.adoc#functions-tointegerlist[`toIntegerList()`] -| `toIntegerList(input :: LIST) :: LIST` +| `toIntegerList(input :: VECTOR \| LIST) :: LIST` a| Converts a `LIST` to a `LIST` values. If any values are not convertible to `INTEGER` they will be null in the `LIST` 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, 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, b :: LIST) :: FLOAT` +| `vector.similarity.cosine(a :: VECTOR \| LIST, b :: VECTOR \| LIST) :: 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, b :: LIST) :: FLOAT` +| `vector.similarity.euclidean(a :: VECTOR \| LIST, b :: VECTOR \| LIST) :: 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] + |=== + diff --git a/modules/ROOT/pages/functions/list.adoc b/modules/ROOT/pages/functions/list.adoc index 99ed3b099..4c7a85f55 100644 --- a/modules/ROOT/pages/functions/list.adoc +++ b/modules/ROOT/pages/functions/list.adoc @@ -433,7 +433,7 @@ The property named `likedColors` and a `LIST` 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`, 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` to a `LIST` values. If any values are not convertible to `FLOAT` they will be null in the `LIST` returned. +| *Description* 3+| Converts a `LIST` or a `VECTOR` 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. +| `input` | `VECTOR` \| `LIST` | A list of values or a vector value to be converted into a list of floats. | *Returns* 3+| `LIST` |=== .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`, an error will be returned. +| If the `input` is not a `VECTOR` or `LIST`, 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` to a `LIST` values. If any values are not convertible to `INTEGER` they will be null in the `LIST` returned. +| *Description* 3+| Converts a `LIST` or a `VECTOR` 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. +| `input` | `VECTOR` \| `LIST` | A list of values or a vector value to be converted into a list of integers. | *Returns* 3+| `LIST` |=== @@ -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`, an error will be returned. +| If the `input` is not a `VECTOR` or a `LIST`, 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`, 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`, 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]. |=== diff --git a/modules/ROOT/pages/functions/vector.adoc b/modules/ROOT/pages/functions/vector.adoc index 8927aba94..2d7c7f71c 100644 --- a/modules/ROOT/pages/functions/vector.adoc +++ b/modules/ROOT/pages/functions/vector.adoc @@ -1,14 +1,98 @@ :description: Vector functions allow you to compute the similarity scores of vector pairs. :table-caption!: - :link-vector-indexes: xref:indexes/semantic-indexes/vector-indexes.adoc - -[[query-functions-vector]] = Vector functions -Vector functions allow you to compute the similarity scores of vector pairs. -These vector similarity functions are identical to those used by Neo4j's {link-vector-indexes}[vector search indexes]. +Vector functions allow you to construct xref:values-and-types/vector.adoc[`VECTOR` values], compute the similarity and distance scores of vector pairs, and calculate the size of a vector. + +[role=label--new-2025.xx] +[[functions-vector]] +== vector() + +.Details +|=== +| *Syntax* 3+| `vector(vectorValue, dimension, coordinateType)` +| *Description* 3+| Constructs a `VECTOR` value. +.4+| *Arguments* | *Name* | *Type* | *Description* +| `vectorValue` | `STRING` \| `LIST` | The numeric values to create the vector coordinates from. +| `dimension` | `INTEGER` | The dimension (number of coordinates) of the vector. +| `coordinateType` | `[INTEGER64, INTEGER32, INTEGER16, INTEGER8, FLOAT64, FLOAT32]` | The type of each coordinate in the vector. +| *Returns* 3+| `VECTOR` +|=== + +[NOTE] +The `VECTOR` values generated by the `vector()` function can be xref:values-and-types/vector.adoc#store-vector-properties[stored as properties]. +As such, the `vector()` function can be used to store the embeddings generated by Neo4j's xref:genai-integrations.adoc[GenAI plugin] as `VECTOR` property values. +`VECTOR` properties can be semantically searched by a xref:indexes/semantic-indexes/vector-indexes.adoc[vector index]. + +.Considerations +|=== + +| If a `STRING` is used in `vectorValue`, it must start and end with square brackets (`[]`). +The values inside the brackets must be a number represented in either decimal or scientific notation and must be comma separated. +| `null`, `NaN`, and `Infinity` values are not allowed as coordinate values. +| If `vectorValue` contain elements that are not of the specified `coordinateType`, they will be coerced to that coordinate type if possible. +This includes the potential of lossy conversion in cases where a larger type, e.g. `INTEGER64` does not fit into the specified type, e.g. `FLOAT32`. +| `dimension` must be greater than `0` and less than or equal to `4096`. +| A `null` `vectorValue` or `dimension` will return `null`. +|=== + +.vector() +===== + +.Construct a `VECTOR` value +[source, cypher] +---- +WITH vector([1, 2, 3], 3, INTEGER) AS vector +RETURN vector, valueType(vector) AS vectorType +---- + +.Result +[role="queryresult",options="header,footer",cols="2*(3) NOT NULL" + +2+d|Rows: 1 +|=== + + +.Construct a `VECTOR` value with a `STRING` `vectorValue` +[source, cypher] +---- +WITH vector("[1.05000e+00, 0.123, 5]", 3, FLOAT32) as vector +RETURN vector, valueType(vector) AS vectorType +---- + +.Result +[role="queryresult",options="header,footer",cols="2*(3) NOT NULL" + +2+d|Rows: 1 +|=== + +.`null` values +[source, cypher] +---- +RETURN vector(null, 3, FLOAT32) AS nullVectorValue, + vector([1, 2, 3], null, INTEGER8) AS nullDimension +---- + +.Result +[role="queryresult",options="header,footer",cols="2*` | A list representing the first vector. -| `b` | `LIST` | A list representing the second vector. +| `a` | `VECTOR` \| `LIST` | A vector or list value representing the first vector. +| `b` | `VECTOR` \| `LIST` | A vector or list value representing the second vector. | *Returns* 3+| `FLOAT` |=== @@ -36,6 +120,7 @@ For more details, see the {link-vector-indexes}#similarity-functions[vector inde | The implementation is identical to that of the latest available vector index provider (`vector-2.0`). | `vector.similarity.cosine()` returns the neighborhood of nodes along with their respective cosine similarity scores, sorted in descending order of similarity. The similarity score range from `0` and `1`, with scores closer to `1` indicating a higher degree of similarity between the indexed vector and the query vector. +| The input arguments `a` and `b` accept `VECTOR` values as of Neo4j 2025.xx. |=== @@ -48,8 +133,8 @@ The similarity score range from `0` and `1`, with scores closer to `1` indicatin | *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. +| `a` | `VECTOR` \| `LIST` | A vector or list value representing the first vector. +| `b` | `VECTOR` \| `LIST` | A vector or list value representing the second vector. | *Returns* 3+| `FLOAT` |=== @@ -66,6 +151,7 @@ For more details, see the {link-vector-indexes}#similarity-functions[vector inde | The implementation is identical to that of the latest available vector index provider (`vector-2.0`). | `vector.similarity.euclidean()` returns the neighborhood of nodes along with their respective Euclidean similarity scores, sorted in descending order of similarity. The similarity score range from `0` and `1`, with scores closer to `1` indicating a higher degree of similarity between the indexed vector and the query vector. +| The input arguments `a` and `b` accept `VECTOR` values as of Neo4j 2025.xx. |=== @@ -85,9 +171,9 @@ To create the graph used in this example, run the following query in an empty Ne [source, cypher, role=test-setup] ---- CREATE - (:Node { id: 1, vector: [1.0, 4.0, 2.0]}), - (:Node { id: 2, vector: [3.0, -2.0, 1.0]}), - (:Node { id: 3, vector: [2.0, 8.0, 3.0]}); + (:Node { id: 1, vector: vector([1.0, 4.0, 2.0], 3, FLOAT32) }), + (:Node { id: 2, vector: vector([3.0, -2.0, 1.0], 3, FLOAT32) }), + (:Node { id: 3, vector: vector([2.0, 8.0, 3.0], 3, FLOAT32) }); ---- Given a parameter `query` (here set to `[4.0, 5.0, 6.0]`), you can query for the two nearest neighbors of that query vector by Euclidean distance. @@ -100,7 +186,7 @@ MATCH (node:Node) WITH node, vector.similarity.euclidean($query, node.vector) AS score RETURN node, score ORDER BY score DESCENDING -LIMIT 2; +LIMIT 2 ---- This returns the two nearest neighbors. @@ -125,3 +211,201 @@ This returns the two nearest neighbors. ====== +[role=label--new-2025.xx] +[[functions-vector_dimension_count]] +== vector_dimension_count() + +.Details +|=== +| *Syntax* 3+| `vector_dimension_count(vector)` +| *Description* 3+| Returns the dimension of a `VECTOR`. +.2+| *Arguments* | *Name* | *Type* | *Description* +| `vector` | `VECTOR` | The vector to calculate the dimension of. +| *Returns* 3+| `INTEGER` +|=== + +.Considerations +|=== + +| If `vector` is not a xref:values-and-types/vector.adoc[`VECTOR`] value, an error will be thrown. +| The xref:functions/scalar.adoc#functions-size[`size()`] function can also be used to return the dimension of a `VECTOR` value. + +|=== + +.vector_dimension_count() +===== + +.Calculate the size of a `VECTOR` +[source, cypher] +---- +RETURN vector_dimension_count(vector([1, 2, 3], 3, INTEGER)) AS size +---- + + +.Result +[role="queryresult",options="header,footer",cols="1*`. +To convert and store this value as a xref:values-and-types/vector.adoc[`VECTOR` property type (introduced in Neo4j 2025.xx)], use the xref:functions/vector.adoc#functions-vector[`vector()`] function. +Storing `VECTOR` values on an on-prem instance requires Enterprise Edition and using Neo4j's link:{neo4j-docs-base-uri}/operations-manual/current/database-internals/store-formats/#store-format-overview[block format]. + +.Signature for `vector()` label:function[] +[source] +---- +vector(vectorValue :: STRING | LIST, dimension :: INTEGER, coordinateType :: [INTEGER64, INTEGER32, INTEGER16, INTEGER8, FLOAT64, FLOAT32]) :: VECTOR +---- + +.Create a `VECTOR` embedding property for the Godfather +[source,cypher,role=test-skip] +---- +MATCH (m:Movie {title:'Godfather, The'}) +WHERE m.plot IS NOT NULL AND m.title IS NOT NULL +WITH m, m.title || ' ' || m.plot AS titleAndPlot // <1> +WITH m, genai.vector.encode(titleAndPlot, 'OpenAI', { token: $token }) AS propertyVector // <2> +SET m.embedding = vector(propertyVector, 1536, FLOAT32) // <3> +RETURN m.embedding AS embedding +---- + +<1> Concatenate the `title` and `plot` of the `Movie` into a single `STRING`. +<2> Create a 1536 dimensional embedding from the `titleAndPlot`. +<3> Store the `propertyVector` as a new `VECTOR` `embedding` property on The Godfather node. +====== + + +[.include-with-Store-embedding-as-a-list] +====== + +Use the `db.create.setNodeVectorProperty` procedure to store an embedding as a `LIST` value to a node property. .Signature for `db.create.setNodeVectorProperty` label:procedure[] [source,syntax] @@ -74,7 +110,7 @@ Use the `db.create.setNodeVectorProperty` procedure to store an embedding to a n db.create.setNodeVectorProperty(node :: NODE, key :: STRING, vector :: ANY) ---- -Use the `db.create.setRelationshipVectorProperty` procedure to store an embedding to a relationship property. +Use the `db.create.setRelationshipVectorProperty` procedure to store an embedding as a `LIST` value to a relationship property. .Signature for `db.create.setRelationshipVectorProperty` label:procedure[] [source,syntax] @@ -88,10 +124,7 @@ db.create.setRelationshipVectorProperty(relationship :: RELATIONSHIP, key :: STR The embeddings are stored as properties on nodes or relationships with the type `LIST`. -.Create an embedding from a single property and store it -==== - -.Create an embedding property for the Godfather +.Create a `LIST` embedding property for the Godfather [source,cypher,role=test-skip] ---- MATCH (m:Movie {title:'Godfather, The'}) @@ -104,7 +137,11 @@ RETURN m.embedding AS embedding <1> Concatenate the `title` and `plot` of the `Movie` into a single `STRING`. <2> Create a 1536 dimensional embedding from the `titleAndPlot`. -<3> Store the `propertyVector` as a new `embedding` property on The Godfather node. +<3> Store the `propertyVector` as a new `LIST `embedding` property on The Godfather node. + +====== +==== + .Result [source, "queryresult"] @@ -118,12 +155,11 @@ RETURN m.embedding AS embedding [NOTE] This result only shows the first 4 of the 1536 numbers in the embedding. -==== [[multiple-embeddings]] -== Generating a batch of embeddings and store them +== Generate a batch of embeddings and store them -Use the `genai.vector.encodeBatch` procedure to generate many vector embeddings with a single API request. +Use the `genai.vector.encodeBatch()` procedure to generate many vector embeddings with a single API request. This procedure takes a list of resources as an input, and returns the same number of result rows, instead of a single one. [IMPORTANT] @@ -132,7 +168,7 @@ This procedure attempts to generate embeddings for all supplied resources in a s Therefore, it is recommended to see the respective provider's documentation for details on, for example, the maximum number of embeddings that can be generated per request. ==== -.Signature for `genai.vector.encodeBatch` label:procedure[] +.Signature for `genai.vector.encodeBatch()` label:procedure[] [source,syntax] ---- genai.vector.encodeBatch(resources :: LIST, provider :: STRING, configuration :: MAP = {}) :: (index :: INTEGER, resource :: STRING, vector :: LIST) @@ -152,9 +188,101 @@ Each returned row contains the following columns: * The `resource` (a `STRING`) is the name of the input resource. * The `vector` (a `LIST`) is the generated vector embedding for this resource. -.Create embeddings from a limited number of properties and store them + + +[.tabbed-example] ==== +[.include-with-Store-embeddings-as-vectors] +====== + +`genai.vector.encode()` returns a `LIST`. +To convert and store this value as a xref:values-and-types/vector.adoc[`VECTOR` property type (introduced in Neo4j 2025.xx)], use the xref:functions/vector.adoc#functions-vector[`vector()`] function. +Storing `VECTOR` values on an on-prem instance requires Enterprise Edition and using Neo4j's link:{neo4j-docs-base-uri}/operations-manual/current/database-internals/store-formats/#store-format-overview[block format]. + +.Signature for `vector()` label:function[] +[source] +---- +vector(vectorValue :: STRING | LIST, dimension :: INTEGER, coordinateType :: [INTEGER64, INTEGER32, INTEGER16, INTEGER8, FLOAT64, FLOAT32]) :: VECTOR +---- + +.Create embeddings from a limited number of properties and store them as `VECTOR` properties +[source,cypher,role=test-skip] +---- +MATCH (m:Movie WHERE m.plot IS NOT NULL) +WITH m +LIMIT 20 +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: $token }) YIELD index, vector +WITH moviesList, index, vector +CALL db.create.setNodeVectorProperty(moviesList[index], 'embedding', vector) // <3> +---- + +<1> xref:functions/aggregating.adoc#functions-collect[Collect] all 20 `Movie` nodes into a `LIST`. +<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`. +<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 +[source, cypher, role=test-skip] +---- +MATCH (m:Movie WHERE m.plot IS NOT NULL) +WITH collect(m) AS moviesList, // <1> + count(*) AS total, + 100 AS batchSize // <2> +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: $token }) YIELD index, vector + CALL db.create.setNodeVectorProperty(moviesList[batchStart + index], 'embedding', vector) // <6> +} IN CONCURRENT TRANSACTIONS OF 1 ROW <7> +---- + +<1> xref:functions/aggregating.adoc#functions-collect[Collect] all returned `Movie` nodes into a `LIST`. +<2> `batchSize` defines the number of nodes in `moviesList` to be processed at once. +Because vector embeddings can be very large, a larger batch size may require significantly more memory on the Neo4j server. +Too large a batch size may also exceed the provider's threshold. +<3> Process `Movie` nodes in increments of `batchSize`. +The end range `total-1` is due to `range` being inclusive on both ends. +<4> A xref:subqueries/subqueries-in-transactions.adoc[`CALL` subquery] executes a separate transaction for each batch. +Note that this `CALL` subquery uses a xref:subqueries/call-subquery.adoc#variable-scope-clause[variable scope clause]. +<5> `batch` is a list of strings, each being the concatenation of `title` and `plot` of one movie. +<6> The procedure sets `vector` as value for the property named `embedding` for the node at position `batchStart + index` in the `moviesList`. +<7> Set to `1` the amount of batches to be processed at once. +For more information on concurrency in transactions, see xref:subqueries/subqueries-in-transactions.adoc#concurrent-transactions[`CALL` subqueries -> Concurrent transactions]). + +[NOTE] +This example may not scale to larger datasets, as `collect(m)` requires the whole result set to be loaded in memory. +For an alternative method more suitable to processing large amounts of data, see link:https://neo4j.com/docs/genai/tutorials/embeddings-vector-indexes/[GenAI documentation - Embeddings & Vector Indexes Tutorial -> Create embeddings with cloud AI providers]. + +====== + + +[.include-with-Store-embeddings-as-lists] +====== + +Use the `db.create.setNodeVectorProperty` procedure to store an embedding as a `LIST` value to a node property. + +.Signature for `db.create.setNodeVectorProperty` label:procedure[] +[source,syntax] +---- +db.create.setNodeVectorProperty(node :: NODE, key :: STRING, vector :: ANY) +---- + +Use the `db.create.setRelationshipVectorProperty` procedure to store an embedding as a `LIST` value to a relationship property. + +.Signature for `db.create.setRelationshipVectorProperty` label:procedure[] +[source,syntax] +---- +db.create.setRelationshipVectorProperty(relationship :: RELATIONSHIP, key :: STRING, vector :: ANY) +---- +* `node` or `relationship` is the entity in which the new property will be stored. +* `key` (a `STRING`) is the name of the new property containing the embedding. +* `vector` is the object containing the embedding. + +The embeddings are stored as properties on nodes or relationships with the type `LIST`. + +.Create embeddings from a limited number of properties and store them as `LIST` properties [source, cypher, role=test-skip] ---- MATCH (m:Movie WHERE m.plot IS NOT NULL) @@ -169,11 +297,9 @@ CALL db.create.setNodeVectorProperty(moviesList[index], 'embedding', vector) // <1> xref:functions/aggregating.adoc#functions-collect[Collect] all 20 `Movie` nodes into a `LIST`. <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`. -<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. -==== +<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 of properties and store them -==== +.Create embeddings from a large number properties and store them as `LIST` values [source, cypher, role=test-skip] ---- MATCH (m:Movie WHERE m.plot IS NOT NULL) @@ -205,13 +331,14 @@ For more information on concurrency in transactions, see xref:subqueries/subquer This example may not scale to larger datasets, as `collect(m)` requires the whole result set to be loaded in memory. For an alternative method more suitable to processing large amounts of data, see link:https://neo4j.com/docs/genai/tutorials/embeddings-vector-indexes/[GenAI documentation - Embeddings & Vector Indexes Tutorial -> Create embeddings with cloud AI providers]. +====== ==== [[ai-providers]] == GenAI providers The following GenAI providers are supported for generating vector embeddings. -Each provider has its own configuration map that can be passed to `genai.vector.encode` or `genai.vector.encodeBatch`. +Each provider has its own configuration map that can be passed to `genai.vector.encode` or `genai.vector.encodeBatch()`. [[vertex-ai]] === Vertex AI diff --git a/modules/ROOT/pages/indexes/semantic-indexes/vector-indexes.adoc b/modules/ROOT/pages/indexes/semantic-indexes/vector-indexes.adoc index 06dd47696..f48bafa76 100644 --- a/modules/ROOT/pages/indexes/semantic-indexes/vector-indexes.adoc +++ b/modules/ROOT/pages/indexes/semantic-indexes/vector-indexes.adoc @@ -40,7 +40,8 @@ An embedding is a numerical representation of a data object, such as a text, ima Each word or token in a text is typically represented as high-dimensional vector where each dimension represents a certain aspect of the word’s meaning. 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. -In Neo4j, vector embeddings are stored as `LIST` properties on a node or relationship. +Vector embeddings are stored as `LIST` 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. [NOTE] ==== @@ -51,7 +52,7 @@ For information about how embeddings can be generated and stored as properties, ==== For example, the movie The Godfather, has the following `plot`: `"The aging patriarch of an organized crime dynasty transfers control of his clandestine empire to his reluctant son."` -This is its 1536-dimensional `embedding` property, where each element in the `LIST` represents a particular aspect of the plot's meaning: +This is its 1536-dimensional `embedding` property, where each coordinate in the `LIST` or `VECTOR` represents a particular aspect of the plot's meaning: ---- [0.005967312026768923, -0.03817005082964897, 0.0014667075593024492, -0.03868866711854935, -0.006505374796688557, 0.020900176838040352, -0.0027551413513720036, -0.0024731445591896772, -0.03734026849269867, -0.02228747308254242, 0.028783122077584267, 0.017905177548527718, 0.011396560817956924, 0.014235977083444595, 0.023143187165260315, -0.014184115454554558, 0.029846282675862312, -0.011928141117095947, 0.018838683143258095, -0.0019172541797161102, 0.0033483069855719805, 0.009497134014964104, -0.03516208380460739, 0.0021441481076180935, 0.002657901030033827, 0.0030760341323912144, 0.004255882930010557, -0.020809419453144073, 0.02358401007950306, -0.013808120042085648, 0.01064456906169653, -0.006975369527935982, 0.007318951655179262, -0.013872946612536907, 0.005905726458877325, -0.010689947754144669, 0.0020225979387760162, -0.016245609149336815, -0.00038815077277831733, -0.007163367234170437, 0.027668101713061333, 0.007215228863060474, -0.009380445815622807, -0.02956104464828968, -0.000863007502630353, 0.012142069637775421, 0.0012957267463207245, -0.027953339740633965, -0.016414159908890724, 0.008453421294689178, -0.0010777463903650641, 0.03311355784535408, -0.013639570213854313, -0.052457891404628754, 0.0010242642601951957, 0.0034390646032989025, -0.01049546804279089, 0.006456754636019468, 0.003970644902437925, -0.011629937216639519, 0.005280147306621075, -0.023402493447065353, -0.014689764939248562, -0.007623638026416302, -0.002453696448355913, 0.02290981076657772, 0.0017989451298490167, 0.0013427261728793383, -0.001776255783624947, -0.002414800226688385, 0.04833490028977394, 0.031142819672822952, -0.0033013075590133667, 0.017879245802760124, 0.0070077828131616116, -0.016154851764440536, -0.005772831384092569, 0.019875913858413696, -0.018008900806307793, 0.012764407321810722, 0.0055232481099665165, -0.027901478111743927, -0.0034909259993582964, 0.0307279285043478, 0.006472961511462927, 0.008861830458045006, -0.01802186481654644, 0.018281172960996628, -0.014223011210560799, -0.00018313586770091206, 0.0026352116838097572, 0.0006754148053005338, 0.014975002966821194, 0.024361930787563324, -0.017166150733828545, 0.0028880364261567593, 0.011824417859315872, 0.01710132323205471, -0.0005003822734579444, -0.018890544772148132, -0.002192768268287182, -0.0018264965619891882, 0.011033530347049236, -0.009095207788050175, -0.022689398378133774, -0.004281813744455576, 0.007092057727277279, -0.015247276052832603, 0.024115590378642082, 0.002996621420606971, -0.02834230102598667, 0.030546413734555244, 0.02350621670484543, -0.020511215552687645, 0.010190781205892563, -0.016582708805799484, 0.028238577768206596, -0.011967036873102188, 0.011623455211520195, -0.02797926962375641, 0.0026254875119775534, 0.018307102844119072, 0.0038701631128787994, -0.03850715234875679, 0.006246067117899656, -0.0006312514888122678, 0.010352848097682, -0.02358401007950306, -0.026708664372563362, -0.002863726345822215, 0.035862214863300323, 0.009860164485871792, -0.01726987399160862, 0.004275330808013678, -0.02663087099790573, 0.009140586480498314, -0.013872946612536907, 0.019136887043714523, -0.020835351198911667, -0.0250879917293787, 0.03044269047677517, 0.026280807331204414, -0.013406192883849144, 0.006683648563921452, -0.01216800045222044, 0.007824601605534554, 0.031505849212408066, 0.023726629093289375, 0.0294832531362772, -0.013678465969860554, 0.033891480416059494, 0.009211895987391472, 0.017088359221816063, -0.02183368429541588, 0.01847565360367298, 0.004644844215363264, -0.009834233671426773, -0.011344699189066887, -0.0006725785788148642, 0.00012691882147919387, 0.015338033437728882, 0.025736261159181595, -0.003967403434216976, -0.007312469184398651, -0.01312743779271841, 0.02350621670484543, -0.0006843284936621785, -0.011785522103309631, 0.006570201832801104, -0.004187814891338348, -0.0070013003423810005, 0.0165178831666708, -0.004537879955023527, 0.022715330123901367, -0.0025120405480265617, 0.025580676272511482, 0.005053253378719091, -0.0020063910633325577, -0.039285074919462204, -0.001816772622987628, 0.0007224142318591475, 0.0161029901355505, 0.04086684808135033, 0.03536953032016754, 0.009626788087189198, -0.023571044206619263, -0.009607339277863503, 0.011085391975939274, 0.020835351198911667, -0.0009027139167301357, -0.007584741804748774, 0.016958704218268394, 0.011130770668387413, -0.016829051077365875, -0.6712950468063354, -0.006511857267469168, -0.024854615330696106, -0.02663087099790573, -0.00008933950448408723, 0.0061779990792274475, 0.004605947993695736, 0.013231161050498486, -0.020187081769108772, 0.00798666849732399, -0.001847565290518105, 0.04086684808135033, 0.007519915234297514, 0.0040808506309986115, -0.034021131694316864, -0.01997963711619377, -0.004972219467163086, -0.023220978677272797, 0.012129104696214199, 0.0018329792656004429, -0.011649386025965214, 0.028446022421121597, -0.0010356089333072305, -0.006223377771675587, 0.021211346611380577, 0.004006299655884504, 0.021937407553195953, -0.02927580662071705, -0.01129283756017685, -0.009296170435845852, -0.01864420250058174, 0.02717541716992855, -0.0003555347793735564, 0.0021700789220631123, 0.048360832035541534, -0.002277043182402849, -0.009049829095602036, 0.033969271928071976, 0.004557327833026648, 0.018916476517915726, -0.000779542897362262, -0.00638544512912631, 0.022183749824762344, -0.012757924385368824, -0.027149485424160957, -0.012278205715119839, 0.0238303504884243, -0.02963883802294731, 0.005218561738729477, -0.004434156697243452, 0.013665501028299332, -0.0024520757142454386, 0.002124700229614973, -0.007273572962731123, -0.0035654769744724035, -0.0028621056117117405, 0.020640870556235313, 0.01091684214770794, -0.0006867594784125686, -0.011694764718413353, 0.011215046048164368, 0.016504917293787003, 0.00827838946133852, -0.0044471221044659615, 0.010676982812583447, 0.027771824970841408, -0.0133802630007267, 0.029820352792739868, 0.008349698968231678, -0.014573076739907265, -0.009017415344715118, 0.011655868031084538, -0.0061066895723342896, -0.013082059100270271, 0.004353123251348734, 0.00672254478558898, 0.01773662678897381, 0.012433790601789951, 0.023843316361308098, 0.015221345238387585, -0.0046221548691391945, -0.00026214358513243496, -0.016582708805799484, 0.016504917293787003, 0.028005201369524002, 0.005516765173524618, -0.04309689253568649, 0.013743292540311813, -0.0064308238215744495, -0.007176332641392946, 0.01911095716059208, 0.00446332897990942, -0.012971853837370872, -0.016919808462262154, 0.010048162192106247, 0.0032769974786788225, -0.021548446267843246, 0.001816772622987628, 0.01856641098856926, -0.04804966226220131, 0.007286538369953632, -0.007299503777176142, -0.014080392196774483, 0.008952588774263859, 0.023908143863081932, 0.012932957150042057, -0.008433973416686058, 0.012783855199813843, 0.0430709607899189, -0.01015836838632822, 0.03534360229969025, -0.007584741804748774, -0.016453055664896965, -0.005720969755202532, -0.014871280640363693, -0.026540113613009453, 0.005228285677731037, 0.0004019264888484031, 0.005931657273322344, -0.02533433400094509, -0.018825719133019447, 0.0023353875149041414, 0.0014059323584660888, -0.02020004764199257, 0.022481953725218773, 0.034980569034814835, -0.02709762565791607, -0.022974636405706406, -0.025023166090250015, 0.00641785841435194, -0.00019822835747618228, -0.004845807328820229, 0.0003723492263816297, -0.010132437571883202, 0.01498796883970499, 0.001948046963661909, -0.0020161152351647615, -0.008842382580041885, 0.0223652645945549, -0.013574742712080479, -0.002369421534240246, 0.003275376744568348, 0.005879795644432306, 0.005789037793874741, 0.006359514314681292, -0.03549918532371521, 0.003118171589449048, -0.026993902400135994, -0.01614188589155674, 0.011578075587749481, 0.0008524731383658946, -0.013367297127842903, 0.004194297362118959, 0.019331367686390877, 0.006152068264782429, -0.015208380296826363, -0.0018005658639594913, -0.015714028850197792, -0.01681608520448208, -0.028990568593144417, 0.010676982812583447, 0.024595309048891068, -0.045560311526060104, -0.0009262136882171035, 0.014845349825918674, -0.020887212827801704, 0.015739960595965385, 0.011727177537977695, 0.0012560202740132809, -0.023052429780364037, 0.0014245701022446156, -0.013062611222267151, -0.011299320496618748, 0.022274507209658623, 0.011338216252624989, -0.007908876053988934, 0.010339883156120777, -0.006132620386779308, 0.01247916929423809, -0.007947771809995174, -0.0025347298942506313, -0.011416008695960045, 0.011027047410607338, 0.004521673079580069, 0.04880165681242943, 0.0012543996563181281, 0.02115948498249054, 0.0165178831666708, -0.025373229756951332, 0.026125222444534302, -0.0031262750271707773, 0.007669016718864441, 0.003821542952209711, -0.021561412140727043, 0.008187631145119667, 0.02358401007950306, 0.02249491773545742, 0.015247276052832603, -0.004560569301247597, 0.030753860250115395, 0.031090958043932915, -0.021457688882946968, 0.027694031596183777, -0.004823117982596159, 0.0049171168357133865, -0.018346000462770462, -0.0030355174094438553, -0.011176149360835552, 0.024102624505758286, 0.006923507899045944, 0.010009266436100006, -0.00510187353938818, 0.0007916979375295341, -0.004722636193037033, 0.019914809614419937, 0.026190048083662987, -0.013289504684507847, 0.006346548907458782, -0.015415825881063938, -0.026734594255685806, 0.003623821074143052, 0.005325525999069214, -0.003922024741768837, -0.00640813447535038, -0.014624938368797302, -0.0065021333284676075, 0.007435640320181847, -0.002808623481541872, 0.010138919577002525, -0.033813685178756714, -0.0032008260022848845, 0.01614188589155674, -0.018994268029928207, 0.008135770447552204, -0.008596041239798069, -0.015662167221307755, 0.004310985561460257, -0.014663834124803543, 0.014962038025259972, -0.03479905426502228, 0.013114472851157188, 0.01341915875673294, 0.05092797800898552, -0.011908693239092827, 0.005332008935511112, -0.013367297127842903, 0.02501020021736622, -0.00029678543796762824, -0.02454344742000103, 0.003152205841615796, -0.015454721637070179, 0.010028714314103127, -0.02102983184158802, -0.0032624113373458385, 0.03583628311753273, -0.015026864595711231, 0.00672254478558898, 0.000010907877367571928, 0.019875913858413696, 0.020161151885986328, 0.014054462313652039, -0.005675591062754393, -0.009224860928952694, 0.014793488197028637, 0.03687351569533348, -0.005442214198410511, 0.005633453372865915, -0.0030436208471655846, -0.012615305371582508, -0.009075759910047054, 0.017192082479596138, -0.002220319816842675, 0.005798762198537588, -0.0007568534929305315, 0.010378778912127018, 0.005908967927098274, -0.0158825796097517, 0.0088812792673707, 0.007766257040202618, -0.0030209312681108713, -0.013561777770519257, -0.035395462065935135, 0.022391194477677345, -0.0027049004565924406, 0.004748567007482052, -0.020433424040675163, -0.00028706141165457666, -0.005092149134725332, -0.018371930345892906, 0.006009449250996113, -0.00645027169957757, 0.015286171808838844, -0.012343033216893673, -0.008628454059362411, -0.010605673305690289, 0.009192448109388351, 0.007500466890633106, -0.013535846956074238, 0.003831267124041915, -0.02956104464828968, 0.0009724028059281409, 0.0034585127141326666, -0.00004074468961334787, -0.025139853358268738, 0.012278205715119839, 0.023519182577729225, -0.012913509272038937, -0.006301170215010643, 0.0037178201600909233, 0.004716153722256422, -0.017905177548527718, 0.009769407100975513, -0.019746258854866028, -0.011675315909087658, 0.007409709505736828, -0.022676432505249977, -0.013406192883849144, 0.003922024741768837, 0.03925914317369461, -0.011325251311063766, -0.014611972495913506, -0.022404160350561142, -0.03311355784535408, 0.0024634203873574734, 0.1057974249124527, 0.014145219698548317, 0.025956671684980392, 0.006878129206597805, -0.019914809614419937, -0.019162818789482117, -0.009231343865394592, -0.04423784464597702, 0.012018898501992226, -0.00921837892383337, 0.02408965863287449, -0.026501217857003212, 0.020225977525115013, 0.005014357157051563, 0.02053714729845524, 0.014521215111017227, -0.002670866437256336, -0.020433424040675163, -0.0015372068155556917, -0.031168751418590546, 0.0051213214173913, 0.006865163799375296, 0.010048162192106247, 0.003795612370595336, -0.009749959222972393, -0.024063728749752045, 0.026449356228113174, 0.00967864878475666, -0.009049829095602036, -0.012284688651561737, -0.02475089207291603, 0.0034844432957470417, -0.00928320549428463, 0.011772556230425835, -0.01811262220144272, -0.01918874867260456, 0.009043346159160137, 0.023843316361308098, 0.02580108679831028, 0.005980277433991432, 0.029327668249607086, -0.008103356696665287, 0.008083908818662167, -0.005490834359079599, 0.021146519109606743, -0.0023499734234064817, -0.03298390284180641, 0.005283388774842024, -0.00043352958164177835, -0.024271173402667046, 0.03181701898574829, -0.000028944177756784484, -0.004479535389691591, -0.002066355897113681, 0.017995934933423996, -0.012783855199813843, 0.013859981670975685, -0.006615580525249243, -0.0008403180981986225, 0.025489918887615204, -0.01789221167564392, -0.03189481049776077, 0.00028949242550879717, -0.03251715004444122, 0.03588814660906792, -0.03500650078058243, -0.007869980297982693, -0.024361930787563324, 0.00451519014313817, -0.018177449703216553, 0.020627904683351517, 0.003249445930123329, 0.010962220840156078, -0.005299595184624195, 0.048023734241724014, -0.0033094107639044523, 0.012971853837370872, -0.02290981076657772, 0.017918141558766365, -0.016245609149336815, -0.013179299421608448, -0.020589008927345276, 0.0037469922099262476, -0.029327668249607086, -0.007383778691291809, 0.013017232529819012, 0.006327101029455662, -0.02689017914235592, -0.004385536536574364, 0.005789037793874741, -0.005597798619419336, -0.004152160137891769, 0.012719028629362583, -0.008220044896006584, -0.01702353172004223, -0.011506766080856323, 0.0042980206198990345, 0.0018702547531574965, -0.0032964455895125866, 0.007267090491950512, -0.009581409394741058, -0.0058182100765407085, -0.005429248791188002, -0.008829417638480663, -0.0030403793789446354, -0.01194110605865717, -0.002591453492641449, 0.005756624508649111, -0.01618078351020813, -0.009821268729865551, -0.00021210535487625748, -0.01768476516008377, -0.0005562954465858638, -0.017451388761401176, -0.015545479021966457, 0.02332470193505287, 0.015960371121764183, 0.02208002656698227, 0.01369143184274435, -0.014495284296572208, -0.007701430004090071, -0.0005567006301134825, 0.027590308338403702, 0.05188741534948349, -0.023609939962625504, -0.017957039177417755, 0.015999266877770424, -0.020900176838040352, 0.003038758644834161, 0.021042795851826668, -0.009814785793423653, 0.0014083633432164788, 0.010897394269704819, -0.0167253278195858, -0.020135220140218735, -0.005273664370179176, -0.009788854978978634, -0.002986897248774767, -0.008764590136706829, -0.006729027256369591, -0.018449721857905388, -0.009166517294943333, -0.002651418326422572, 0.008245975710451603, 0.0034358231350779533, -0.028757192194461823, 0.01511762198060751, -0.008544179610908031, 0.005344973877072334, 0.013924808241426945, -0.003299686824902892, -0.04143732413649559, -0.0008403180981986225, 0.010949255898594856, -0.013600673526525497, -0.03448788449168205, -0.007863497361540794, -0.01809965819120407, -0.00444063963368535, 0.004920358303934336, 0.0330357663333416, -0.008816451765596867, 0.006683648563921452, 0.00823301076889038, -0.015947405248880386, 0.02608632668852806, 0.0037243026308715343, -0.007623638026416302, -0.028031131252646446, 0.027123555541038513, 0.01843675784766674, 0.016712361946702003, 0.040374163538217545, -0.0021538722794502974, 0.01885164901614189, -0.011740143410861492, 0.017490284517407417, -0.0004517621418926865, -0.00034439266892150044, -0.026190048083662987, -0.021729961037635803, 0.0020209772046655416, -0.014521215111017227, -0.01467679999768734, 0.002505557844415307, -0.01061863824725151, 0.015623271465301514, -0.010087057948112488, -0.0031748951878398657, 0.01631043665111065, 0.016375262290239334, -0.013257091864943504, 0.010741809383034706, -0.012932957150042057, -0.002484489232301712, 0.0027324517723172903, 0.00897203665226698, -0.004793945699930191, 0.0043466403149068356, -0.0020047705620527267, 0.0021538722794502974, 0.021263208240270615, -0.0269679706543684, -0.024115590378642082, -0.0025833500549197197, 0.030598275363445282, 0.002772968728095293, 0.01584368385374546, 0.006981851998716593, -0.0037113374564796686, -0.01273199450224638, -0.026280807331204414, -0.02182071842253208, -0.049527715891599655, 0.02195037342607975, -0.008628454059362411, -0.004353123251348734, 0.01064456906169653, -0.009698097594082355, -0.04094463959336281, 0.0238303504884243, 0.0034649954177439213, 0.032802388072013855, 0.0002048123424174264, 0.022507883608341217, 0.03770329803228378, -0.010346366092562675, 0.0028588641434907913, 0.026410460472106934, 0.019085025414824486, 0.008848865516483784, 0.015830717980861664, -0.004469811450690031, 0.013808120042085648, -0.012031864374876022, -0.02099093608558178, -0.006054827943444252, -0.045638103038072586, -0.024050762876868248, 0.014417491853237152, 0.01218744833022356, 0.0032413427252322435, -0.013302470557391644, -0.0003156257444061339, 0.006942956242710352, 0.00542600778862834, -0.0034358231350779533, 0.022067060694098473, -0.013847015798091888, -0.026942040771245956, -0.0334506556391716, -0.01835896447300911, -0.0021036313846707344, -0.001962633104994893, 0.012615305371582508, -0.0186053067445755, 0.01572699472308159, -0.02542509138584137, 0.019422125071287155, -0.013950739055871964, -0.002110114088281989, 0.02052418142557144, -0.0014197081327438354, 0.0010485743405297399, -0.004372571129351854, 0.0069299908354878426, -0.005105114541947842, -0.003756716148927808, -0.015960371121764183, 0.025554746389389038, 0.003516856813803315, 0.005951105151325464, 0.009736993350088596, 0.043459922075271606, -0.008952588774263859, 0.021315069869160652, -0.011318768374621868, -0.016375262290239334, -0.004560569301247597, -0.026656802743673325, 0.004842565860599279, 0.0004894427256658673, -0.023635871708393097, 0.007448605261743069, -0.008965553715825081, 0.0026092808693647385, -0.01999260112643242, -0.007811635732650757, 0.012142069637775421, -0.01375625841319561, -0.02102983184158802, -0.006806819699704647, 0.015869613736867905, -0.0074032265692949295, -0.001892944099381566, -0.0037016132846474648, -0.005322284530848265, 0.03293204307556152, -0.014430457726120949, 0.0418262854218483, -0.012641236186027527, 0.018216345459222794, -0.028290439397096634, 0.02576219104230404, 0.008433973416686058, 0.013963703997433186, 0.030598275363445282, -0.01225227490067482, 0.012051312252879143, 0.0014553628861904144, -0.008822934702038765, 0.01100111659616232, 0.009860164485871792, -0.004388778004795313, -0.01685498282313347, 0.01091035921126604, -0.00033223762875422835, -0.007850532419979572, -0.0006320617976598442, 0.002114976057782769, -0.007532880175858736, 0.01710132323205471, 0.015610306523740292, -0.009036863222718239, 0.008200597018003464, 0.012174483388662338, 0.00447305291891098, 0.0186053067445755, -0.019253576174378395, 0.010638087056577206, -0.02086128108203411, 0.022404160350561142, 0.010437123477458954, 0.0006920266896486282, -0.02128913812339306, -0.009296170435845852, -0.004106780979782343, 0.044808320701122284, -0.013782189227640629, -0.003750233445316553, -0.01181145291775465, 0.02764216996729374, 0.011960554867982864, -0.005043528974056244, 0.006155309733003378, -0.015584375709295273, 0.012433790601789951, -0.021600307896733284, -0.04314875230193138, -0.01214855257421732, -0.024776823818683624, 0.039077628403902054, 0.016271540895104408, 0.000348039175150916, -0.01511762198060751, 0.0014926382573321462, -0.04068533331155777, -0.0020290804095566273, -0.006904060021042824, 0.02099093608558178, 0.017049461603164673, -0.006981851998716593, 0.007364330347627401, 0.007416191976517439, 0.00766253424808383, 0.02153548039495945, -0.002995000686496496, 0.02157437615096569, -0.011312286369502544, -0.009685131721198559, 0.00414891866967082, -0.009672166779637337, -0.01308854203671217, -0.003380720503628254, -0.003168412484228611, 0.013769223354756832, -0.012615305371582508, 0.007973702624440193, 0.001315985107794404, -0.006139102857559919, -0.028212646022439003, 0.0004906582762487233, 0.0006340876570902765, 0.013289504684507847, -0.010359331034123898, -0.02956104464828968, 0.0263456329703331, 0.02621597982943058, 0.005357939284294844, -0.022754225879907608, -0.009393410757184029, 0.007053161505609751, -0.018086692318320274, -0.0012552099069580436, 0.003977127373218536, -0.010839049704372883, -0.01584368385374546, 0.007753291632980108, 0.005951105151325464, 0.02478978969156742, -0.00858955830335617, 0.007280055433511734, 0.013257091864943504, -0.0000065713156800484285, 0.007234676741063595, -0.00413919473066926, -0.01467679999768734, -0.018333034589886665, -0.017658835276961327, -0.01681608520448208, 0.005108356010168791, -0.007630120497196913, 0.008479352109134197, -0.02771996334195137, 0.004567051772028208, -0.018579376861453056, -0.003983610309660435, -0.0023110774345695972, 0.023065393790602684, 0.04281165450811386, -0.015273206867277622, -0.006696613971143961, 0.002272181212902069, -0.008356180973351002, -0.014508250169456005, -0.0066090975888073444, 0.00827838946133852, -0.016906842589378357, 0.003750233445316553, -0.008524730801582336, -0.0022802846506237984, -0.005156976170837879, -0.009633270092308521, -0.035940006375312805, -0.004323950968682766, 0.027771824970841408, 0.19261354207992554, -0.014547145925462246, -0.006657717749476433, 0.013808120042085648, -0.021340999752283096, 0.011869796551764011, 0.024115590378642082, 0.014080392196774483, 0.0023856281768530607, 0.0005133476224727929, -0.016206713393330574, 0.01723097823560238, 0.008012599311769009, 0.0019723570439964533, 0.006560477428138256, -0.040996503084897995, -0.010657534934580326, 0.00037032339605502784, -0.027875546365976334, -0.011727177537977695, -0.00768198212608695, -0.007299503777176142, -0.011202080175280571, -0.01939619518816471, 0.039622172713279724, -0.011668833903968334, -0.015830717980861664, 0.016919808462262154, 0.03207632899284363, 0.015960371121764183, -0.01093629002571106, -0.016842016950249672, -0.008336733095347881, -0.013244125992059708, -0.011999450623989105, -0.020122256129980087, -0.007422674912959337, -0.02501020021736622, -0.008505282923579216, -0.005526489112526178, -0.0011830900330096483, 0.01773662678897381, 0.010709396563470364, -0.007267090491950512, 0.015999266877770424, 0.02604742906987667, -0.013315435498952866, 0.01621967926621437, -0.02082238532602787, -0.01689387857913971, -0.0439007468521595, -0.03358031064271927, 0.000994281843304634, 0.03726247698068619, -0.02208002656698227, 0.000011990435268671717, 0.006949438713490963, 0.020433424040675163, 0.00515373470261693, -0.031298406422138214, 0.0031116888858377934, 0.015701064839959145, -0.02813485451042652, -0.007377295754849911, 0.007461570668965578, 0.03985555097460747, -0.010975186713039875, -0.025697365403175354, 0.0397258959710598, -0.026319703087210655, -0.0030403793789446354, -0.010067610070109367, -0.002486109733581543, -0.0088812792673707, 0.0017438423819839954, -0.001923736883327365, 0.017827384173870087, 0.006220136769115925, 0.010255607776343822, 0.001199296792037785, -0.01772366091609001, 0.035136155784130096, -0.0061066895723342896, -0.010735327377915382, -0.010651051998138428, -0.026151152327656746, 0.006981851998716593, 0.006622062996029854, -0.010048162192106247, -0.0009124379721470177, -0.00419105589389801, -0.019668467342853546, 0.00012296844215597957, 0.004894427489489317, 0.006852198392152786, 0.010437123477458954, 0.005908967927098274, 0.0038247844204306602, -0.008103356696665287, -0.006456754636019468, -0.028653468936681747, 0.018216345459222794, 0.032205980271101, 0.00022101905778981745, -0.029664767906069756, -0.008155218325555325, 0.03871459513902664, 0.03394334018230438, 0.005860347766429186, -0.013600673526525497, -0.016958704218268394, 0.006372479721903801, 0.0012543996563181281, -0.01911095716059208, -0.010437123477458954, 0.008356180973351002, -0.012855164706707, -0.008472870104014874, 0.019370263442397118, -0.029457321390509605, 0.0034487885423004627, -0.015415825881063938, -0.00047364120837301016, 0.008887761272490025, -0.0020015290938317776, 0.010501950047910213, -0.007500466890633106, -0.0017470837337896228, 0.01717911660671234, -0.024063728749752045, 0.026734594255685806, -0.024556411430239677, 0.0013573121977970004, -0.00010007645323639736, -0.00450546620413661, 0.007513432297855616, 0.027201347053050995, 0.003426099196076393, -0.022183749824762344, 0.002813485451042652, 0.008064460940659046, 0.002243009163066745, 0.009899060241878033, 0.010988151654601097, -0.004790704697370529, -0.004638361278921366, 0.006025656126439571, -0.010605673305690289, -0.01625857502222061, -0.020342666655778885, -0.016090024262666702, -0.026410460472106934, 0.0121226217597723, -0.009406376630067825, 0.0023759042378515005, -0.0273828636854887, -0.015260240994393826, -0.004832841921597719, -0.0007702240254729986, 0.01856641098856926, -0.031039098277688026, 0.0073967440985143185, 0.018721995875239372, -0.023026498034596443, -0.008200597018003464, -0.023480286821722984, -0.16450461745262146, 0.025710329413414, 0.01681608520448208, -0.009023898281157017, 0.023428425192832947, -0.022754225879907608, 0.027616240084171295, 0.015234310179948807, -0.009224860928952694, 0.005166700109839439, 0.0008131718495860696, 0.0038507150020450354, -0.03153178095817566, -0.0026757284067571163, 0.003335341578349471, 0.00672254478558898, -0.030546413734555244, 0.036277107894420624, 0.017256908118724823, 0.0010526260593906045, 0.0053125605918467045, -0.02091314271092415, -0.0016555157490074635, -0.0012454859679564834, 0.023467320948839188, 0.009497134014964104, 0.0046351198107004166, 0.005380628630518913, -0.021691065281629562, -0.013062611222267151, -0.048023734241724014, -0.0008427490829490125, 0.017321735620498657, 0.021340999752283096, 0.011740143410861492, 0.012219862081110477, -0.012984818778932095, 0.007020748220384121, -0.015130587853491306, -0.016193747520446777, 0.0071439193561673164, 0.03236156702041626, 0.024997234344482422, 0.01185683161020279, 0.010735327377915382, 0.04636416584253311, 0.014599007554352283, -0.009004450403153896, 0.019383229315280914, -0.009607339277863503, -0.00414891866967082, -0.008336733095347881, -0.019888877868652344, -0.0005830365116707981, 0.02771996334195137, 0.005620488431304693, -0.00701426574960351, 0.013730327598750591, 0.014145219698548317, 0.011331734247505665, -0.021807754412293434, 0.022857949137687683, 0.01593444123864174, -0.0031343784648925066, 0.001282761339098215, -0.028627539053559303, 0.013354332186281681, 0.0034098925534635782, -0.014689764939248562, -0.004784221760928631, -0.015208380296826363, -0.00796722061932087, -0.008693280629813671, -0.02311725541949272, 0.011629937216639519, -0.012323584407567978, -0.03243935853242874, 0.007643085904419422, 0.00766253424808383, 0.0028702090494334698, -0.017412493005394936, 0.026267841458320618, 0.010884428396821022, -0.03448788449168205, 0.004327192436903715, 0.018838683143258095, -0.02228747308254242, -0.014702730812132359, -0.01020374707877636, -0.027694031596183777, 0.006122896447777748, -0.004252641461789608, -0.012686614878475666, -0.008829417638480663, 0.03319134935736656, 0.01789221167564392, 0.021250242367386818, -0.006683648563921452, 0.009412859566509724, -0.02294870652258396, 0.0009659201023168862, -0.008336733095347881, -0.019603639841079712, -0.012116138823330402, 0.009775889106094837, 0.03993334248661995, 0.009892578236758709, 0.017153184860944748, 0.015545479021966457, -0.01288109552115202, -0.020433424040675163, 0.013652535155415535, 0.022170783951878548, 0.024102624505758286, -0.003623821074143052, 0.03230970352888107, 0.01852751523256302, -0.03132433444261551, -0.017218012362718582, 0.011279872618615627, 0.052250444889068604, 0.005604281555861235, 0.010722361505031586, 0.006155309733003378, -0.016362298280000687, 0.0038020950742065907, -0.1179330125451088, 0.0006563718779943883, 0.006923507899045944, 0.010300987400114536, 0.010313952341675758, 0.016128921881318092, 0.010683465749025345, 0.032050397247076035, -0.0040808506309986115, 0.011318768374621868, -0.021016865968704224, -0.05787741392850876, -0.018786821514368057, -0.03155771270394325, 0.010994634591042995, -0.00672254478558898, 0.010605673305690289, -0.029042430222034454, -0.018294138833880424, 0.01147435326129198, -0.0367957204580307, 0.016906842589378357, 0.010385261848568916, -0.006301170215010643, -0.014547145925462246, -0.004356364719569683, -0.03181701898574829, -0.0031505851075053215, 0.004936564713716507, 0.012952405028045177, 0.010398227721452713, -0.018164483830332756, 0.01794407330453396, -0.020977970212697983, -0.0003221084189135581, 0.007617155089974403, 0.0036173383705317974, -0.01026209071278572, 0.037651438266038895, -0.015662167221307755, 0.011156701482832432, -0.014599007554352283, -0.00417160801589489, -0.03412485495209694, 0.010022231377661228, 0.004084091633558273, -0.005659384187310934, -0.0012973473640158772, 0.02266346849501133, -0.015195414423942566, -0.021211346611380577, -0.01056029461324215, -0.008284871466457844, -0.001761669758707285, 0.005711245816200972, 0.009205413050949574, 0.008997967466711998, -0.021470654755830765, -0.02379145473241806, 0.013872946612536907, -0.004845807328820229, -0.016193747520446777, -0.003912300802767277, 0.00304200011305511, -0.002687073079869151, -0.007617155089974403, 0.003983610309660435, -0.028575677424669266, 0.012939440086483955, -0.004434156697243452, -0.020381562411785126, 0.0030338966753333807, -0.022131888195872307, 0.0012187449028715491, -0.020251909270882607, 0.003640027716755867, -0.018449721857905388, 0.008557144552469254, 0.029042430222034454, -0.00807094294577837, -0.025502884760499, -0.025852948427200317, 0.03057234361767769, -0.032205980271101, 0.011779039166867733, 0.007481019012629986, -0.010112988762557507, 0.017114289104938507, 0.011623455211520195, -0.01751621626317501, -0.009341550059616566, -0.005238009616732597, -0.013561777770519257, -0.005001391749829054, -0.014702730812132359, 0.008609006181359291, -0.009568443521857262, 0.00857011042535305, 0.0027049004565924406, 0.009101689793169498, -0.018294138833880424, -0.0010202126577496529, -0.07286538183689117, 0.01214855257421732, -0.011403043754398823, 0.0032656528055667877, 0.0046221548691391945, -0.017568077892065048, 0.019136887043714523, -0.022546779364347458, -0.0037826469633728266, -0.004913875367492437, -0.01572699472308159, 0.034306369721889496, 0.013509916141629219, -0.014158184640109539, -0.011014082469046116, -0.010787188075482845, 0.005027322564274073, 0.002033942611888051, 0.017218012362718582, 0.02478978969156742, -0.010430640541017056, 0.0027437966782599688, 0.00802556425333023, -0.01406742725521326, 0.0038442325312644243, 0.0035038914065808058, -0.003345065750181675, 0.02386924810707569, -0.00384747376665473, -0.012550478801131248, 0.0008500420954078436, -0.012025381438434124, 0.015662167221307755, 0.019914809614419937, 0.029846282675862312, -0.026656802743673325, -0.006203929893672466, -0.011033530347049236, 0.04947585612535477, 0.03575849160552025, -0.007960737682878971, -0.024984268471598625, 0.013548812828958035, -0.02484164945781231, -0.01406742725521326, 0.011681798845529556, -0.022806087508797646, 0.0018378413515165448, 0.030961304903030396, 0.007928323931992054, 0.03251715004444122, 0.010884428396821022, 0.002808623481541872, -0.008466387167572975, 0.02379145473241806, -0.019162818789482117, 0.05357291176915169, -0.0044049848802387714, -0.0040581608191132545, -0.013471020385622978, 0.020718662068247795, 0.00829783733934164, -0.01685498282313347, -0.004100298509001732, -0.000024132808903232217, -0.014482319355010986, -0.03404706344008446, 0.007876462303102016, 0.0011855211341753602, -0.0405556783080101, -0.01225227490067482, -0.006268756929785013, 0.015312102623283863, 0.015299137681722641, 0.013548812828958035, 0.014560110867023468, 0.01471569575369358, -0.002121458761394024, -0.01100111659616232, 0.00015933225222397596, 0.01965550146996975, -0.003769681556150317, -0.02826450765132904, 0.01413225382566452, 0.029198015108704567, 0.048568278551101685, -0.005461662542074919, 0.014274872839450836, 0.0036529931239783764, 0.005160217639058828, 0.0010145402047783136, 0.017243942245841026, -0.006793854292482138, 0.0005344163510017097, 0.01341915875673294, 0.019538814201951027, -0.003721061395481229, -0.01056029461324215, 0.005033805035054684, 0.03562884032726288, -0.004832841921597719, 0.012997783720493317, -0.006443789228796959, -0.015817752107977867, -0.015947405248880386, 0.023208012804389, -0.019590675830841064, -0.0267605260014534, -0.008045012131333351, 0.0018005658639594913, 0.022935740649700165, -0.006323859561234713, -0.0033677550964057446, 0.02027783915400505, -0.020433424040675163, 0.01689387857913971, -0.027019832283258438, -0.040166717022657394, -0.0001858707400970161, 0.009393410757184029, 0.0010169713059440255, 0.00733839999884367, 0.00923782680183649, -0.011007599532604218, 0.022339332848787308, 0.01406742725521326, 0.01659567467868328, -0.021794788539409637, -0.019085025414824486, -0.008245975710451603, 0.016323402523994446, -0.0023759042378515005, -0.0077208783477544785, -0.001962633104994893, 0.0036108556669205427, -0.0008832658641040325, -0.0267605260014534, 0.02873126231133938, -0.022935740649700165, 0.02412855438888073, -0.005513523705303669, 0.00507918419316411, 0.005951105151325464, 0.005173183046281338, 0.005001391749829054, -0.0177625585347414, 0.015130587853491306, -0.01999260112643242, -0.0192406103014946, 0.02140582725405693, -0.007377295754849911, 0.02927580662071705, -0.015104657039046288, -0.01216800045222044, 0.0034552712459117174, -0.003481202060356736, 0.013561777770519257, 0.0022592158056795597, -0.01183090079575777, 0.013665501028299332, 0.017075393348932266, 0.008511765860021114, -0.007409709505736828, -0.0014261907199397683, -0.003058206755667925, 0.0031424816697835922, 0.0021846650633960962, -0.000989419873803854, -0.022144854068756104, 0.0036270625423640013, -0.006233102176338434, -0.016504917293787003, 0.003999816719442606, 0.017931107431650162, -0.025956671684980392, 0.021626237779855728, 0.002192768268287182, -0.001260882243514061, 0.018721995875239372, -0.023493250831961632, 0.030598275363445282, -0.011616972275078297, -0.019331367686390877, 0.01505279541015625, 0.01505279541015625, 0.004524914547801018, 0.0019042887724936008, -0.014962038025259972] ---- @@ -124,7 +125,7 @@ For more information about the values accepted by different index providers, see ==== `vector.dimensions` The dimensions of the vectors to be indexed. For more information, see xref:indexes/semantic-indexes/vector-indexes.adoc#embeddings[]. -This setting can be omitted, and any `LIST` can be indexed and queried, separated by their dimensions, _though only vectors of the same dimension can be compared._ +This setting can be omitted, and any `LIST` or, as of Neo4j 2025.xx, `VECTOR` value can be indexed and queried, separated by their dimensions, _though only vectors of the same dimension can be compared._ Setting this value adds additional checks that ensure only vectors with the configured dimensions are indexed, and querying the index with a vector of a different dimensions returns an error. [NOTE] diff --git a/modules/ROOT/pages/introduction/cypher-neo4j.adoc b/modules/ROOT/pages/introduction/cypher-neo4j.adoc index cc87055ee..334c73780 100644 --- a/modules/ROOT/pages/introduction/cypher-neo4j.adoc +++ b/modules/ROOT/pages/introduction/cypher-neo4j.adoc @@ -39,6 +39,10 @@ xref::constraints/managing-constraints.adoc#create-key-constraints[node and rela a| Only xref::constraints/managing-constraints.adoc#create-property-uniqueness-constraints[node and relationship property uniqueness constraints]. +| Store xref:values-and-types/vector.adoc[`VECTOR`] values as properties. +| `VECTOR` values can be stored as properties if the instance uses Neo4j's link:{neo4j-docs-base-uri}/operations-manual/current/database-internals/store-formats/#store-format-overview[block format]. +| `VECTOR` values cannot be stored as properties using Community Edition. + |=== [[neo4j-terminology]] diff --git a/modules/ROOT/pages/values-and-types/casting-data.adoc b/modules/ROOT/pages/values-and-types/casting-data.adoc index 818b8c917..1b188acd4 100644 --- a/modules/ROOT/pages/values-and-types/casting-data.adoc +++ b/modules/ROOT/pages/values-and-types/casting-data.adoc @@ -13,7 +13,7 @@ The following functions are available for casting data values: |=== | Function | Description -| toBoolean() | Converts a `STRING`, `INTEGER`, or `BOOLEAN` value to a `BOOLEAN` value. +| xref:functions/list.adoc#functions-toboolean[`toBoolean()`] | Converts a `STRING`, `INTEGER`, or `BOOLEAN` value to a `BOOLEAN` value. | toBooleanList() | Converts a `LIST` and returns a `LIST` values. If any values are not convertible to `BOOLEAN` they will be `null` in the `LIST` returned. @@ -24,7 +24,7 @@ For any other input value, `null` will be returned. | toFloat() | Converts an `INTEGER`, `FLOAT`, or a `STRING` value to a `FLOAT` value. Otherwise `null` is returned. -| toFloatList() | Converts a `LIST` and returns a `LIST` values. +| toFloatList() | Converts a `LIST` or, as of Neo4j 2025.xx, a `VECTOR` and returns a `LIST` values. If any values are not convertible to `FLOAT` they will be `null` in the `LIST` returned. | toFloatOrNull() | Converts an `INTEGER`, `FLOAT`, or a `STRING` value to a `FLOAT`. @@ -32,7 +32,7 @@ For any other input value, `null` will be returned. | toInteger() | Converts a `BOOLEAN`, `INTEGER`, `FLOAT` or a `STRING` value to an `INTEGER` value. -| toIntegerList() | Converts a `LIST` to a `LIST` values. If any values are not convertible to `INTEGER` they will be null in the `LIST` returned. +| toIntegerList() | Converts a `LIST` or, as of Neo4j 2025.xx, a `VECTOR` to a `LIST` values. If any values are not convertible to `INTEGER` they will be null in the `LIST` returned. | toIntegerOrNull() | Converts a `BOOLEAN`, `INTEGER`, `FLOAT` or a `STRING` value to an `INTEGER` value. For any other input value, `null` will be returned. diff --git a/modules/ROOT/pages/values-and-types/index.adoc b/modules/ROOT/pages/values-and-types/index.adoc index 61222e496..c5c25c6b2 100644 --- a/modules/ROOT/pages/values-and-types/index.adoc +++ b/modules/ROOT/pages/values-and-types/index.adoc @@ -7,12 +7,13 @@ Rather, Cypher will automatically infer the data type of a given value. More information about the data values and types supported by Cypher can be found in the following sections: -* xref::values-and-types/property-structural-constructed.adoc[] +* xref:values-and-types/property-structural-constructed.adoc[] * xref:values-and-types/boolean-numeric-string.adoc[] * xref::values-and-types/temporal.adoc[] -* xref::values-and-types/spatial.adoc[] -* xref::values-and-types/lists.adoc[] -* xref::values-and-types/maps.adoc[] +* xref:values-and-types/spatial.adoc[] +* xref:values-and-types/lists.adoc[] +* xref:values-and-types/maps.adoc[] +* xref:values-and-types/vector.adoc[] label:new[Introduced in Neo4j 2025.xx] * xref:values-and-types/graph-references.adoc[] * xref::values-and-types/working-with-null.adoc[] * xref::values-and-types/casting-data.adoc[] diff --git a/modules/ROOT/pages/values-and-types/ordering-equality-comparison.adoc b/modules/ROOT/pages/values-and-types/ordering-equality-comparison.adoc index e17d62dc1..28c45b403 100644 --- a/modules/ROOT/pages/values-and-types/ordering-equality-comparison.adoc +++ b/modules/ROOT/pages/values-and-types/ordering-equality-comparison.adoc @@ -35,9 +35,12 @@ For example, `1 > b` and `1 < b` are both `false` when `b` is NaN. * String values are compared for ordering using lexicographic order (e.g. `"x" < "xy"`). * Boolean values are compared for ordering such that `false < true`. * When comparing values for ordering, if one of the arguments is `null`, the result is always `null`. -* xref:values-and-types/spatial.adoc[Spatial values] cannot be compared using the operators `\<=`, `<`,`>=`, `>`. -To compare spatial values within a specific range, use either the xref:functions/spatial.adoc#functions-withinBBox[`point.withinBBox()`] or the xref:functions/spatial.adoc#functions-point[`point()`] function. +* xref:values-and-types/spatial.adoc[Spatial values] and xref:values-and-types/vector.adoc[`VECTOR`] values cannot be compared using the operators `\<=`, `<`,`>=`, `>`. +To compare spatial values within a specific range, use either the xref:functions/spatial.adoc#functions-withinBBox[`point.withinBBox()`] or the xref:functions/spatial.adoc#functions-point-wgs84-2d[`point()`] function. + +For the ordering of `VECTOR` types, see xref:values-and-types/vector.adoc#ordering-vector[`VECTOR` values -> Ordering `VECTOR` types]. + [[value-hierarchy]] === Hierarchy of values @@ -48,13 +51,14 @@ Values of different types are ordered based on a predefined hierarchy, from leas * xref::values-and-types/property-structural-constructed.adoc#structural-types[`RELATIONSHIP`] * xref::values-and-types/lists.adoc[`LIST`] * xref::patterns/fixed-length-patterns.adoc#path-patterns[`PATH`] +* xref::values-and-types/vector.adoc[`VECTOR`] label:new[Introduced in Neo4j 2025.xx] +* xref::values-and-types/spatial.adoc[`POINT`] * xref::values-and-types/temporal.adoc[`ZONED DATETIME`] * xref::values-and-types/temporal.adoc[`LOCAL DATETIME`] * xref::values-and-types/temporal.adoc[`DATE`] * xref::values-and-types/temporal.adoc[`ZONED TIME`] * xref::values-and-types/temporal.adoc[`LOCAL TIME`] * xref::values-and-types/temporal.adoc[`DURATION`] -* xref::values-and-types/spatial.adoc[`POINT`] * xref::values-and-types/property-structural-constructed.adoc[`STRING`] * xref::values-and-types/property-structural-constructed.adoc[`BOOLEAN`] * Numbers: xref:values-and-types/property-structural-constructed.adoc[`INTEGER`, `FLOAT`] @@ -144,3 +148,67 @@ If they have the same time and offset but different named time zones, they are s * Duration values cannot be directly compared. Since the length of a day, month, or year varies, Cypher does not define a strict ordering for durations. As a result, comparing two durations `(e.g, duration1 < duration2)` will always return `null`. + +[[ordering-vector-types]] +=== Ordering vector types + +The xref:values-and-types/vector.adoc[`VECTOR`] supertypes are ordered in the following ascending order. + +* `VECTOR` +* `VECTOR` +* `VECTOR(DIMENSION)` + +`VECTOR` types with both a defined coordinate type and dimension are ordered according to the ordering of the vector coordinate types, listed in ascending order below: + +* `INTEGER8` +* `INTEGER16` +* `INTEGER32` +* `INTEGER64` +* `FLOAT32` +* `FLOAT64` + +Within the same coordinate type, `VECTOR` types are ordered by their dimension, with smaller values first. +`VECTOR` types of the same coordinate type and dimension are then ordered pairwise. + +.Ordering rules for `VECTOR` values +[cols="3,3,2,6", options="header"] +|=== +| A | B | Ordered As | Reason + +| `VECTOR(12345)` +| `VECTOR(123456)` +| A < B +| Same coordinate type, compare by dimension ascending. + +| `VECTOR(1234)` +| `VECTOR(1234)` +| A < B +| Coordinate type order: `INTEGER32` < `FLOAT32` + +| `VECTOR` +| `VECTOR(3)` +| A < B +| Coordinate type defined and no dimension < dimension defined and no coordinate type + +| `VECTOR(123456)` +| `VECTOR(3)` +| A < B +| Coordinate type order: `INTEGER64` < `FLOAT32`, compare coordinate type first. + +| `VECTOR(1234)` +| `VECTOR(1234)` +| B < A +| Coordinate type order: `FLOAT32` < `FLOAT64` + +| `VECTOR([1, 2])` +| `VECTOR([2, 1])` +| A < B +| Same coordinate type and dimension, pairwise value comparison. + +| `VECTOR(1234)` +| `LIST` +| A < B +| `VECTOR` values are ordered before `LIST` values. + +|=== + diff --git a/modules/ROOT/pages/values-and-types/property-structural-constructed.adoc b/modules/ROOT/pages/values-and-types/property-structural-constructed.adoc index bc8007f66..c44c80ccf 100644 --- a/modules/ROOT/pages/values-and-types/property-structural-constructed.adoc +++ b/modules/ROOT/pages/values-and-types/property-structural-constructed.adoc @@ -3,7 +3,6 @@ :description: This section provides an overview of the property, structural, and constructed data types supported by Cypher. :page-aliases: values-and-types/property-structural-composite.adoc - Cypher provides first class support for a number of data value types. These fall into the following three categories: *property*, *structural*, and *constructed*. This section will first provide a brief overview of each type, and then go into more detail about the property data type. @@ -13,21 +12,22 @@ This section will first provide a brief overview of each type, and then go into A property type value is one that can be stored as a node or relationship property. -Property types are the most primitive types in Cypher and include the following: `BOOLEAN`, `DATE`, `DURATION`, `FLOAT`, `INTEGER`, `LIST`, `LOCAL DATETIME`, `LOCAL TIME`, `POINT`, `STRING`, `ZONED DATETIME`, and `ZONED TIME`. +Property types are the most primitive types in Cypher and include the following: `BOOLEAN`, `DATE`, `DURATION`, `FLOAT`, `INTEGER`, `LIST`, `LOCAL DATETIME`, `LOCAL TIME`, `POINT`, `STRING`, `VECTOR` (introduced in Neo4j 2025.xx) `ZONED DATETIME`, and `ZONED TIME`. * Property types can be returned from Cypher queries. * Property types can be used as xref::syntax/parameters.adoc[parameters]. * Property types can be stored as properties. * Property types can be constructed with Cypher literals. -Homogeneous lists of simple types can be stored as properties, although lists in general (see xref::values-and-types/property-structural-constructed.adoc#constructed-types[Constructed types]) cannot be stored as properties. +Homogeneous lists of simple types can be stored as properties (with the exeption of xref:values-and-types/vector.adoc[`VECTOR` types], which cannot be stored in lists), although lists in general (see xref::values-and-types/property-structural-constructed.adoc#constructed-types[Constructed types]) cannot be stored as properties. Lists stored as properties cannot contain `null` values. +Storing `VECTOR` type values as properties is only supported in the Neo4j Enterprise Edition using link:{neo4j-docs-base-uri}/operations-manual/current/database-internals/store-formats/#store-format-overview[block format] or on Aura instances. This functionality is not available in Neo4j Community Edition. + Cypher also provides pass-through support for byte arrays, which can be stored as property values. Byte arrays are supported for performance reasons, since using Cypher's generic data type, `LIST` (where each `INTEGER` has a 64-bit representation), would be too costly. However, byte arrays are _not_ considered a first class data type by Cypher, so they do not have a literal representation. - [[structural-types]] == Structural types @@ -94,12 +94,13 @@ However, not all types can be used in all places. | `MAP` | | `NODE` | `ANY NODE`, `VERTEX`, `ANY VERTEX` | `NOTHING` | -| `null` | +| `NULL` | | `PATH` | | `POINT` | | `PROPERTY VALUE` | `ANY PROPERTY VALUE` | `RELATIONSHIP` | `ANY RELATIONSHIP`, `EDGE`, `ANY EDGE` | `STRING` | `VARCHAR` +| `VECTOR(DIMENSION)` label:new[Introduced in Neo4j 2025.xx] | `VECTOR`, `VECTOR`, `VECTOR(DIMENSION)`, `VECTOR(DIMENSION, TYPE)` | `ZONED DATETIME` | `TIMESTAMP WITH TIME ZONE`, `TIMESTAMP WITH TIMEZONE` | `ZONED TIME` | `TIME WITH TIME ZONE`, `TIME WITH TIMEZONE` | `INNER_TYPE_1 \| INNER_TYPE_2...` | `ANY` @@ -110,7 +111,7 @@ A shorthand syntax equivalent for `NOT NULL` is to use an exclamation mark `!` ( Note that closed dynamic types (`INNER_TYPE_1 | INNER_TYPE_2...`) cannot be appended with `NOT NULL`: all inner types must be nullable, or all appended with `NOT NULL`. [[type-normalization]] -== Type Normalization +== Type normalization Cypher runs a normalization algorithm on all input types, simplifying the given type to a deterministic representation for equivalent types. Types are simplified to their default name (e.g. `BOOL` is simplified to `BOOLEAN`). @@ -124,41 +125,95 @@ For example, given the closed dynamic type `BOOL | LIST | BOOLEAN | LIST(12345)` +| `VECTOR` +| `VECTOR` is the supertype and encompasses all others. + +| `VECTOR \| VECTOR(12345)` +| `VECTOR \| VECTOR(12345)` +| Cannot be normalized — one vector lacks a dimension, the other lacks a coordinate type. + +| `VECTOR \| VECTOR(12345)` +| `VECTOR` +| Same type, the vector without a defined dimension encompasses the other. + +| `VECTOR(12345) \| VECTOR(12345)` +| `VECTOR(12345)` +| Same dimension, the vector without a defined coordinate type encompasses the other. + +| `VECTOR \| VECTOR` +| `VECTOR \| VECTOR` +| Cannot be normalized — coordinate types differ. + +| `VECTOR(1234) \| VECTOR(12345)` +| `VECTOR(1234) \| VECTOR(12345)` +| Cannot be normalized — dimensions differ. + +| `VECTOR(1234) \| VECTOR(1234)` +| `VECTOR(1234) \| VECTOR(1234)` +| Cannot be normalized — coordinate types differ, even if dimensions match. +|=== + + [[ordering-of-types]] === Ordering of types The ordering of types is as follows: - * Predefined types - ** `NOTHING` - ** `null` - ** `BOOLEAN` - ** `STRING` - ** `INTEGER` - ** `FLOAT` - ** `DATE` - ** `LOCAL TIME` - ** `ZONED TIME` - ** `LOCAL DATETIME` - ** `ZONED DATETIME` - ** `DURATION` - ** `POINT` - ** `NODE` - ** `RELATIONSHIP` - * Constructed types - ** `MAP` - ** `LIST` (ordered by the inner type) - ** `PATH` - * Dynamic union types - ** `INNER_TYPE_1 \| INNER_TYPE_2...` (ordered by specific rules for closed dynamic union type) - ** `ANY` +* Predefined types +** `NOTHING` +** `NULL` +** `BOOLEAN` +** `STRING` +** `INTEGER8`* +** `INTEGER16`* +** `INTEGER32`* +** `INTEGER` (`INTEGER64`) +** `FLOAT32`* +** `FLOAT` (`FLOAT64`) +** `DATE` +** `LOCAL TIME` +** `ZONED TIME` +** `LOCAL DATETIME` +** `ZONED DATETIME` +** `DURATION` +** `POINT` +** `NODE` +** `RELATIONSHIP` +** `VECTOR` (ordered by coordinate type and dimension) + +++*++ _Vector-only coordinate type._ + +* Constructed types +** `MAP` +** `LIST` (ordered by the inner type) +** `PATH` + +* Dynamic union types +** `INNER_TYPE_1 | INNER_TYPE_2...` (ordered by specific rules for closed dynamic union type) +** `ANY` Subtypes are always ordered before any enclosing types (e.g. `LIST` is ordered before `LIST`). This also means that the `NOT NULL` variants of each type comes before the nullable variant. The order between two closed dynamic unions `A` and `B` is determined as followed: - * If `A` has fewer inner types than `B`, `A` is ordered first. - * If `A` and `B` have the same number of inner types, they are ordered according to the order of the first inner type that differ (lexicographic order). +* If `A` has fewer inner types than `B`, `A` is ordered first. +* If `A` and `B` have the same number of inner types, they are ordered according to the order of the first inner type that differ (lexicographic order). The resulting order is deterministic. @@ -186,13 +241,33 @@ Note that Cypher types are implemented using Java, and that below table referenc | `P292471208677Y6M15DT15H36M32.999999999S` | Nanoseconds -| `FLOAT` -| `Double.MIN_VALUE` footnote:[The minimum value represents the minimum positive value of a `FLOAT`, i.e. the closest value to zero. -It is also possible to have a negative float.] +| `FLOAT32`* +| `Float.MIN_VALUE` footnote:[For both `FLOAT32` and `FLOAT64`, the minimum value represents the minimum positive value, i.e. the closest value to zero. +Negative values are also possible.] +| `Float.MAX_VALUE` +| 32 bit + +| `FLOAT` (`FLOAT64`) +| `Double.MIN_VALUE` | `Double.MAX_VALUE` | 64 bit -| `INTEGER` +| `INTEGER8`* +| `Byte.MIN_VALUE` +| `Byte.MAX_VALUE` +| 8 bit + +| `INTEGER16`* +| `Short.MIN_VALUE` +| `Short.MAX_VALUE` +| 16 bit + +| `INTEGER32`* +| `Integer.MIN_VALUE` +| `Integer.MAX_VALUE` +| 32 bit + +| `INTEGER` (`INTEGER64`) | `Long.MIN_VALUE` | `Long.MAX_VALUE` | 64 bit @@ -231,6 +306,11 @@ It is also possible to have a negative float.] | - | - +| `VECTOR(DIMENSION)` +| Minimum of the coordinate type at the given dimension. +| Maximum of the coordinate type at the given dimension. +| Precision of the coordinate type. + | `ZONED DATETIME` | `-999_999_999-01-01T00:00:00+18:00` | `+999_999_999-12-31T23:59:59.999999999-18:00` @@ -242,22 +322,50 @@ It is also possible to have a negative float.] | Nanoseconds |=== +++*++ _Vector-only coordinate type._ + + === Java value details [.values, opts="header", width=75%, cols="1,3"] |=== | Name | Value +| `Byte.MAX_VALUE` +| 127 + +| `Byte.MIX_VALUE` +| -128 + | `Double.MAX_VALUE` | 1.7976931348623157e+308 | `Double.MIN_VALUE` | 4.9e-324 +| `Float.MAX_VALUE` +| 3.4028235E38 + +| `Float.MIN_VALUE` +| 1.4E-45 + +| `Integer.MAX_VALUE` +| 2147483647 + +| `Integer.MIN_VALUE` +| -2147483648 + | `Long.MAX_VALUE` | 2^63-1 | `Long.MIN_VALUE` -| -2^63 +| -2^63 + +| `SHORT.MAX_VALUE` +| 32767 + +| `SHORT.MIN_VALUE` +| -32768 + |=== diff --git a/modules/ROOT/pages/values-and-types/vector.adoc b/modules/ROOT/pages/values-and-types/vector.adoc new file mode 100644 index 000000000..175f51641 --- /dev/null +++ b/modules/ROOT/pages/values-and-types/vector.adoc @@ -0,0 +1,184 @@ += Vectors +:description: Information about Cypher's `VECTOR` type. +:page-role: new-2025.xx + + +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 utilized 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-type]] +== The vector type + +The `VECTOR` type is a fixed-length, ordered collection of 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. + +.Example `VECTOR` type +[source] +---- +VECTOR([1.05, 0.123, 5], 3, FLOAT32 NOT NULL) +---- + +In this example `VECTOR` type value, `[1.05, 0.123, 5]` is the coordinates of the `VECTOR`, `3` defines its dimensionality, and `FLOAT32` specifies 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, unlike `LIST` values which contain elements that can be accessed individually with xref:expressions/list-expressions.adoc[list expressions], all operations on a `VECTOR` must operate on the entire `VECTOR`; it is not possible to access or slice individual dimensions of a `VECTOR` value. +Additionally, Neo4j cannot store lists containing `VECTOR` values. + +The dimension of a `VECTOR` value must be larger than `0` and less than or equal to `4096`. + +The following coordinate types are supported: + +.Vector coordinate types +[options="header",cols="2*(DIMENSION)` are a part. +This logic continues for `VECTOR` types that define only a coordinate type or a dimension. +A `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(4)` and `VECTOR(4)`. +Similarly, a `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` is a supertype of `VECTOR(3)` and `VECTOR(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 + +To construct a `VECTOR` value, use the xref:functions/vector.adoc#functions-vector[`vector()`] function. + +The following query constructs a three-dimensional vector with `INTEGER` values. +It returns the `VECTOR` itself, and the xref:functions/scalar.adoc#functions-valuetype[`valueType()`] function is used to return information about its type. + +.Construct a `VECTOR` value +[source, cypher] +---- +WITH vector([1, 2, 3], 3, INTEGER) AS vector +RETURN vector, valueType(vector) AS vectorType +---- + +.Result +[role="queryresult",options="header,footer",cols="2*(3) NOT NULL" + +2+d|Rows: 1 +|=== + +The following example uses a parameter containing a `LIST` as input to `vectorValue`. + +.Parameters +[source, parameters] +---- +{ + "integerList": [1, 2, 3, 4, 5] +} +---- + +.Construct a `VECTOR` value with using a parameter for `vectorValue` +[source, cypher] +---- +WITH vector($integerList, 5, INTEGER8) as vector +RETURN vector, valueType(vector) AS vectorType +---- + +.Result +[role="queryresult",options="header,footer",cols="2*(5) NOT NULL" + +2+d|Rows: 1 +|=== + +[role=label--enterprise-edition] +[[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. + +[NOTE] +Storing `VECTOR` values on an on-prem instance requires Neo4j's link:{neo4j-docs-base-uri}/operations-manual/current/database-internals/store-formats/#store-format-overview[block format]. + +.Create a node and assign a `VECTOR` property +[source, cypher] +---- +CREATE (n:Label {vectorProp: vector([1,2,3], 3, INTEGER)}) +RETURN n.vectorProp AS vectorProp +---- + +.Result +[role="queryresult",options="header,footer",cols="1*