Insert rows

This Astra DB Serverless feature is 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.

The Data API tables commands are available through HTTP and the clients.

If you use a client, tables commands are available only in client versions 2.0-preview or later. For more information, see Data API client upgrade guide.

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.

Method signature

Python
TypeScript
Java
curl

The following method belongs to the astrapy.Table class.

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

The following method belongs to the Table class.

async insertMany(
  rows: readonly WSchema[],
  options?: {
    ordered?: boolean,
    concurrency?: number,
    chunkSize?: number,
    timeout?: number | TimeoutDescriptor,
  }
): TableInsertManyResult<PKey>

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

TableInsertManyResult insertMany(
  List<? extends T> rows,
  TableInsertManyOptions options
)

TableInsertManyResult insertMany(
  List<? extends T> rows
)

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 '{
  "insertMany": {
    "documents": ROWS_JSON_ARRAY,
    "options": {
      "ordered": BOOLEAN,
      "returnDocumentPositions": BOOLEAN
    }
  }
}'

Result

Python
TypeScript
Java
curl

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:

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

Inserts the specified rows and returns a promise that resolves to a TableInsertManyResult<PKey> object that includes the primary keys of the inserted rows. 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<RSchema>.

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, then the operation stops and throws a TableInsertManyError. If chunkSize is greater than one, then the entire chunk containing the failing row fails to insert.

If a row fails to insert and the request is unordered, the operation will try to process the remaining rows and then throw a TableInsertManyError.

TableInsertManyError will indicate which rows were successfully inserted.

Example resolved response:

{
  insertedIds: [
    { matchId: 'match0', round: 0 },
    { matchId: 'match1', round: 0 },
    { matchId: 'match2', round: 0 },
    // ...
  ],
  insertedCount: 50,
}

Inserts the specified rows and returns a TableInsertManyResult instance that includes the primary keys of the inserted rows and the schema of the primary key.

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

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

Example response:

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

Inserts the specified rows.

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.

The JSON response includes the following:

status.primaryKeySchema: An object that describes the table’s primary key definition, including column names and types.
status.insertedIds: A nested array that contains the primary key values for each inserted row. If the primary key has multiple columns, then the order of each array matches the order described by status.primaryKeySchema.

Omitted if the options.returnDocumentPositions parameter is true.
status.documentResponses: An array of objects where each object represents a row. In each object, status describes the outcome of the insertion, and _id is an array that contains the primary key values.

Included only if the options.returnDocumentPositions parameter is true.

You must check the entire response for errors to verify that all rows inserted successfully.

If a row fails to insert and the request is ordered, then the API skips the failed row and all subsequent rows. The API returns an error about the first row that failed to insert.

If a row fails to insert and the request is unordered, then the API skips the failed row but attempts to insert any remaining rows. The response includes a status object that describes successful insertions and an errors array that describes problems with failed rows.

Example response for a single-column primary key:

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

Example response for a multi-column primary key:

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

Parameters

Python
TypeScript
Java
curl

Name Type Summary

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.

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.

Name Type Summary

Name	Type	Summary
`rows`	`Schema[]`	An array of object expressing the rows to insert. Each object 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?`	`TableInsertManyOptions`	The options for this operation.

rows

Schema[]

An array of object expressing the rows to insert. Each object 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?

TableInsertManyOptions

The options for this operation.

Options (TableInsertManyOptions):

Name Type Summary

Name	Type	Summary
`ordered?`	`boolean`	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?`	`number`	The maximum number of concurrent requests to the API at a given time. Defaults to `8`. This is not available for ordered insertions.
`chunkSize?`	`number`	The number of rows to insert in a single API request. Leave it unspecified (recommended) to use the system default.
`timeout?`	`number \| TimeoutDescriptor`	The client-side timeout for this operation.

ordered?

boolean

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?

number

The maximum number of concurrent requests to the API at a given time. Defaults to 8.

This is not available for ordered insertions.

chunkSize?

number

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

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

timeout?

number | TimeoutDescriptor

The client-side timeout for this operation.

Name Type Summary

