Insert a row

Inserts a single row into a table.

This method can insert a row in an existing CQL table, but the Data API does not support all CQL data types or modifiers. For more information, see Data types in tables.

For general information about working with tables and rows, see About tables with the Data API.

Ready to write code? See the examples for this method to get started. If you are new to the Data API, check out the quickstart.

Result

Python
TypeScript
Java
curl

Inserts the specified row and returns a TableInsertOneResult object that includes the primary key of the inserted row as a dictionary and as a tuple.

If a row with the specified primary key already exists in the table, the row will be overwritten with the specified column values. Unspecified columns will remain unchanged.

If any of the inserted columns use the wrong datatype or improper encoding, then the entire insert fails.

Inserts the specified row and returns a promise that resolves to a TableInsertOneResult<PKey> object that includes the primary key of the inserted row. The primary key type is inferred from the PKey of the table’s type. If it cannot be inferred from the PKey, it is instead inferred from Partial<Schema>.

If a row with the specified primary key already exists in the table, the row will be overwritten with the specified column values. Unspecified columns will remain unchanged.

If any of the inserted columns use the wrong datatype or improper encoding, then the entire insert fails.

Inserts the specified row and returns a TableInsertOneResult instance that includes the primary key of the inserted row and the schema of the primary key.

If a row with the specified primary key already exists in the table, the row will be overwritten with the specified column values. Unspecified columns will remain unchanged.

If any of the inserted columns use the wrong datatype or improper encoding, then the entire insert fails.

Inserts the specified row. In the JSON response, status.primaryKeySchema is an object that describes the table’s primary key definition, including column names and types. status.insertedIds is a nested array that contains the values inserted for each primary key column.

If a row with the specified primary key already exists in the table, the row will be overwritten with the specified column values. Unspecified columns will remain unchanged.

If any of the inserted columns use the wrong datatype or improper encoding, then the entire insert fails.

Example response for a single-column primary key:

{
  "status": {
    "primaryKeySchema": {
      "email": {
        "type": "ascii"
      }
    },
    "insertedIds": [
      [
        "tal@example.com"
      ]
    ]
  }
}

Example response for a multi-column primary key:

{
  "status": {
    "primaryKeySchema": {
      "email": {
        "type": "ascii"
      },
      "graduation_year": {
        "type": "int"
      }
    },
    "insertedIds": [
      [
        "tal@example.com",
        2014
      ]
    ]
  }
}

Parameters

Python
TypeScript
Java
curl

Use the insert_one method, which belongs to the astrapy.Table class.

Method signature

insert_one(
  row: Dict[str, Any],
  *,
  general_method_timeout_ms: int,
  request_timeout_ms: int,
  timeout_ms: int,
) -> TableInsertOneResult:

Name Type Summary

Name	Type	Summary
`row`	`dict`	A dictionary that defines the row to insert. All primary key values are required. To reduce tombstones, you should not explicitly set a column to `null`. The table definition determines the columns in the row, the type for each column, and the primary key. To get this information, see List table metadata.
`general_method_timeout_ms`	`int`	Optional. The maximum time, in milliseconds, that the client should wait for the underlying HTTP request. This parameter is aliased as `request_timeout_ms` and `timeout_ms`. Default: The default value for the table. This default is 30 seconds unless you specified a different default when you initialized the `Table` or `DataAPIClient` object. For more information, see Timeout options.

row

dict

A dictionary that defines the row to insert.

All primary key values are required.

To reduce tombstones, you should not explicitly set a column to null.

The table definition determines the columns in the row, the type for each column, and the primary key. To get this information, see List table metadata.

general_method_timeout_ms

int

Optional. The maximum time, in milliseconds, that the client should wait for the underlying HTTP request.

This parameter is aliased as request_timeout_ms and timeout_ms.

Default: The default value for the table. This default is 30 seconds unless you specified a different default when you initialized the Table or DataAPIClient object. For more information, see Timeout options.

Use the insertOne method, which belongs to the Table class.

Method signature

async insertOne(
  row: Schema,
  options?: {
    timeout?: number | TimeoutDescriptor,
  },
): TableInsertOneResult<PKey>

Name Type Summary

Name	Type	Summary
`row`	`Schema`	An object that defines the row to insert. All primary key values are required. To reduce tombstones, you should not explicitly set a column to `null`. The table definition determines the columns in the row, the type for each column, and the primary key. To get this information, see List table metadata.
`options.timeout`	`number` \| `TimeoutDescriptor`	Optional. A timeout to impose on the underlying API request.

row

Schema

An object that defines the row to insert.

All primary key values are required.

To reduce tombstones, you should not explicitly set a column to null.

The table definition determines the columns in the row, the type for each column, and the primary key. To get this information, see List table metadata.

