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.
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: Schema[],
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,
"returnDocumentResponses": 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<Schema>
.
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 bystatus.primaryKeySchema
.Omitted if the
options.returnDocumentResponses
parameter istrue
. -
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.returnDocumentResponses
parameter istrue
.
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
]
]
}
}
Example response when options.returnDocumentResponses
is true:
{
"status": {
"primaryKeySchema": {
"email": {
"type": "ascii"
}
},
"documentResponses": [
{"_id":["tal@example.com"], "status":"OK"},
{"_id":["sami@example.com"], "status":"OK"},
{"_id":["kirin@example.com"], "status":"OK"}
]
}
}
Parameters
-
Python
-
TypeScript
-
Java
-
curl
Name | Type | Summary |
---|---|---|
|
|
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 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. |
|
|
If |
|
|
The maximum number of concurrent requests to the API at a given time. It cannot be more than one for ordered insertions. |
|
|
The number of rows to insert in a single API request. Leave it unspecified (recommended) to use the system default. |
|
|
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 |
|
|
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 |
---|---|---|
|
|
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 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. |
|
|
The options for this operation. |
Options (TableInsertManyOptions
):
Name | Type | Summary |
---|---|---|
|
|
If |
|
|
The maximum number of concurrent requests to the API at a given time. Defaults to This is not available for ordered insertions. |
|
|
The number of rows to insert in a single API request. Leave it unspecified (recommended) to use the system default. |
|
|
The client-side timeout for this operation. |
Name | Type | Summary |
---|---|---|
|
|
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 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. |
|
Configuration and specialization of the Options |
Name | Type | Summary |
---|---|---|
|
|
If |
|
|
The maximum number of concurrent requests to the API at a given time. It cannot be more than one for ordered insertions. |
|
|
The number of rows to insert in a single API request. Leave it unspecified (recommended) to use the system default. |
Name | Type | Summary |
---|---|---|
|
|
Data API command to insert multiples row in a table. |
|
|
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 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 for the command, including |
|
|
If |
|
|
If true, the response includes a |
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
-
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 rows into the table
result = table.insert_many(
[
{
"title": "Computed Wilderness",
"author": "Ryan Eau",
"numberOfPages": 432,
"dueDate": DataAPIDate.from_string("2024-12-18"),
"genres": DataAPISet(["History", "Biography"])
},
{
"title": "Desert Peace",
"author": "Walter Dray",
"numberOfPages": 355,
"rating": 4.5
},
]
)
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 rows into the table
(async function () {
const result = await table.insertMany([
{
title: "Computed Wilderness",
author: "Ryan Eau",
numberOfPages: 432,
dueDate: date("2024-12-18"),
genres: new Set(["History", "Biography"]),
},
{
title: "Desert Peace",
author: "Walter Dray",
numberOfPages: 355,
rating: 4.5,
}
]);
})();
package com.example;
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.commands.results.TableInsertManyResult;
import com.datastax.astra.client.tables.definition.rows.Row;
import java.util.Calendar;
import java.util.Date;
import java.util.List;
import java.util.Set;
public class InsertMany {
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 rows into the table
Calendar calendar = Calendar.getInstance();
calendar.set(2024, Calendar.DECEMBER, 18);
Date date = calendar.getTime();
Row row1 =
new Row()
.addText("title", "Computed Wilderness")
.addText("author", "Ryan Eau")
.addInt("numberOfPages", 432)
.addDate("dueDate", date)
.addSet("genres", Set.of("History", "Biography"));
Row row2 =
new Row()
.addText("title", "Desert Peace")
.addText("author", "Walter Dray")
.addInt("numberOfPages", 355)
.addFloat("rating", 4.5f);
TableInsertManyResult result = table.insertMany(List.of(row1, row2));
System.out.println(result.getInsertedIds());
}
}
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": [
{
"title": "Computed Wilderness",
"author" :"Ryan Eau",
"numberOfPages": 432,
"dueDate": "2024-12-18",
"genres": ["History", "Biography"]
},
{
"title": "Desert Peace",
"author" :"Walter Dray",
"numberOfPages": 355,
"rating": 3.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.
-
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 rows into the table
result = table.insert_many(
[
{
"title": "Computed Wilderness",
"author": "Ryan Eau",
"summaryGenresVector": DataAPIVector([0.4, -0.6, 0.2]),
},
{
"title": "Desert Peace",
"author": "Walter Dray",
"summaryGenresVector": DataAPIVector([0.3, 0.6, 0.5]),
}
]
)
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 rows into the table
(async function () {
const result = await table.insertMany([
{
title: "Computed Wilderness",
author: "Ryan Eau",
summaryGenresVector: new DataAPIVector([0.4, -0.6, 0.2]),
},
{
title: "Desert Peace",
author: "Walter Dray",
summaryGenresVector: new DataAPIVector([0.3, 0.6, 0.5]),
},
]);
})();
package com.example;
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.commands.results.TableInsertManyResult;
import com.datastax.astra.client.tables.definition.rows.Row;
import com.datastax.astra.client.core.vector.DataAPIVector;
import java.util.List;
public class InsertMany {
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 rows into the table
Row row1 =
new Row()
.addText("title", "Computed Wilderness")
.addText("author", "Ryan Eau")
.addVector("summaryGenresVector", new DataAPIVector(new float[]{0.4f, -0.6f, 0.2f}));
Row row2 =
new Row()
.addText("title", "Desert Peace")
.addText("author", "Walter Dray")
.addVector("summaryGenresVector", new DataAPIVector(new float[]{0.3f, 0.6f, 0.5f}));
TableInsertManyResult result = table.insertMany(List.of(row1, row2));
System.out.println(result.getInsertedIds());
}
}
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 '{
"insertMany": {
"documents": [
{
"title": "Computed Wilderness",
"author" :"Ryan Eau",
"summaryGenresVector": [.12, .52, .32]
},
{
"title": "Desert Peace",
"author" :"Walter Dray",
"summaryGenresVector": [0.3, 0.6, 0.5]
}
]
}
}'
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": [
{
"title": "Computed Wilderness",
"author" :"Ryan Eau",
"summaryGenresVector": {"$binary": "PfXCjz8FHrg+o9cK"}
},
{
"title": "Desert Peace",
"author" :"Walter Dray",
"summaryGenresVector": {"$binary": "PpmZmj8ZmZo/AAAA"}
}
]
}
}'
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, 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 rows into the table
result = table.insert_many(
[
{
"title": "Computed Wilderness",
"author": "Ryan Eau",
"summaryGenresVector": "Text to vectorize",
"summaryGenresOriginalText": "Text to vectorize",
},
{
"title": "Desert Peace",
"author": "Walter Dray",
"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 rows into the table
(async function () {
const result = await table.insertMany([
{
title: "Computed Wilderness",
author: "Ryan Eau",
summaryGenresVector: "Text to vectorize",
summaryGenresOriginalText: "Text to vectorize",
},
{
title: "Desert Peace",
author: "Walter Dray",
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.TableInsertManyResult;
import com.datastax.astra.client.tables.definition.rows.Row;
import java.util.List;
public class InsertMany {
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 rows into the table
Row row1 =
new Row()
.addText("title", "Computed Wilderness")
.addText("author", "Ryan Eau")
.addVectorize("summaryGenresVector", "Text to vectorize")
.addText("summaryGenresOriginalText", "Text to vectorize");
Row row2 =
new Row()
.addText("title", "Desert Peace")
.addText("author", "Walter Dray")
.addVectorize("summaryGenresVector", "Text to vectorize")
.addText("summaryGenresOriginalText", "Text to vectorize");
TableInsertManyResult result = table.insertMany(List.of(row1, row2));
System.out.println(result.getInsertedIds());
}
}
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": [
{
"title": "Computed Wilderness",
"author" :"Ryan Eau",
"summaryGenresVector": "Text to vectorize",
"summaryGenresOriginalText": "Text to vectorize"
},
{
"title": "Desert Peace",
"author" :"Walter Dray",
"summaryGenresVector": "Text to vectorize",
"summaryGenresOriginalText": "Text to vectorize"
}
]
}
}'
Insert rows and specify insertion behavior
-
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 rows into the table
result = table.insert_many(
[
{
"title": "Computed Wilderness",
"author": "Ryan Eau",
"numberOfPages": 432,
"dueDate": DataAPIDate.from_string("2024-12-18"),
"genres": DataAPISet(["History", "Biography"])
},
{
"title": "Desert Peace",
"author": "Walter Dray",
"numberOfPages": 355,
"rating": 4.5
},
],
chunk_size=2,
concurrency=2,
ordered=False,
)
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 rows into the table
(async function () {
const result = await table.insertMany(
[
{
title: "Computed Wilderness",
author: "Ryan Eau",
numberOfPages: 432,
dueDate: date("2024-12-18"),
genres: new Set(["History", "Biography"]),
},
{
title: "Desert Peace",
author: "Walter Dray",
numberOfPages: 355,
rating: 4.5,
}
],
{
chunkSize: 2,
concurrency: 2,
ordered: false,
}
);
})();
package com.example;
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.commands.results.TableInsertManyResult;
import com.datastax.astra.client.tables.commands.options.TableInsertManyOptions;
import com.datastax.astra.client.tables.definition.rows.Row;
import java.util.Calendar;
import java.util.Date;
import java.util.List;
import java.util.Set;
public class InsertMany {
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");
// Define the insertion options
TableInsertManyOptions options = new TableInsertManyOptions()
.chunkSize(20)
.concurrency(3)
.ordered(false);
// Insert rows into the table
Calendar calendar = Calendar.getInstance();
calendar.set(2024, Calendar.DECEMBER, 18);
Date date = calendar.getTime();
Row row1 =
new Row()
.addText("title", "Computed Wilderness")
.addText("author", "Ryan Eau")
.addInt("numberOfPages", 432)
.addDate("dueDate", date)
.addSet("genres", Set.of("History", "Biography"));
Row row2 =
new Row()
.addText("title", "Desert Peace")
.addText("author", "Walter Dray")
.addInt("numberOfPages", 355)
.addFloat("rating", 4.5f);
TableInsertManyResult result = table.insertMany(List.of(row1, row2), options);
System.out.println(result.getInsertedIds());
}
}
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": [
{
"title": "Computed Wilderness",
"author" :"Ryan Eau",
"numberOfPages": 432,
"dueDate": "2024-12-18",
"genres": ["History", "Biography"]
},
{
"title": "Desert Peace",
"author" :"Walter Dray",
"numberOfPages": 355,
"rating": 3.5
}
],
"options": {
"ordered": false,
"returnDocumentResponses": true
}
}
}'
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.