Name	Type	Summary
`rows`	`List<Row>`	The list of Rows to insert. At minimum, you must specify the primary key values in full for each row. 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`	`TableInsertManyOptions`	Configuration and specialization of the Options

rows

List<Row>

The list of Rows to insert.

At minimum, you must specify the primary key values in full for each row. 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

TableInsertManyOptions

Configuration and specialization of the Options

TableInsertManyOptions:

Name Type Summary

Name	Type	Summary
`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`	The maximum number of concurrent requests to the API at a given time. It cannot be more than one for ordered insertions.
`chunkSize`	`int`	The number of rows to insert in a single API request. Leave it unspecified (recommended) to use the system default.

ordered

bool

concurrency

int

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

chunkSize

int

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

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

Name Type Summary

Name	Type	Summary
`insertMany`	`command`	Data API command to insert multiples row in a table.
`documents`	`array`	An array of objects where each object represents a row to insert. Each row object contains key-value pairs for the columns in the table. At minimum, each row must include primary key values. Any unspecified columns are set to `null`. The table definition determines the available columns, the primary key, and the column types. For more information, see Create a table and Data types in tables. You can insert up to 100 rows per HTTP request. If you want to insert more rows at once, you must make multiple requests or use the Data API clients.
`options`	`object`	Options for the command, including `ordered` and `returnDocumentPositions`.
`options.ordered`	`boolean`	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.
`options.returnDocumentPositions`	`boolean`	If true, the response includes a `status` for each insertion. The default is false.

insertMany

command

Data API command to insert multiples row in a table.

documents

array

An array of objects where each object represents a row to insert. Each row object contains key-value pairs for the columns in the table. At minimum, each row must include primary key values. Any unspecified columns are set to null.

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

You can insert up to 100 rows per HTTP request. If you want to insert more rows at once, you must make multiple requests or use the Data API clients.

options

object

Options for the command, including ordered and returnDocumentPositions.

options.ordered

boolean

options.returnDocumentPositions

boolean

If true, the response includes a status for each insertion. The default is false.

Examples

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

Python
TypeScript
Java
curl

Insert many rows concurrently:

insert_result = my_table.insert_many(
    [
        {
            "match_id": "fight4",
            "round": 1,
            "winner": "Victor",
            "score": 18,
            "when": DataAPITimestamp.from_string(
                "2024-11-28T11:30:00Z",
            ),
            "fighters": DataAPISet([
                UUID("0193539a-2770-8c09-a32a-111111111111"),
                UUID('019353e3-00b4-83f9-a127-222222222222'),
            ]),
            "m_vector": DataAPIVector([0.4, -0.6, 0.2]),
        },
        {"match_id": "fight5", "round": 1, "winner": "Adam"},
        {"match_id": "fight5", "round": 2, "winner": "Betta"},
        {"match_id": "fight5", "round": 3, "winner": "Caio"},
        {
            "match_id": "challenge6",
            "round": 1,
            "winner": "Donna",
            "m_vector": [0.9, -0.1, -0.3],
        },
        {"match_id": "challenge6", "round": 2, "winner": "Erick"},
        {"match_id": "challenge6", "round": 3, "winner": "Fiona"},
        {"match_id": "tournamentA", "round": 1, "winner": "Gael"},
        {"match_id": "tournamentA", "round": 2, "winner": "Hanna"},
        {
            "match_id": "tournamentA",
            "round": 3,
            "winner": "Ian",
            "fighters": DataAPISet([
                UUID("0193539a-2770-8c09-a32a-111111111111"),
            ]),
        },
        {"match_id": "fight7", "round": 1, "winner": "Joy"},
        {"match_id": "fight7", "round": 2, "winner": "Kevin"},
        {"match_id": "fight7", "round": 3, "winner": "Lauretta"},
    ],
    concurrency=10,
    chunk_size=3,
)

The previous example has a very low chunk_size for demonstration purposes. For best performance, DataStax recommends using the default chunk_size.

Perform an ordered insertion:

my_table.insert_many(
    [
        {"match_id": "fight5", "round": 1, "winner": "Adam0"},
        {"match_id": "fight5", "round": 2, "winner": "Betta0"},
        {"match_id": "fight5", "round": 3, "winner": "Caio0"},
        {"match_id": "fight5", "round": 1, "winner": "Adam Zuul"},
        {"match_id": "fight5", "round": 2, "winner": "Betta Vigo"},
        {"match_id": "fight5", "round": 3, "winner": "Caio Gozer"},
    ],
    ordered=True,
)

Full example script

from astrapy import DataAPIClient
client = DataAPIClient("TOKEN")
database = client.get_database("API_ENDPOINT")

from astrapy.constants import SortMode
from astrapy.info import (
    CreateTableDefinition,
    ColumnType,
)

my_table = database.create_table(
    "games",
    definition=(
        CreateTableDefinition.builder()
        .add_column("match_id", ColumnType.TEXT)
        .add_column("round", ColumnType.TINYINT)
        .add_vector_column("m_vector", dimension=3)
        .add_column("score", ColumnType.INT)
        .add_column("when", ColumnType.TIMESTAMP)
        .add_column("winner", ColumnType.TEXT)
        .add_set_column("fighters", ColumnType.UUID)
        .add_partition_by(["match_id"])
        .add_partition_sort({"round": SortMode.ASCENDING})
        .build()
    ),
)

# Insert complete and partial rows at once (concurrently)
from astrapy.data_types import (
    DataAPISet,
    DataAPITimestamp,
    DataAPIVector,
)
from astrapy.ids import UUID

insert_result = my_table.insert_many(
    [
        {
            "match_id": "fight4",
            "round": 1,
            "winner": "Victor",
            "score": 18,
            "when": DataAPITimestamp.from_string(
                "2024-11-28T11:30:00Z",
            ),
            "fighters": DataAPISet([
                UUID("0193539a-2770-8c09-a32a-111111111111"),
                UUID('019353e3-00b4-83f9-a127-222222222222'),
            ]),
            "m_vector": DataAPIVector([0.4, -0.6, 0.2]),
        },
        {"match_id": "fight5", "round": 1, "winner": "Adam"},
        {"match_id": "fight5", "round": 2, "winner": "Betta"},
        {"match_id": "fight5", "round": 3, "winner": "Caio"},
        {
            "match_id": "challenge6",
            "round": 1,
            "winner": "Donna",
            "m_vector": [0.9, -0.1, -0.3],
        },
        {"match_id": "challenge6", "round": 2, "winner": "Erick"},
        {"match_id": "challenge6", "round": 3, "winner": "Fiona"},
        {"match_id": "tournamentA", "round": 1, "winner": "Gael"},
        {"match_id": "tournamentA", "round": 2, "winner": "Hanna"},
        {
            "match_id": "tournamentA",
            "round": 3,
            "winner": "Ian",
            "fighters": DataAPISet([
                UUID("0193539a-2770-8c09-a32a-111111111111"),
            ]),
        },
        {"match_id": "fight7", "round": 1, "winner": "Joy"},
        {"match_id": "fight7", "round": 2, "winner": "Kevin"},
        {"match_id": "fight7", "round": 3, "winner": "Lauretta"},
    ],
    concurrency=10,
    chunk_size=3,
)
insert_result.inserted_ids
# [{'match_id': 'fight4', 'round': 1}, {'match_id': 'fight5', ...
insert_result.inserted_id_tuples
# [('fight4', 1), ('fight5', 1), ('fight5', 2), ('fight5', 3), ...

# Ordered insertion
# (would stop on first failure; predictable end result on the database)
my_table.insert_many(
    [
        {"match_id": "fight5", "round": 1, "winner": "Adam0"},
        {"match_id": "fight5", "round": 2, "winner": "Betta0"},
        {"match_id": "fight5", "round": 3, "winner": "Caio0"},
        {"match_id": "fight5", "round": 1, "winner": "Adam Zuul"},
        {"match_id": "fight5", "round": 2, "winner": "Betta Vigo"},
        {"match_id": "fight5", "round": 3, "winner": "Caio Gozer"},
    ],
    ordered=True,
)
# TableInsertManyResult(inserted_ids=[{'match_id': 'fight5', 'round': 1}, ...

Example:

# Insert complete and partial rows at once (concurrently)
from astrapy.data_types import (
    DataAPISet,
    DataAPITimestamp,
    DataAPIVector,
)
from astrapy.ids import UUID

insert_result = my_table.insert_many(
    [
        {
            "match_id": "fight4",
            "round": 1,
            "winner": "Victor",
            "score": 18,
            "when": DataAPITimestamp.from_string(
                "2024-11-28T11:30:00Z",
            ),
            "fighters": DataAPISet([
                UUID("0193539a-2770-8c09-a32a-111111111111"),
                UUID('019353e3-00b4-83f9-a127-222222222222'),
            ]),
            "m_vector": DataAPIVector([0.4, -0.6, 0.2]),
        },
        {"match_id": "fight5", "round": 1, "winner": "Adam"},
        {"match_id": "fight5", "round": 2, "winner": "Betta"},
        {"match_id": "fight5", "round": 3, "winner": "Caio"},
        {
            "match_id": "challenge6",
            "round": 1,
            "winner": "Donna",
            "m_vector": [0.9, -0.1, -0.3],
        },
        {"match_id": "challenge6", "round": 2, "winner": "Erick"},
        {"match_id": "challenge6", "round": 3, "winner": "Fiona"},
        {"match_id": "tournamentA", "round": 1, "winner": "Gael"},
        {"match_id": "tournamentA", "round": 2, "winner": "Hanna"},
        {
            "match_id": "tournamentA",
            "round": 3,
            "winner": "Ian",
            "fighters": DataAPISet([
                UUID("0193539a-2770-8c09-a32a-111111111111"),
            ]),
        },
        {"match_id": "fight7", "round": 1, "winner": "Joy"},
        {"match_id": "fight7", "round": 2, "winner": "Kevin"},
        {"match_id": "fight7", "round": 3, "winner": "Lauretta"},
    ],
    concurrency=10,
    chunk_size=3,
)
insert_result.inserted_ids
# [{'match_id': 'fight4', 'round': 1}, {'match_id': 'fight5', ...
insert_result.inserted_id_tuples
# [('fight4', 1), ('fight5', 1), ('fight5', 2), ('fight5', 3), ...

# Ordered insertion
# (would stop on first failure; predictable end result on the database)
my_table.insert_many(
    [
        {"match_id": "fight5", "round": 1, "winner": "Adam0"},
        {"match_id": "fight5", "round": 2, "winner": "Betta0"},
        {"match_id": "fight5", "round": 3, "winner": "Caio0"},
        {"match_id": "fight5", "round": 1, "winner": "Adam Zuul"},
        {"match_id": "fight5", "round": 2, "winner": "Betta Vigo"},
        {"match_id": "fight5", "round": 3, "winner": "Caio Gozer"},
    ],
    ordered=True,
)
# TableInsertManyResult(inserted_ids=[{'match_id': 'fight5', 'round': 1}, ...

Basic unordered insert:

const docs = Array.from({ length: 50 }, (_, i) => ({ matchId: `match${i}`, round: 0 }));
await table.insertMany(docs);

Basic ordered insert:

const docs = Array.from({ length: 50 }, (_, i) => ({ matchId: `match${i}`, round: 0 }));
await table.insertMany(docs, { ordered: true });

Example:

Full script

import { CreateTableDefinition, DataAPIClient, InferTablePrimaryKey, InferTableSchema, timestamp, uuid, vector } from '@datastax/astra-db-ts';

// Instantiate the client and connect to the database
const client = new DataAPIClient();
const db = client.db(process.env.CLIENT_DB_URL!, { token: process.env.CLIENT_DB_TOKEN! });

// Create table schema using bespoke Data API table definition syntax, and then infer the type.
// For information about table typing and definitions, see the documentation for createTable.
const TableDefinition = <const>{
  columns: {
    matchId: 'text'
    round: 'tinyint',
    mVector: { type: 'vector', dimension: 3 },
    score: 'int',
    when: 'timestamp',
    winner: 'text',
    fighters: { type: 'set', valueType: 'uuid' },
  },
  primaryKey: {
    partitionBy: ['matchId'],
    partitionSort: { round: 1 },
  },
} satisfies CreateTableDefinition;

type TableSchema = InferTableSchema<typeof TableDefinition>;
type TablePK = InferTablePrimaryKey<typeof TableDefinition>;

(async function () {
  // Create a table with the given TableSchema type if a 'games' table doesn't already exist
  const table = await db.createTable<TableSchema, TablePK>('games', { definition: TableDefinition, ifNotExists: true });

// Use insertOne and insertMany to insert rows into tables.
// Inserts are also upserts for tables.

// insertOne examples

  // Inserts a single row
  const res = await table.insertOne({
      matchId: 'match_0',
      round: 1,                                       // All non-varint/decimal numbers are represented as JS numbers
      score: 18,
      when: timestamp(),                              // Shorthand for `new DataAPITimestamp(new Date())`
      winner: 'Victor',
      fighters: new Set([                             // Use native Maps, Sets, and Arrays for maps, sets, and lists.
        uuid('a4e4e5b0-1f3b-4b4d-8e1b-4e6b3f1f3b4d'), // You can nest datatypes in maps, sets, and lists.
        uuid(4),                                      // Shorthand for `UUID.v4()`
      ]),
      mVector: vector([0.2, -0.3, -0.5]),             // Shorthand for `new DataAPIVector([0.2, -0.3, -0.5])`
    });                                               // Use this instead of plain arrays to enable vector-specific optimizations

  // Returns primary key of type { id: string, time: DataAPITimestamp }
  const primaryKey = res.insertedId;
  console.log(primaryKey.matchId);

  // Inserts are also upserts in tables.
  // If the winner of round 1 was actually 'Cham P. Yun' instead of 'Victor',
  // you can use insertOne to modify the row identified by its primary key.
  await table.insertOne({
    matchId: 'match_0',
    round: 1,
    score: null,                // Set `score` to `null` to clear the previously inserted value
    winner: 'Cham P. Yun',
    mVector: [-0.6, 0.2, -0.7],
    });

  // The upserted row now has the following values:
  // { matchId: 'match_0', round: 1, score: null, when: <timestamp>, winner: 'Cham P. Yun', fighters: <uuid[]>, mVector: [-0.6, 0.2, -0.7] }

// insertMany examples

  // Inserts two rows in an unordered fashion.
  // Primary keys are required.
  // Unspecified columns are set to null.
  await table.insertMany([{
    matchId: 'fight4',
    round: 1,
    winner: 'Victor',
    score: 18,
    when: timestamp('2024-11-28T11:30:00Z'),
    fighters: new Set([
      uuid('0193539a-2770-8c09-a32a-111111111111'),
      uuid('019353e3-00b4-83f9-a127-222222222222'),
    ]),
    mVector: vector([0.4, -0.6, 0.2]),
    },
  // Insert with the primary key and 2 other values.
    {
    matchId: 'challenge6',
    round: 2,
    winner: 'Wynn Uhr',
    },
  ]);

  // Performs two inserts against the same row in an ordered fashion ('ordered: true').
  // Because inserts are also upserts in tables, if an ordered insert modifies the same row multiple times,
  // subsequent inserts overwrite prior inserts if the inserts modify the same columns.
  // In this example, the second insert overwrites the `winner` and `mVector` values from the first insert.
  //
  // In unordered inserts, upserts still occur, but the order is not guaranteed and the outcome is unpredictable.
  // However, unordered inserts are parallelized on the client and server.
  // They are generally more performant and recommended for most use cases.
  const res = await table.insertMany([
    {
      matchId: 'match_0',
      round: 1,                                       // All numbers are represented as JS numbers except varint and decimal
      score: 18,
      when: timestamp(),                              // Shorthand for `new DataAPITimestamp(new Date())`
      winner: 'Victor',
      fighters: new Set([                             // Use native Maps, Sets, and Arrays for maps, sets, and lists.
        uuid('a4e4e5b0-1f3b-4b4d-8e1b-4e6b3f1f3b4d'), // You can nest datatypes in maps, sets, and lists.
        uuid(7),                                      // Shorthand for `UUID.v7()`
      ]),
      mVector: vector([0.2, -0.3, -0.5]),             // Shorthand for `new DataAPIVector([0.2, -0.3, -0.5])`
    },                                                // Use this instead of plain arrays to enable vector-specific optimizations
    {
      matchId: 'match_0',
      round: 1,
      score: null,                                   // Set `score` to `null` to insert no value or clear a previously-inserted value
      winner: 'Cham P. Yun',
      mVector: [-0.6, 0.2, -0.7],
    }],
    {
      timeout: 60000,
      ordered: true,
    });

  // Returns primary key of type { matchId: string, round: number }[]
  // Because both inserts have the same matchId, the primary key is 'match_0' for both
  const primaryKey = res.insertedIds;
  console.log(primaryKey[0].matchId, primaryKey[1].matchId);

  // After both inserts, the row has the following values:
  // { matchId: 'match_0', round: 1, score: null, when: <timestamp>, winner: 'Cham P. Yun', fighters: <uuid[]>, mVector: [-0.6, 0.2, -0.7] }

  const docs: TableSchema[] = Array.from({ length: 101 }, (\_, i) => ({
    matchId: \`match_${i}`,
    round: 1,
  }));
  await table.insertMany(docs);

  // Uncomment the following line to drop the table and any related indexes.
  // await table.drop();
})();