options.timeout

number | TimeoutDescriptor

Optional. A timeout to impose on the underlying API request.

Use the insertOne method, which belongs to the com.datastax.astra.client.tables.Table class.

Method signature

TableInsertOneResult insertOne(T row)

TableInsertOneResult insertOne(
  T row,
  TableInsertOneOptions insertOneOptions
)

Name Type Summary

Name	Type	Summary
`row`	`Row`	An object that defines the row to insert. The `Row` object is similar to a `Map`. All primary key values are required. To reduce tombstones, you should not explicitly set a column to `null`. The table definition determines the columns in the row, the type for each column, and the primary key. To get this information, see List table metadata.
`options`	`TableInsertOneOptions`	Optional. The options for this operation, including the timeout.

row

Row

An object that defines the row to insert. The Row object is similar to a Map.

All primary key values are required.

To reduce tombstones, you should not explicitly set a column to null.

The table definition determines the columns in the row, the type for each column, and the primary key. To get this information, see List table metadata.

options

TableInsertOneOptions

Optional. The options for this operation, including the timeout.

Use the insertOne command.

Command signature

curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/TABLE_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "insertOne": {
    "document": ROW
  }
}'

Name Type Summary

Name	Type	Summary
`document`	`object`	An object that defines the row to insert. All primary key values are required. To reduce tombstones, you should not explicitly set a column to `null`. The table definition determines the columns in the row, the type for each column, and the primary key. To get this information, see List table metadata.

document

object

An object that defines the row to insert.

All primary key values are required.

To reduce tombstones, you should not explicitly set a column to null.

The table definition determines the columns in the row, the type for each column, and the primary key. To get this information, see List table metadata.

Examples

The following examples demonstrate how to insert a row into a table.

Insert a row

When you insert a row, you must specify a non-null value for each primary key column. Non-primary key columns are optional. To reduce tombstones, you should not explicitly set a column to null.

Python
TypeScript
Java
curl

The following example uses untyped documents or rows, but you can define a client-side type for your collection to help statically catch errors. For examples, see Typing support.

from astrapy import DataAPIClient
from astrapy.data_types import (
    DataAPISet,
    DataAPIDate,
)

# Get an existing table
client = DataAPIClient()
database = client.get_database("API_ENDPOINT", token="APPLICATION_TOKEN")
table = database.get_table("TABLE_NAME")

# Insert a row into the table
result = table.insert_one(
    {
        "title": "Computed Wilderness",
        "author": "Ryan Eau",
        "number_of_pages": 432,
        "due_date": DataAPIDate.from_string("2024-12-18"),
        "genres": DataAPISet(["History", "Biography"]),
    }
)

import { DataAPIClient, date } from "@datastax/astra-db-ts";

// Get an existing table
const client = new DataAPIClient();
const database = client.db("API_ENDPOINT", {
  token: "APPLICATION_TOKEN",
});
const table = database.table("TABLE_NAME");

// Insert a row into the table
(async function () {
  const result = await table.insertOne({
    title: "Computed Wilderness",
    author: "Ryan Eau",
    number_of_pages: 432,
    due_date: date("2024-12-18"),
    genres: new Set(["History", "Biography"]),
  });
})();

import com.datastax.astra.client.DataAPIClient;
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;
import java.util.Calendar;
import java.util.Date;
import java.util.Set;

public class Example {

  public static void main(String[] args) {
    // Get an existing table
    Table<Row> table =
        new DataAPIClient("APPLICATION_TOKEN")
            .getDatabase("API_ENDPOINT")
            .getTable("TABLE_NAME");

    // Insert a row into the table
    Calendar calendar = Calendar.getInstance();
    calendar.set(2024, Calendar.DECEMBER, 18);
    Date date = calendar.getTime();
    Row row =
        new Row()
            .addText("title", "Computed Wilderness")
            .addText("author", "Ryan Eau")
            .addInt("number_of_pages", 432)
            .addDate("due_date", date)
            .addSet("genres", Set.of("History", "Biography"));
    TableInsertOneResult result = table.insertOne(row);
    System.out.println(result.getInsertedId());
  }
}

curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/TABLE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "insertOne": {
    "document": {
      "title": "Computed Wilderness",
      "author" :"Ryan Eau",
      "number_of_pages": 432,
      "due_date": "2024-12-18",
      "genres": ["History", "Biography"]
    }
  }
}'

Insert a row with vector embeddings

You can only insert vector embeddings into vector columns.

To create a table with a vector column, see Create a table. To add a vector column to an existing table, see Alter a table.

All embeddings in the column should use the same provider, model, and dimensions. Mismatched embeddings can cause inaccurate vector searches.

