Skip to content

Commit 4edc094

Browse files
JPryce-AklundhJPryce-Aklundh
committed
significant update to vector type page
1 parent a85c7b2 commit 4edc094

File tree

2 files changed

+198
-10
lines changed

2 files changed

+198
-10
lines changed

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,9 @@ RETURN val, val IS :: INTEGER AS isInteger
3838
2+d|Rows: 4
3939
|===
4040

41+
[[type-predicate-vector]]
42+
== Type predicate expressions and VECTOR values
43+
4144
[[type-predicate-not]]
4245
== Type predicate expressions with NOT
4346

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

Lines changed: 195 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
Cypher's supports a `VECTOR` type that can be stored as properties on nodes and relationships.
66
`VECTOR` properties can be utilized for efficient semantic retrieval with the Neo4j's xref:indexes/semantic-indexes/vector-indexes.adoc[vector indexes] and xref:genai-integrations.adoc[GenAI plugin].
77

8-
8+
[[construct-vector-values]]
99
== Construct vector type values
1010

1111
To construct a `VECTOR` type value, use the xref:functions/vector.adoc#functions-vector[`vector()`] function.
@@ -24,34 +24,219 @@ The `vectorValue` must be of the same length as the given `dimension` and contai
2424
For example a `VECTOR` with a dimension of `3` has three values, which might represent vector embeddings.
2525
* `coordinateType`: a vector-only coordinate `INTEGER` or `FLOAT` type, determining the data type for each of the values in `vectorValue`.
2626
If `vectorValue` contain elements that are not of the specified coordinate type, they will be coerced to that coordinate type if possible.
27-
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`.
27+
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`.
28+
For details of all available coordinate types, see xref:values-and-types/vector.adoc#vector-super-and-coordinate-types[vector coordinate types] below.
2829

29-
The following expression constructs a three-dimensional vector with integer values:
30+
The following query constructs a three-dimensional vector with `INTEGER` values.
31+
It returns the `VECTOR` itself, and the xref:functions/scalar.adoc#functions-valuetype[`valueType()`] function is used to information about its type.
3032

