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 blob, DataStax does not recommend using blob in primary keys.

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",
  });
})();

The Go client is in preview. For more information, see astra-db-go.

You can insert binary data as a []byte slice or a Base64-encoded string with $binary. []byte slices are automatically Base64-encoded.

By default, the Go client returns binary data received from the Data API as a []byte slice.

package main

import (
	"context"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/options"
)

func main() {
	ctx := context.Background()
	// Get an existing table
	client := astra.NewClient(
		options.API().SetDataAPIBackend(options.DataAPIBackendHCD),
	)

	database := client.Database(
		"API_ENDPOINT",
		options.API().
			SetTokenProvider(
				options.NewUsernamePasswordTokenProvider(
					"USERNAME",
					"PASSWORD",
				),
			).
			SetKeyspace("KEYSPACE_NAME"),
	)

	table := database.Table("TABLE_NAME")

	// Insert binary values
	_, err := table.InsertOne(
		ctx,
		map[string]any{
			// Using $binary with a Base64-encoded string
			"example_blob": map[string]any{
				"$binary": "PfvnbT7peNU/Sfvn",
			},
			// No need for explicit '$binary' with a byte array
			"another_example_blob": []byte{
				0x3d,
				0xfb,
				0xe7,
				0x6d,
				0x3e,
				0xe9,
				0x78,
				0xd5,
				0x3f,
				0x49,
				0xfb,
				0xe7,
			},
			"title": "Example",
		},
	)
	if err != nil {
		log.Fatal(err)
	}
}

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.

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"
    }
  }
}'

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()

BLOB type

Was this helpful?

Give Feedback