Python
TypeScript
Java
curl

You can use the astrapy.data_types.DataAPIVector class to binary-encode your vector embeddings. DataStax recommends that you always use a DataAPIVector object instead of a list of floats to improve performance.

from astrapy import DataAPIClient
from astrapy.data_types import (
    DataAPIVector,
)

# Get an existing table
client = DataAPIClient()
database = client.get_database("API_ENDPOINT", token="APPLICATION_TOKEN")
table = database.get_table("TABLE_NAME")

# Insert a row into the table
result = table.insert_one(
    {
        "title": "Computed Wilderness",
        "author": "Ryan Eau",
        "summary_genres_vector": DataAPIVector([0.4, -0.6, 0.2]),
    }
)

You can use the DataAPIVector class to binary-encode your vector embeddings. DataStax recommends that you always use a DataAPIVector object instead of a list of floats to improve performance.

import { DataAPIClient, DataAPIVector } from "@datastax/astra-db-ts";

// Get an existing table
const client = new DataAPIClient();
const database = client.db("API_ENDPOINT", {
  token: "APPLICATION_TOKEN",
});
const table = database.table("TABLE_NAME");

// Insert a row into the table
(async function () {
  const result = await table.insertOne({
    title: "Computed Wilderness",
    author: "Ryan Eau",
    summary_genres_vector: new DataAPIVector([0.4, -0.6, 0.2]),
  });
})();

You can use the DataAPIVector class to binary-encode your vector embeddings. DataStax recommends that you always use a DataAPIVector object instead of a list of floats to improve performance.

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.core.vector.DataAPIVector;
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 an existing table
    Table<Row> table =
        new DataAPIClient("APPLICATION_TOKEN")
            .getDatabase("API_ENDPOINT")
            .getTable("TABLE_NAME");

    // Insert a row into the table
    Row row =
        new Row()
            .addText("title", "Computed Wilderness")
            .addText("author", "Ryan Eau")
            .addVector("summary_genres_vector", new DataAPIVector(new float[] {0.4f, -0.6f, 0.2f}));
    TableInsertOneResult result = table.insertOne(row);
    System.out.println(result.getInsertedId());
  }
}

You can provide the vector embeddings as an array of floats, or you can use $binary to provide the vector embeddings as a Base64-encoded string. $binary can be more performant.

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

Array of floats
$binary

curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/TABLE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "insertOne": {
    "document": {
      "title": "Computed Wilderness",
      "author" :"Ryan Eau",
      "summary_genres_vector": [.12, .52, .32]
    }
  }
}'

curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/TABLE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "insertOne": {
    "document": {
      "title": "Computed Wilderness",
      "author" :"Ryan Eau",
      "summary_genres_vector": {"$binary": "PfXCjz8FHrg+o9cK"}
    }
  }
}'

Insert a row and generate vector embeddings

To automatically generate vector embeddings, your table must have a vector column with an embedding provider integration. You can configure embedding provider integrations when you create a table, add a vector column to an existing table, or alter an existing vector column.

When you insert a row, you can pass a string to the vector column. Astra DB uses the embedding provider integration to generate vector embeddings from that string.

The strings used to generate the vector embeddings are not stored. If you want to store the original strings, you must store them in a separate column.

In the following examples, summary_genres_vector is a vector column that has an embedding provider integration configured, and summary_genres_original_text is a text column to store the original text.

Python
TypeScript
Java
curl

The following example uses untyped documents or rows, but you can define a client-side type for your collection to help statically catch errors. For examples, see Typing support.

from astrapy import DataAPIClient

# Get an existing table
client = DataAPIClient()
database = client.get_database("API_ENDPOINT", token="APPLICATION_TOKEN")
table = database.get_table("TABLE_NAME")

# Insert a row into the table
result = table.insert_one(
    {
        "title": "Computed Wilderness",
        "author": "Ryan Eau",
        "summary_genres_vector": "Text to vectorize",
        "summary_genres_original_text": "Text to vectorize",
    }
)

import { DataAPIClient } from "@datastax/astra-db-ts";

// Get an existing table
const client = new DataAPIClient();
const database = client.db("API_ENDPOINT", {
  token: "APPLICATION_TOKEN",
});
const table = database.table("TABLE_NAME");

// Insert a row into the table
(async function () {
  const result = await table.insertOne({
    title: "Computed Wilderness",
    author: "Ryan Eau",
    summary_genres_vector: "Text to vectorize",
    summary_genres_original_text: "Text to vectorize",
  });
})();

