Insert a row

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

Method signature

  • Python

  • TypeScript

  • Java

  • curl

The following method belongs to the astrapy.Table class.

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

The following method belongs to the Table class.

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

The following methods belong to the com.datastax.astra.client.tables.Table class.

TableInsertOneResult insertOne(T row)
TableInsertOneResult insertOne(
  T row,
  TableInsertOneOptions insertOneOptions
)
curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_TABLE" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "insertOne": {
    "document": ROW
  }
}'

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.

Example response:

TableInsertOneResult(
  inserted_id={'match_id': 'match_0', 'round': 1},
  inserted_id_tuple=('match_0', 1),
  raw_results=...
)

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.

Example response:

{
  insertedId: { matchId: 'match_0', round: 1 },
}

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.

Example response:

{
  "status": {
    "primaryKeySchema": {
      "match_id": {
        "type": "text"
      },
      "round": {
        "type": "int"
      }
    },
    "insertedIds": [
      [
        "match_1",
        2
      ]
    ]
  }
}

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

Name Type Summary

row

dict

Defines the row to insert. 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.

general_method_timeout_ms

int

A timeout, in milliseconds, to impose on the underlying API request. If not provided, the Table defaults apply. This parameter is aliased as request_timeout_ms and timeout_ms for convenience.
Name Type Summary

row

Schema

Defines the row to insert. 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.

options.timeout?

WithTimeout

The client-side timeout for this operation.
Name Type Summary

row

Row

Defines the row to insert. This object is similar to a Map where you can add the object you like with utilities methods. At minimum, you must specify the primary key values in full. 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.

options

TableInsertOneOptions

Specialization of the Table object overriding default configuration (DataAPIOptions)
Name Type Summary

insertOne

command

Data API command to insert one row in a table.

document

object

Defines the row to insert. 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.

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, and any unspecified non-primary key columns are set to null.

  • Python

  • TypeScript

  • Java

  • curl

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

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

# Insert a row into the table
result = table.insert_one(
    {
        "title": "Computed Wilderness",
        "author": "Ryan Eau",
        "numberOfPages": 432,
        "dueDate": 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('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
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",
      numberOfPages: 432,
      dueDate: date("2024-12-18"),
      genres: new Set(["History", "Biography"])
  });
})();
package com.example;

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 InsertOne {

    public static void main(String[] args) {
        // Get an existing table
        Table<Row> table = new DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
            .getDatabase("ASTRA_DB_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("numberOfPages", 432)
                .addDate("dueDate", date)
                .addSet("genres", Set.of("History", "Biography"));
        TableInsertOneResult result = table.insertOne(row);
        System.out.println(result.getInsertedId());
    }
}
curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/TABLE_NAME" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "insertOne": {
    "document": {
      "title": "Computed Wilderness",
      "author" :"Ryan Eau",
      "numberOfPages": 432,
      "dueDate": "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.

  • Python

  • TypeScript

  • Java

  • curl

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

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

# Insert a row into the table
result = table.insert_one(
    {
        "title": "Computed Wilderness",
        "author": "Ryan Eau",
        "summaryGenresVector": DataAPIVector([0.4, -0.6, 0.2]),
    }
)
import { DataAPIClient, DataAPIVector } from '@datastax/astra-db-ts';

// Get an existing table
const client = new DataAPIClient('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
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",
      summaryGenresVector: new DataAPIVector([0.4, -0.6, 0.2]),
  });
})();
package com.example;

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 com.datastax.astra.client.core.vector.DataAPIVector;

public class InsertOne {

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

        // Insert a row into the table
        Row row =
            new Row()
                .addText("title", "Computed Wilderness")
                .addText("author", "Ryan Eau")
                .addVector("summaryGenresVector", 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.

  • Array of floats

  • $binary

curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/TABLE_NAME" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "insertOne": {
    "document": {
      "title": "Computed Wilderness",
      "author" :"Ryan Eau",
      "summaryGenresVector": [.12, .52, .32]
    }
  }
}'
curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/TABLE_NAME" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "insertOne": {
    "document": {
      "title": "Computed Wilderness",
      "author" :"Ryan Eau",
      "summaryGenresVector": {"$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, summaryGenresVector is a vector column that has an embedding provider integration configured, and summaryGenresOriginalText is a text column to store the original text.

  • Python

  • TypeScript

  • Java

  • curl

from astrapy import DataAPIClient

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

# Insert a row into the table
result = table.insert_one(
    {
        "title": "Computed Wilderness",
        "author": "Ryan Eau",
        "summaryGenresVector": "Text to vectorize",
        "summaryGenresOriginalText": "Text to vectorize",
    }
)
import { DataAPIClient } from '@datastax/astra-db-ts';

// Get an existing table
const client = new DataAPIClient('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
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",
      summaryGenresVector: "Text to vectorize",
      summaryGenresOriginalText: "Text to vectorize",
  });
})();
package com.example;

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 InsertOne {

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

        // Insert a row into the table
        Row row =
            new Row()
                .addText("title", "Computed Wilderness")
                .addText("author", "Ryan Eau")
                .addVectorize("summaryGenresVector", "Text to vectorize")
                .addText("summaryGenresOriginalText", "Text to vectorize");
        TableInsertOneResult result = table.insertOne(row);
        System.out.println(result.getInsertedId());
    }
}
curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/TABLE_NAME" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "insertOne": {
    "document": {
      "title": "Computed Wilderness",
      "author" :"Ryan Eau",
      "summaryGenresVector": "Text to vectorize",
      "summaryGenresOriginalText": "Text to vectorize"
    }
  }
}'

Client reference

  • Python

  • TypeScript

  • Java

  • curl

For more information, see the client reference.

For more information, see the client reference.

For more information, see the client reference.

Client reference documentation is not applicable for HTTP.

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