// Inserts two rows in an unordered fashion.
// Primary keys are required.
// Unspecified columns are set to null.
await table.insertMany([{
  matchId: 'fight4',
  round: 1,
  winner: 'Victor',
  score: 18,
  when: timestamp('2024-11-28T11:30:00Z'),
  fighters: new Set([
    uuid('0193539a-2770-8c09-a32a-111111111111'),
    uuid('019353e3-00b4-83f9-a127-222222222222'),
  ]),
  mVector: vector([0.4, -0.6, 0.2]),
  },
// Insert with the primary key and 2 other values.
  {
  matchId: 'challenge6',
  round: 2,
  winner: 'Wynn Uhr',
  },
]);

// Performs two inserts against the same row in an ordered fashion ('ordered: true').
// Because inserts are also upserts in tables, if an ordered insert modifies the same row multiple times,
// subsequent inserts overwrite prior inserts if the inserts modify the same columns.
// In this example, the second insert overwrites the `winner` and `mVector` values from the first insert.
//
// In unordered inserts, upserts still occur, but the order is not guaranteed and the outcome is unpredictable.
// However, unordered inserts are parallelized on the client and server.
// They are generally more performant and recommended for most use cases.
const res = await table.insertMany([
  {
    matchId: 'match_0',
    round: 1,                                       // All numbers are represented as JS numbers except varint and decimal
    score: 18,
    when: timestamp(),                              // Shorthand for `new DataAPITimestamp(new Date())`
    winner: 'Victor',
    fighters: new Set([                             // Use native Maps, Sets, and Arrays for maps, sets, and lists.
      uuid('a4e4e5b0-1f3b-4b4d-8e1b-4e6b3f1f3b4d'), // You can nest datatypes in maps, sets, and lists.
      uuid(7),                                      // Shorthand for `UUID.v7()`
    ]),
    mVector: vector([0.2, -0.3, -0.5]),             // Shorthand for `new DataAPIVector([0.2, -0.3, -0.5])`
  },                                                // Use this instead of plain arrays to enable vector-specific optimizations
  {
    matchId: 'match_0',
    round: 1,
    score: null,                                   // Set `score` to `null` to insert no value or clear a previously-inserted value
    winner: 'Cham P. Yun',
    mVector: [-0.6, 0.2, -0.7],
  }],
  {
    timeout: 60000,
    ordered: true,
  });

