BLOB type
Use the blob type for binary data.
Although you can store binary-encoded vector data in a blob column, you cannot create a vector index or perform a vector search on the column.
Instead, use the vector type to store vector data.
|
Due to a known issue with filtering on |
-
Python
-
TypeScript
-
Java
-
C#
-
curl
You can insert binary data to a blob column as a Base64-encoded string with $binary or as a bytes value.
The Python client returns binary data received from the Data API as a bytes value, even if it was inserted as a Base64-encoded string.
from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
# Get an existing table
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
"API_ENDPOINT",
token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
table = database.get_table("TABLE_NAME", keyspace="KEYSPACE_NAME")
# Insert binary values
result = table.insert_one(
{
"example_blob": b"=\xfb\xe7m>\xe9x\xd5?I\xfb\xe7",
"another_example_blob": {"$binary": "PfvnbT7peNU/Sfvn"},
"title": "Example",
}
)You can insert binary data as a DataAPIBlob object.
The DataAPIBlob class and its blob shorthand accept DataAPIBlobLike input, such as ArrayBuffer and { $binary: string }.
The TypeScript client returns binary data received from the Data API as a DataAPIBlob object.
The DataAPIBlob class provides methods like asArrayBuffer() for accessing the binary data.
import {
DataAPIClient,
UsernamePasswordTokenProvider,
DataAPIBlob,
} from "@datastax/astra-db-ts";
// Get an existing table
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const table = database.table("TABLE_NAME", {
keyspace: "KEYSPACE_NAME",
});
// Insert binary values
(async function () {
const result = await table.insertOne({
example_blob: new DataAPIBlob({ $binary: "PfvnbT7peNU/Sfvn" }),
another_example_blob: new DataAPIBlob(Buffer.from([0x0, 0x1, 0x2])),
title: "Example",
});
})();You can insert binary data as a byte array.
The Java client automatically converts byte[] values into a Base64-encoded string.
import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.commands.results.TableInsertOneResult;
import com.datastax.astra.client.tables.definition.rows.Row;
public class Example {
public static void main(String[] args) {
// Get and existing table
Table<Row> table =
DataAPIClients.clientHCD("USERNAME", "PASSWORD")
.getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
.getTable("TABLE_NAME");
// Insert binary values
byte[] exampleBytes = {
(byte) 0x3D, (byte) 0xFB, (byte) 0xE7, (byte) 0x6D,
(byte) 0x3E, (byte) 0xE9, (byte) 0x78, (byte) 0xD5,
(byte) 0x3F, (byte) 0x49, (byte) 0xFB, (byte) 0xE7
};
Row row = new Row().addBlob("example_blob", exampleBytes).addText("title", "Example");
TableInsertOneResult result = table.insertOne(row);
}
}You can insert binary data as a byte array.
The C# client automatically converts byte[] values into a Base64-encoded string.
-
Typed
-
Untyped
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Tables;
namespace Examples;
public class ExampleRow
{
[ColumnPrimaryKey]
[ColumnName("title")]
public string Title { get; set; } = null!;
[ColumnName("example_blob")]
public byte[]? ExampleBlob { get; set; }
}
public class Program
{
static async Task Main()
{
// Get an existing table
var client = new DataAPIClient(
new CommandOptions() { Destination = DataAPIDestination.HCD }
);
var database = client.GetDatabase(
"API_ENDPOINT",
DataAPIClient.UsernamePasswordTokenProvider(
"USERNAME",
"PASSWORD"
),
"KEYSPACE_NAME"
);
var table = database.GetTable<ExampleRow>("TABLE_NAME");
// Insert a binary value
var row = new ExampleRow()
{
ExampleBlob = new byte[]
{
0x3D,
0xFB,
0xE7,
0x6D,
0x3E,
0xE9,
0x78,
0xD5,
0x3F,
0x49,
0xFB,
0xE7,
},
Title = "Example",
};
await table.InsertOneAsync(row);
}
}using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Tables;
namespace Examples;
public class Program
{
static async Task Main()
{
// Get an existing table
var client = new DataAPIClient(
new CommandOptions() { Destination = DataAPIDestination.HCD }
);
var database = client.GetDatabase(
"API_ENDPOINT",
DataAPIClient.UsernamePasswordTokenProvider(
"USERNAME",
"PASSWORD"
),
"KEYSPACE_NAME"
);
var table = database.GetTable("TABLE_NAME");
// Insert a binary value
var row = new Row()
{
{
"example_blob",
new byte[]
{
0x3D,
0xFB,
0xE7,
0x6D,
0x3E,
0xE9,
0x78,
0xD5,
0x3F,
0x49,
0xFB,
0xE7,
}
},
{ "title", "Example" },
};
await table.InsertOneAsync(row);
}
}You can insert binary data as a Base64-encoded string with $binary.
Vector binary encodings specification
A d-dimensional vector is a list of d floating-point numbers that can be binary encoded.
To prepare for encoding, the list must be transformed into a sequence of bytes where each float is represented as four bytes in big-endian format.
Then, the byte sequence is Base64-encoded, with = padding, if needed.
For example, here are some vectors and their resulting Base64 encoded strings:
[0.1, -0.2, 0.3] = "PczMzb5MzM0+mZma" [0.1, 0.2] = "PczMzT5MzM0=" [10, 10.5, 100, -91.19] = "QSAAAEEoAABCyAAAwrZhSA=="
Once encoded, you use $binary to pass the Base64 string to the Data API:
{ "$binary": "BASE64_STRING" }You can use a script to encode your vectors, for example:
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()curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/TABLE_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"insertOne": {
"document": {
"example_blob" : {"$binary": "PaPXCr8euFI+x64U"},
"title": "Example"
}
}
}'