import com.datastax.astra.client.DataAPIClient;
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 an existing table
    Table<Row> table =
        new DataAPIClient("APPLICATION_TOKEN")
            .getDatabase("API_ENDPOINT")
            .getTable("TABLE_NAME");

    // Insert a row into the table
    Row row =
        new Row()
            .addText("title", "Computed Wilderness")
            .addText("author", "Ryan Eau")
            .addVectorize("summary_genres_vector", "Text to vectorize")
            .addText("summary_genres_original_text", "Text to vectorize");
    TableInsertOneResult result = table.insertOne(row);
    System.out.println(result.getInsertedId());
  }
}

curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/TABLE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "insertOne": {
    "document": {
      "title": "Computed Wilderness",
      "author" :"Ryan Eau",
      "summary_genres_vector": "Text to vectorize",
      "summary_genres_original_text": "Text to vectorize"
    }
  }
}'

Insert a row with a map column that uses non-string keys

Python
TypeScript
Java
curl

To insert a row with a map column that includes non-string keys, you must use an array of key-value pairs to represent the map column.

With the Python client, you can also use DataAPIMap to encode maps that use non-string keys.

from astrapy import DataAPIClient
from astrapy.data_types import DataAPIMap

# Get an existing table
client = DataAPIClient()
database = client.get_database("API_ENDPOINT", token="APPLICATION_TOKEN")
table = database.get_table("TABLE_NAME")

# Insert a row into the table
result = table.insert_one(
    {
        # This map has non-string keys,
        # so the insertion is an array of key-value pairs
        "map_column_1": [[1, "value1"], [2, "value2"]],
        # Alternatively, use DataAPIMap to encode maps with non-string keys
        "map_column_2": DataAPIMap({1: "value1", 2: "value2"}),
        # This map does not have non-string keys,
        # so the insertion does not need to be an array of key-value pairs
        "map_column_3": {"key1": "value1", "key2": "value2"},
        "title": "Once in a Living Memory",
        "author": "Kayla McMaster",
    }
)

To insert a row with a map column that includes non-string keys, you must use an array of key-value pairs to represent the map column.

import { DataAPIClient } from "@datastax/astra-db-ts";

// Get an existing table
const client = new DataAPIClient();
const database = client.db("API_ENDPOINT", {
  token: "APPLICATION_TOKEN",
});
const table = database.table("TABLE_NAME");

// Insert a row into the table
(async function () {
  const result = await table.insertOne({
    // This map has non-string keys,
    // so the insertion is an array of key-value pairs
    map_column_1: [
      [1, "value1"],
      [2, "value2"],
    ],
    // This map does not have non-string keys,
    // so the insertion does not need to be an array of key-value pairs
    map_column_2: {
      key1: "value1",
      key2: "value2",
    },
    title: "Once in a Living Memory",
    author: "Kayla McMaster",
  });
})();

The Java client supports insertion of a row with a map column that includes non-string keys. (You don’t need to use an array of key-value pairs to represent the map column.)

import com.datastax.astra.client.DataAPIClient;
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;
import java.util.Map;

public class Example {

  public static void main(String[] args) {
    // Get an existing table
    Table<Row> table =
        new DataAPIClient("APPLICATION_TOKEN")
            .getDatabase("API_ENDPOINT")
            .getTable("TABLE_NAME");

    // This map has non-string keys,
    // but the insertion can still be represented as a map
    // instead of an array of key-value pairs
    Map<Integer, String> mapColumn1 = Map.of(1, "value1", 2, "value2");

    // This map does not have non-string keys
    Map<String, String> mapColumn2 = Map.of("key1", "value1", "key2", "value2");

    Row row =
        new Row()
            .addMap("map_column_1", mapColumn1)
            .addMap("map_column_2", mapColumn2)
            .addText("title", "Once in a Living Memory")
            .addText("author", "Kayla McMaster");

    TableInsertOneResult result = table.insertOne(row);
    System.out.println(result.getInsertedId());
  }
}

To insert a row with a map column that includes non-string keys, you must use an array of key-value pairs to represent the map column.

curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/TABLE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "insertOne": {
    "document": {
      # This map has non-string keys,
      # so the insertion is an array of key-value pairs
      "map_column_1": [
          [1, "value1"],
          [2, "value2"]
      ],
      # This map does not have non-string keys,
      # so the insertion does not need to be an array of key-value pairs
      "map_column_2": {
        "key1": "value1",
        "key2": "value2"
      },
      "title": "Once in a Living Memory",
      "author": "Kayla McMaster"
    }
  }
}'

Client reference

Python
TypeScript
Java
curl

For more information, see the client reference.

Client reference documentation is not applicable for HTTP.

Insert a row

Result

Parameters

Examples

Insert a row

Insert a row with vector embeddings

Insert a row and generate vector embeddings

Insert a row with a map column that uses non-string keys

Client reference

Was this helpful?

Give Feedback