// Returns primary key of type { matchId: string, round: number }[]
// Because both inserts have the same matchId, the primary key is 'match_0' for both
const primaryKey = res.insertedIds;
console.log(primaryKey[0].matchId, primaryKey[1].matchId);

// After both inserts, the row has the following values:
// { matchId: 'match_0', round: 1, score: null, when: <timestamp>, winner: 'Cham P. Yun', fighters: <uuid[]>, mVector: [-0.6, 0.2, -0.7] }

const docs: TableSchema[] = Array.from({ length: 101 }, (\_, i) => ({
  matchId: \`match_${i}`,
  round: 1,
}));
await table.insertMany(docs);

Insert many rows concurrently:

Table<Row> table = db.getTable("games");

TableInsertManyOptions options = new TableInsertManyOptions()
  .concurrency(10)
  .ordered(false)
  .chunkSize(3);

List<Row> myRows = new ArrayList<>();
myRows.add(new Row().addText("match_id", "fight4")
  .addInt("round", 1)
  .addText("winner", "Victor")
  .addInt("score", 18)
  .addTimeStamp("when", Instant.now())
  .addSet("fighters", Set.of(
    UUID.fromString("0193539a-2770-8c09-a32a-111111111111"),
    UUID.fromString("019353e3-00b4-83f9-a127-222222222222")
    )
   )
  .addVector("m_vector", new DataAPIVector(new float[]{0.4f, -0.6f, 0.2f})));
