$vector in collections
$vector is a reserved field in documents.
It stores a vector embedding that is used for vector search
Only vector-enabled collections support the $vector field.
For more information, see Create a collection that can store vector embeddings.
Insert and update a document’s $vector field
When you insert or update a document, you can use the $vector field to store a vector embedding for the document.
For an example, see Insert documents with vector embeddings.
All vector embeddings in a collection should be generated by the same model with the same dimensions. Using mismatched embeddings produces unreliable and incorrect results in vector searches. The Data API only checks that the dimensions are the same; it doesn’t check whether the embeddings are from different models.
Return the $vector field
By default, the Data API excludes the $vector field from returned documents.
If you want the Data API to return the $vector field, you must use a projection to explicitly include the $vector field in the response.
Binary encoding of vector embeddings
-
Python
-
TypeScript
-
Go
-
Java
-
C#
-
curl
When inserting or updating documents, you can specify the $vector field as an array of floats or use the astrapy.data_types.DataAPIVector class to represent and encode the vector embedding.
Similarly, for vector searches, you can provide the search vector as an array of floats or use the astrapy.data_types.DataAPIVector class.
DataAPIVector is a wrapper around a list of floats.
from astrapy.data_types import DataAPIVector
vector = DataAPIVector([.08, .68, .30])For collections and documents, regardless of whether you use a DataAPIVector object or a list of floats, vector embeddings are binary-encoded by default, which improves performance.
To change the default encoding, see Serdes Options and Custom Data Types.
When you read the value of a $vector field, the client always returns a DataAPIVector object, unless you change the default ser/des behavior.
For more information, see DataAPIVector.
When inserting or updating documents, you can specify the $vector field as an array of floats or use the DataAPIVector class to represent and encode the vector embedding.
Similarly, for vector searches, you can provide the search vector as an array of floats or use the DataAPIVector class.
DataAPIVector is a wrapper around an array of floats.
import { DataAPIVector } from '@datastax/astra-db-ts';
const vector = new DataAPIVector([0.4, -0.6, 0.2]);For collections and documents, regardless of whether you use a DataAPIVector object or a list of floats, the vector embeddings are binary-encoded by default, which improves performance.
To change the default encoding, see Custom Ser/Des.
|
The Go client is in preview. For more information, see astra-db-go. |
When inserting or updating documents, you can specify the $vector field as a slice of floats or use the datatypes.Vector struct to represent and binary-encode the vector embedding.
Similarly, for vector searches, you can provide the search vector as a slice of floats or use the datatypes.Vector struct.
Use datatypes.NewVector to create a datatypes.Vector struct:
package main
import (
"github.com/datastax/astra-db-go/v2/astra/datatypes"
)
func main() {
vector := datatypes.NewVector(
[]float32{0.08, -0.62, 0.39},
)
}For collections and documents, regardless of whether you use a slice of floats or the datatypes.Vector struct, vector embeddings are binary-encoded by default, which improves performance.
When you read the value of the $vector field, the client always returns a datatypes.Vector struct when you decode the results into astra.Document or map[string]any.
To decode the vector as a slice of floats, decode into a custom struct that defines the $vector field as []float32.
When inserting or updating documents, you can specify the $vector field as an array of floats or use the DataAPIVector class to represent and encode the vector embedding.
Similarly, for vector searches, you can provide the search vector as an array of floats or use the DataAPIVector class.
DataAPIVector is a wrapper around an array of floats.
import com.datastax.astra.client.core.vector.DataAPIVector;
DataAPIVector vector = new DataAPIVector(new float[] {.1f, .2f});When you send a DataAPIVector object, the vector embeddings are binary-encoded by default.
DataStax recommends that you always use a DataAPIVector object instead of a list of floats to improve performance.
For more information, see DataAPIVector.
The C# client automatically binary-encodes your vector embeddings when you insert into the $vector field in a collection.
Similarly, the client binary-encodes the search vector when you perform a vector search.
When inserting or updating documents with HTTP, you can specify the $vector field using either an array of floats or a Base64-encoded string with $binary.
Similarly, for vector searches, you can provide the search vector as an array of floats or use $binary.
$binary can be more performant.
For examples, see Insert documents with vector embeddings and Use vector search to find documents.
If you use $binary, the underlying bytes must represent 32-bit floating point values in big-endian format.
The byte sequence must be Base64-encoded, with = padding if needed.
For example:
-
[0.1, -0.2, 0.3]is"PczMzb5MzM0+mZma" -
[0.1, 0.2]is"PczMzT5MzM0=" -
[10, 10.5, 100, -91.19]is"QSAAAEEoAABCyAAAwrZhSA=="
The following script can binary-encode vectors:
python
import base64
import struct
input_vector = [0.1, -0.2, 0.3]
d = len(input_vector)
pack_format = ">" + "f" * d
binary_encode = base64.b64encode(struct.pack(pack_format, *input_vector)).decode()When you read the value of a $vector field, the Data API returns either a list of floats or a binary-encoded string, depending
on the format used when writing the document in the collection.
