Insert rows

Tables with the Data API are currently in public preview. Development is ongoing, and the features and functionality are subject to change. Astra DB Serverless, and the use of such, is subject to the DataStax Preview Terms.

Inserts multiple rows 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

Inserts the specified rows and returns a TableInsertManyResult object that includes the primary key of the inserted rows as dictionaries and as ordered tuples.

If a row with the specified primary key already exists in the table, the row is overwritten with the specified column values. Unspecified columns are not changed.

If a row fails to insert and the request is ordered, the operation stops.

Example response:

python
TableInsertManyResult(
  inserted_ids=[
    {'match_id': 'fight4', 'round': 1},
    {'match_id': 'fight5', 'round': 1},
    {'match_id': 'fight5', 'round': 2},
    {'match_id': 'fight5', 'round': 3},
    {'match_id': 'challenge6', 'round': 1}
    ... (13 total)
  ],
  inserted_id_tuples=[
    ('fight4', 1), ('fight5', 1), ('fight5', 2),
    ('fight5', 3), ('challenge6', 1) ... (13 total)
  ],
  raw_results=...
)

Parameters

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

Method signature
python
insert_many(
  rows: Iterable[Dict[str, Any]],
  *,
  ordered: bool,
  chunk_size: int,
  concurrency: int
  general_method_timeout_ms: int,
  request_timeout_ms: int,
  timeout_ms: int,
) -> TableInsertManyResult
Name Type Summary

rows

Iterable[dict]

An iterable of dictionaries, each defining a row to insert. Each dictionary contains key-value pairs for each column in the table. At minimum, primary key values are required. Any unspecified columns are set to null.

The table definition determines the available columns, the primary key, and each column’s type. For more information, see Create a table and Data types in tables.

ordered

bool

If False (default), insertions occur in an arbitrary order with possible concurrency. If True, insertions occur sequentially. If you don’t need ordered inserts, DataStax recommends False, which typically results in a much higher insert throughput than an equivalent ordered insertion.

concurrency

int | None

The maximum number of concurrent requests to the API at a given time. It cannot be more than one for ordered insertions.

chunk_size

int | None

The number of rows to insert in a single API request.

Leave it unspecified (recommended) to use the system default.

general_method_timeout_ms

int | None

a timeout, in milliseconds, to impose on the whole operation, which may consist of several API requests. If not provided, the corresponding Table defaults apply. This parameter is aliased as timeout_ms for convenience.

request_timeout_ms

int | None

a timeout, in milliseconds, to impose on each individual HTTP request to the Data API to accomplish the operation. If not provided, the corresponding Table defaults apply.

Examples

The following examples demonstrate how to insert multiple rows into a table.

Insert rows

When you insert rows, you must specify a non-null value for each primary key column for each row. Non-primary key columns are optional, and any unspecified non-primary key columns are set to null.

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

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

# Insert rows into the table
result = table.insert_many(
    [
        {
            "title": "Computed Wilderness",
            "author": "Ryan Eau",
            "number_of_pages": 432,
            "due_date": DataAPIDate.from_string("2024-12-18"),
            "genres": DataAPISet(["History", "Biography"]),
        },
        {
            "title": "Desert Peace",
            "author": "Walter Dray",
            "number_of_pages": 355,
            "rating": 4.5,
        },
    ]
)

Insert rows 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
from astrapy import DataAPIClient
from astrapy.data_types import (
    DataAPIVector,
)

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

# Insert rows into the table
result = table.insert_many(
    [
        {
            "title": "Computed Wilderness",
            "author": "Ryan Eau",
            "summary_genres_vector": DataAPIVector([0.4, -0.6, 0.2]),
        },
        {
            "title": "Desert Peace",
            "author": "Walter Dray",
            "summary_genres_vector": DataAPIVector([0.3, 0.6, 0.5]),
        },
    ]
)

Insert rows 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 summaryGenresOriginalText is a text column to store the original text.

python
from astrapy import DataAPIClient

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

# Insert rows into the table
result = table.insert_many(
    [
        {
            "title": "Computed Wilderness",
            "author": "Ryan Eau",
            "summary_genres_vector": "Text to vectorize",
            "summaryGenresOriginalText": "Text to vectorize",
        },
        {
            "title": "Desert Peace",
            "author": "Walter Dray",
            "summary_genres_vector": "Text to vectorize",
            "summaryGenresOriginalText": "Text to vectorize",
        },
    ]
)

Insert rows and specify insertion behavior

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

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

# Insert rows into the table
result = table.insert_many(
    [
        {
            "title": "Computed Wilderness",
            "author": "Ryan Eau",
            "number_of_pages": 432,
            "due_date": DataAPIDate.from_string("2024-12-18"),
            "genres": DataAPISet(["History", "Biography"]),
        },
        {
            "title": "Desert Peace",
            "author": "Walter Dray",
            "number_of_pages": 355,
            "rating": 4.5,
        },
    ],
    chunk_size=2,
    concurrency=2,
    ordered=False,
)

Client reference

For more information, see the client reference.

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2025 DataStax | Privacy policy | Terms of use | Manage Privacy Choices

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: +1 (650) 389-6000, info@datastax.com