myRows.add(new Row().addText("match_id", "fight5").addInt("round", 1).addText("winner", "Adam"));
myRows.add(new Row().addText("match_id", "fight5").addInt("round", 2).addText("winner", "Betta"));
myRows.add(new Row().addText("match_id", "fight5").addInt("round", 3).addText("winner", "Caio"));
myRows.add(new Row().addText("match_id", "challenge6").addInt("round", 1).addText("winner", "Donna")
 .addVector("m_vector", new DataAPIVector(new float[]{0.9f, -0.1f, -0.3f})));
myRows.add(new Row().addText("match_id", "challenge6").addInt("round", 2).addText("winner", "Erick"));
myRows.add(new Row().addText("match_id", "challenge6").addInt("round", 3).addText("winner", "Fiona"));
myRows.add(new Row().addText("match_id", "tournamentA").addInt("round", 1).addText("winner", "Gael"));
myRows.add(new Row().addText("match_id", "tournamentA").addInt("round", 2).addText("winner", "Hanna"));
myRows.add(new Row().addText("match_id", "tournamentA").addInt("round", 3).addText("winner", "Ian")
 .addSet("fighters", Set.of(UUID.fromString("0193539a-2770-8c09-a32a-111111111111"))));
myRows.add(new Row().addText("match_id", "fight7").addInt("round", 1).addText("winner", "Joy"));
myRows.add(new Row().addText("match_id", "fight7").addInt("round", 2).addText("winner", "Kevin"));
myRows.add(new Row().addText("match_id", "fight7").addInt("round", 3).addText("winner", "Lauretta"));
TableInsertManyResult insertResults = table
  .insertMany(myRows, options);

