Insert a row (Python)

Tables with the Data API are currently in public preview. Development is ongoing, and the features and functionality are subject to change. Hyper-Converged Database (HCD), and the use of such, is subject to the DataStax Preview Terms.

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 type compatibility in tables (Python).

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

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 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.

Parameters

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 (Python).
`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 (Python).

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.

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.

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.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
from astrapy.data_types import DataAPIDate, DataAPISet

# Get an existing table
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
    keyspace="KEYSPACE_NAME",
)
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"]),
    }
)

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 (Python). To add a vector column to an existing table, see Alter a table (Python).

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

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.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
from astrapy.data_types import DataAPIVector

# Get an existing table
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
    keyspace="KEYSPACE_NAME",
)
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.08, -0.62, 0.39]),
    }
)

Client reference

For more information, see the client reference.

Insert a row (Python)

Result

Parameters

Examples

Insert a row

Insert a row with vector embeddings

Client reference

Was this helpful?

Give Feedback