3133
.Construct a `VECTOR` value
3234
[source, cypher]
3335
----
3436
WITH vector([1,2,3], 3, INTEGER) AS vector
35-
RETURN vector, valueType(vector)
37+
RETURN vector, valueType(vector) AS vectorType
38+
----
39+
40+
.Result
41+
[role="queryresult",options="header,footer",cols="2*<m"]
42+
|===
43+
| vector | vectorType
44+
45+
| [1, 2, 3] | "VECTOR<FLOAT32 NOT NULL>(3) NOT NULL"
46+
47+
2+d|Rows: 1
48+
|===
49+
50+
.Construct a `VECTOR` value with a `STRING` `vectorValue`
51+
[source, cypher]
52+
----
53+
WITH vector("[1.05000e+00, 0.123, 5]", 3, FLOAT32) as vector
54+
RETURN vector, valueType(vector) AS vectorType
55+
----
56+
57+
.Result
58+
[role="queryresult",options="header,footer",cols="2*<m"]
59+
|===
60+
| vector | vectorType
61+
62+
| | "VECTOR<FLOAT32 NOT NULL>(3) NOT NULL"
63+
64+
2+d|Rows: 1
65+
|===
66+
67+
The following example uses a parameter containing a `LIST<INTEGER>` as input to `vectorValue`.
68+
69+
.Parameters
70+
[source, parameters]
71+
----
72+
{
73+
"integerList": [1, 2, 3, 4, 5]
74+
}
75+
----
76+
77+
.Construct a `VECTOR` value with using a parameter for `vectorValue`
78+
[source, cypher]
79+
----
80+
WITH vector($integerList, 5, INTEGER8) as vector
81+
RETURN vector, valueType(vector) AS vectorType
82+
----
83+
84+
.Result
85+
[role="queryresult",options="header,footer",cols="2*<m"]
86+
|===
87+
| vector | vectorType
88+
89+
| [1, 2, 3, 4, 5] | "VECTOR<INTEGER8 NOT NULL>(5) NOT NULL"
90+
91+
2+d|Rows: 1
92+
|===
93+
94+
Both `dimension` and `coordinateType` are optional when using the `vector()` function.
95+
96+
* If `coordinateType` is omitted, the type will be determined by Cypher.
97+
If the `LIST` used as `vectorValue` is mixed containing exclusively `INTEGER` values, then the largest of those types will be set as the `coordinateType`.
98+
For example, `LIST<INTEGER64 | INTEGER32` generates a `VECTOR` value with a `coordinateType` of `INTEGER64`.
99+
If the `vectorValue` contains both `FLOAT` and `INTEGER` values, then the `coordinateType` will be that of the largest `FLOAT` present in `vectorValue`.
100+
For example, `LIST<INTEGER64 | FLOAT64` generates a `VECTOR` value with a `coordinateType` of `FLOAT64`.
101+
102+
* If `dimension` is omitted, it is calculated by taking the size of the `vectorValue`.
103+
For example a `LIST` with 1024 elements generates a `VECTOR` value with the `dimension` `1024`.
104+
105+
.Construct a `VECTOR` value omitting both `dimension` and `coordinateType`
106+
[source, cypher]
107+
----
108+
WITH vector([1, 2.5, 3]) AS vector
109+
RETURN vector, valueType(vector) AS vectorType
110+
----
111+
112+
.Result
113+
[role="queryresult",options="header,footer",cols="2*<m"]
114+
|===
115+
| vector | vectorType
116+
117+
| [1, 2, 3] | "VECTOR<FLOAT64 NOT NULL>(3) NOT NULL"
118+
119+
2+d|Rows: 1
120+
|===
121+
122+
When constructing a `VECTOR` value with the `vector()` function, a `null` `vectorValue`, `dimension`, or `coordinateType` will return `null`.
123+
124+
.`null` values
125+
[source, cypher]
126+
----
127+
RETURN vector(null, 3, FLOAT32) AS nullVectorValue,
128+
vector([1, 2, 3], null, INTEGER8) AS nullDimension,
129+
vector([1, 2, 3], 3, null) AS nullCoordinateType
36130
----
37131

132+
.Result
133+
[role="queryresult",options="header,footer",cols="3*<m"]
134+
|===
135+
| nullVectorValue | nullDimension | nullCoordinateType
38136