The previous example has a very low chunk_size for demonstration purposes. For best performance, DataStax recommends using the default chunk_size.

Perform an ordered insertion:

TableInsertManyResult results2 = table.insertMany(
 List.of(
  new Row().addText("match_id", "fight5").addInt("round", 1).addText("winner", "Adam0"),
  new Row().addText("match_id", "fight5").addInt("round", 2).addText("winner", "Betta0"),
  new Row().addText("match_id", "fight5").addInt("round", 3).addText("winner", "Caio0"),
  new Row().addText("match_id", "fight5").addInt("round", 1).addText("winner", "Adam Zuul"),
  new Row().addText("match_id", "fight5").addInt("round", 2).addText("winner", "Betta Vigo"),
  new Row().addText("match_id", "fight5").addInt("round", 3).addText("winner", "Caio Gozer")
 ),
 new TableInsertManyOptions()
  .ordered(true));

Example:

package com.datastax.astra.client.tables;

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.DataAPIDestination;
import com.datastax.astra.client.core.auth.UsernamePasswordTokenProvider;
import com.datastax.astra.client.core.options.DataAPIClientOptions;
import com.datastax.astra.client.core.vector.DataAPIVector;
import com.datastax.astra.client.databases.Database;
import com.datastax.astra.client.databases.DatabaseOptions;
import com.datastax.astra.client.tables.commands.options.TableInsertManyOptions;
import com.datastax.astra.client.tables.commands.results.TableInsertManyResult;
import com.datastax.astra.client.tables.commands.results.TableInsertOneResult;
import com.datastax.astra.client.tables.definition.columns.ColumnDefinition;
import com.datastax.astra.client.tables.definition.rows.Row;

import java.time.Instant;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.UUID;

public class InsertManyRows {
  public static void main(String[] args) {
   Database db = new DataAPIClient("token").getDatabase("endpoint");

   Table<Row> table = db.getTable("games");

   TableInsertManyOptions options = new TableInsertManyOptions()
     .concurrency(10)
     .ordered(false)
     .chunkSize(3);

   List<Row> myRows = new ArrayList<>();
   myRows.add(new Row().addText("match_id", "fight4")
    .addInt("round", 1)
    .addText("winner", "Victor")
    .addInt("score", 18)
    .addTimeStamp("when", Instant.now())
    .addSet("fighters", Set.of(
     UUID.fromString("0193539a-2770-8c09-a32a-111111111111"),
     UUID.fromString("019353e3-00b4-83f9-a127-222222222222")))
    .addVector("m_vector",
        new DataAPIVector(new float[]{0.4f, -0.6f, 0.2f})));

  myRows.add(new Row()
   .addText("match_id", "fight5")
   .addInt("round", 1)
   .addText("winner", "Adam"));
  myRows.add(new Row()
   .addText("match_id", "fight5")
   .addInt("round", 2)
   .addText("winner", "Betta"));
  myRows.add(new Row().addText("match_id", "fight5").addInt("round", 3).addText("winner", "Caio"));
  myRows.add(new Row().addText("match_id", "challenge6").addInt("round", 1).addText("winner", "Donna")
              .addVector("m_vector", new DataAPIVector(new float[]{0.9f, -0.1f, -0.3f})));
      myRows.add(new Row().addText("match_id", "challenge6").addInt("round", 2).addText("winner", "Erick"));
      myRows.add(new Row().addText("match_id", "challenge6").addInt("round", 3).addText("winner", "Fiona"));
      myRows.add(new Row().addText("match_id", "tournamentA").addInt("round", 1).addText("winner", "Gael"));
      myRows.add(new Row().addText("match_id", "tournamentA").addInt("round", 2).addText("winner", "Hanna"));
      myRows.add(new Row().addText("match_id", "tournamentA").addInt("round", 3).addText("winner", "Ian")
              .addSet("fighters", Set.of(UUID.fromString("0193539a-2770-8c09-a32a-111111111111"))));
      myRows.add(new Row().addText("match_id", "fight7").addInt("round", 1).addText("winner", "Joy"));
      myRows.add(new Row().addText("match_id", "fight7").addInt("round", 2).addText("winner", "Kevin"));
      myRows.add(new Row().addText("match_id", "fight7").addInt("round", 3).addText("winner", "Lauretta"));
   TableInsertManyResult results = table.insertMany(myRows, options);

   TableInsertManyResult results2 = table.insertMany(
     List.of(
       new Row().addText("match_id", "fight5").addInt("round", 1).addText("winner", "Adam0"),
       new Row().addText("match_id", "fight5").addInt("round", 2).addText("winner", "Betta0"),
       new Row().addText("match_id", "fight5").addInt("round", 3).addText("winner", "Caio0"),
       new Row().addText("match_id", "fight5").addInt("round", 1).addText("winner", "Adam Zuul"),
       new Row().addText("match_id", "fight5").addInt("round", 2).addText("winner", "Betta Vigo"),
       new Row().addText("match_id", "fight5").addInt("round", 3).addText("winner", "Caio Gozer")),
   new TableInsertManyOptions().ordered(true));
  }
}