39-
[role=label-enterprise-edition]
137+
| null | null | null
138+
139+
3+d|Rows: 1
140+
|===
141+
142+
143+
== Calculate vector size
144+
145+
To calculate the size of a `VECTOR` value, use either the xref:functions/scalar.adoc#functions-size[`size()`] function or the xref:functions/vector.adoc#functions-vector_dimension_count[`vector_dimension_count()`] function
146+
(Unlike `size()`, `vector_dimension_count` will return `null` for any non-`VECTOR` values`).
147+
148+
.Calculate `VECTOR` size with `size()`
149+
[source, cypher]
150+
----
151+
RETURN size(vector([1, 2, 3], 3, INTEGER)) AS size
152+
----
153+
154+
.Result
155+
[role="queryresult",options="header,footer",cols="1*<m"]
156+
|===
157+
| size
158+
159+
| 3
160+
161+
1+d|Rows: 1
162+
|===
163+
164+
.Calculate `VECTOR` size with `vector_dimension_count()`
165+
[source, cypher]
166+
----
167+
RETURN vector_dimension_count(vector([1, 2, 3], 3, INTEGER)) AS size
168+
----
169+
170+
.Result
171+
[role="queryresult",options="header,footer",cols="1*<m"]
172+
|===
173+
| size
174+
175+
| 3
176+
177+
1+d|Rows: 1
178+
|===
179+
180+
[role=label--enterprise-edition]
40181
== Store vector values as properties
41182

183+
To store a `VECTOR` value as a node or relationship property, use the `vector()` function together with a write clause.
42184

185+
.Create a node and assign a `VECTOR` property
186+
[source, cypher]
187+
----
188+
CREATE (n:Label)
189+
SET n.vectorProp = vector([1,2,3], 3, INTEGER))
190+
RETURN n.vectorProp AS vectorProp
191+
----
43192

44-
== Vector types, the GenAI plugin, and vector indexes
193+
.Parameters
194+
[source, parameters]
195+
----
196+
{
197+
"floatList": [1.3, 2.4, 3.1, 4.4, 5.9]
198+
}
199+
----
45200

201+
.Store a `VECTOR` property using a parameter
202+
[source, cypher]
203+
----
204+
CREATE (n:Label)
205+
SET n.vectorProp = vector($floatList, 5, FLOAT)
206+
RETURN n.vectorProp AS vectorProp
207+
----
46208

47-
== Vectors and lists
209+
[[genai-plugin-vector-indexes]]
210+
== Vector values, the GenAI plugin, and vector indexes
48211

212+
The `VECTOR` type can be used for more efficient handling of
49213

50-
Since Vectors are described as having multiple dimensions, they look a bit like the constructed value type LIST<...>. However, all vector operations operate on the entire vector. Operations on individual components of a vector instance are not defined. We therefore conclude that vectors are predefined value types.
51214

52215

216+
[[vector-super-and-coordinate-types]]
217+
== Vector supertypes and vector coordinate types
218+
219+
Though the `dimension` and `coordinateType` can be omitted when creating a `VECTOR` value with the `vector()` function, it is not possible to construct a `VECTOR` value without a dimension or a coordinate type.
220+
As such, `VECTOR` should be considered a supertype (which can be checked for in a xref:expressions/predicates/type-predicate-expressions.adoc#type-predicate-vector[type predicate expressions]) to which all combinations of `VECTOR<TYPE>(DIMENSION)` are a part.
221+
222+
This logic continues for `VECTOR` values that define only a coordinate type or a dimension; a `VECTOR` with only a defined dimension represents all vectors of that dimension regardless of the type (e.g. `VECTOR<INTEGER8>` is a supertype of `VECTOR<INTEGER8>(3)` and `VECTOR<INTEGER8>(1024)`, and a `VECTOR` with only a defined coordinate type represents all vectors of that coordinate type regardless of the dimension (e.g. `VECTOR(3)` is a supertype of `VECTOR<FLOAT>(3)` and `VECTOR<INTEGER8>(3)`).
223+
224+
.Vector coordinate types
225+
[options="header",cols="2*<m"]
226+
|===
227+
| Default name | Alias
228+
229+
| `FLOAT` | `FLOAT64`
230+
| `FLOAT32` |
231+
| `INTEGER` | `INT`, `INT64`, `SIGNED INTEGER`, `INTEGER64`
232+
| `INTEGER8` | `INT8`
233+
| `INTEGER16`| `INT16`
234+
| `INTEGER32` | `INT8`
53235

236+
|===
54237

55-
== Vector supertype and vector coordinate types
56238

57-
Whilst it is not possible to store a typeless, dimensionless vector, it is possible to use that type in a type predicate expression for example; RETURN x IS :: VECTOR which should evaluate to true as long as x is a vector, regardless of its coordinate type or dimension. Due to this, we consider VECTOR to be a supertype of all VECTOR types. This logic continues for vectors that define only a type or a dimension, a VECTOR with only a dimension represents all vectors of that dimension regardless of the type, and a VECTOR with only a type represents all vectors of that type regardless of the dimension.
239+
== Vectors and lists
240+
241+
242+
Since Vectors are described as having multiple dimensions, they look a bit like the constructed value type LIST<...>. However, all vector operations operate on the entire vector. Operations on individual components of a vector instance are not defined. We therefore conclude that vectors are predefined value types.

0 commit comments

Comments
 (0)