To insert multiple rows, provide a documents array containing an object for each row that you want to insert. Each row object contains key-value pairs of column names and values to insert. Primary key values are required. Any unspecified columns are set to null.

The following example inserts rows with scalar, map, list, and set data. The format of the values for each column depend on the column’s data type.

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 '{
  "insertMany": {
    "documents": [
      {
        "string_key": "value1",
        "int_key": 2,
        "boolean_key": true,
        "float_column": -3.47
        "map_column": {
          "key1": "value1",
          "key2": "value2"
        },
      },
      {
        "string_key": "value2",
        "int_key": 7,
        "boolean_key": false,
        "list_column": [ 10, 11, 12 ],
      },
      {
        "string_key": "value3",
        "int_key": 9,
        "boolean_key": false,
        "set_column": [ 9, 8, 7 ]
      }
    ]
    "options": {
      "ordered": false,
      "returnDocumentPositions": true
    }
  }
}' | jq

You can insert pre-generated vector data into a vector column as an array or as a binary encoded value. Alternatively, if the column has a vectorize integration, you can automatically generate an embedding from a string.

# Insert vector data as an array
"vector_column": [ 0.1, -0.2, 0.3 ]

# Insert vector data with $binary
"vector_column": { "$binary": "PczMzb5MzM0+mZma" }

# Generate an embedding with vectorize
"vector_column": "Text to vectorize"

For more information, see Vector type.

Example:

curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/default_keyspace/students" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "insertMany": {
    "documents": [
      {
        "name": "Tal Noor",
        "email": "tal@example.com",
        "graduated": true,
        "graduation_year": 2014,
        "grades": {
          "bio_101": 98,
          "math_202": 91
        },
        "extracurriculars": [ "Robotics club", "Cycling team" ],
        "semester_gpas": [ 3.9, 4.0, 3.7, 3.8 ]
      },
      {
        "name": "Sami Minh",
        "email": "sami@example.com",
        "graduated": true,
        "graduation_year": 2024,
        "grades": {
          "econ_101": 98,
          "econ_202": 91
        },
        "extracurriculars": [ "Debate team", "IM soccer" ],
        "semester_gpas": [ 3.6, 3.2, 3.7, 3.9 ]
      },
      {
        "name": "Kiran Jay",
        "email": "kiran@example.com",
        "graduated": true,
        "graduation_year": 2024,
        "grades": {
          "draw_101": 98,
          "pottery_301": 91
        },
        "extracurriculars": [ "RA", "Gardening club" ],
        "semester_gpas": [ 3.4, 3.6, 3.8, 3.7 ]
      }
    ]
  }
}' | jq

Client reference

Python
TypeScript
Java
curl

For more information, see the client reference.

Client reference documentation is not applicable for HTTP.

Insert rows

Method signature

Result

Parameters

Examples

Client reference

Was this helpful?

Give Feedback