Insert documents

Inserts multiple documents into a collection.

Documents are stored in collections. They represent a single row or record of data in Astra DB Serverless databases. For more information, see Work with collections and Work with documents.

If the collection is vector-enabled, pregenerated vector embeddings can be included by using the reserved $vector field for each document. If the collection has vectorize enabled, vector embeddings can be automatically generated from text specified in the reserved $vectorize field for each document.

Method signature

  • Python

  • TypeScript

  • Java

  • curl

collection.insert_many(
    documents: Iterable[Dict[str, Any]],
    *,
    ordered: bool,
    chunk_size: int,
    concurrency: int
    max_time_ms: int,
) -> InsertManyResult
collection.insertMany(
  documents: MaybeId<Schema>[],
  options?: {
    ordered?: boolean,
    concurrency?: number,
    chunkSize?: number,
    maxTimeMS?: number,
  },
): Promise<InsertManyResult<Schema>>
InsertManyResult collection.insertMany(
    List<? extends T> documents
)
InsertManyResult collection.insertMany(
    List<? extends T> documents,
    InsertManyOptions options
)
curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/COLLECTION_NAME" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "insertMany": {
    "documents": DOCUMENTS_JSON_ARRAY,
    "options": {
      "ordered": BOOLEAN,
    }
  }
}'

Result

  • Python

  • TypeScript

  • Java

  • curl

Inserts the specified documents and returns an InsertManyResult object that includes the IDs of the inserted documents and details about the success of the operation.

The ID value depends on the ID type. For more information, see Document IDs.

Example response:

InsertManyResult(inserted_ids=[
    "3f557bef-fd53-47ea-957b-effd53c7eaec",
    101,
    "132ffr343"
], raw_results=...)

Inserts the specified documents and returns a promise that resolves to an InsertManyResult<Schema> object that includes the IDs of the inserted documents and the number of inserted documents.

The ID value depends on the ID type. For more information, see Document IDs.

Example response:

{
  insertedCount: 3,
  insertedIds: [
    '92b3c4f4-db44-4440-b4c4-f4db54e440b8',
    101,
    '132ffr343'
  ]
}

Inserts the specified documents and returns a wrapper (InsertManyResult) that includes the IDs of the inserted documents.

The ID value depends on the ID type. For more information, see Document IDs.

Inserts the specified documents and returns a JSON object that includes the IDs of the inserted documents.

The ID value depends on the ID type. For more information, see Document IDs.

Example response:

{
  "status": {
    "insertedIds": [
      "3f557bef-fd53-47ea-957b-effd53c7eaec",
      101,
      "132ffr343"
    ]
  }
}

Parameters

  • Python

  • TypeScript

  • Java

  • curl

Name Type Summary

documents

Iterable[Dict[str, Any]]

An iterable of dictionaries, with each dictionary describing a document to insert.

In addition to open-ended fields that you can specify for each document, you may also specify the following reserved fields:

  • _id: An optional unique identifier for the document. If _id is omitted, it is created automatically based on the ID type. For more information, see Document IDs.

  • $vector: An optional array of numbers representing a vector embedding. The $vector field is only supported for vector-enabled collections. For more information, see Vector and vectorize.

  • $vectorize: An optional string to generate vector embeddings from. The $vectorize field is only supported for collections that have vectorize enabled. For more information, see Vector and vectorize and Auto-generate embeddings with vectorize.

The document may not contain both a $vector and a $vectorize field.

ordered

bool

Optional. Whether the insertions must be processed sequentially. If False, the documents may be inserted in an arbitrary order and possibly concurrently. If you don’t need ordered inserts, DataStax recommends setting this parameter to False for faster performance.

Default: False

chunk_size

int

Optional. The number of documents to include in a single API request. DataStax recommends leaving this parameter unspecified to use the system default.

Maximum: 100

Default: 50

concurrency

int

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

If ordered is True, then concurrency must be 1 or unspecified.

Default: 20 if ordered is False. 1 if ordered is True.

max_time_ms

int

Optional. The maximum time, in milliseconds, that the client should wait for each underlying HTTP request.

Default: The default value for the collection. This default is 30 seconds unless you specified a different default when you initialized the Collection object.
Name Type Summary

documents

MaybeId<Schema>[]

An array of documents to insert.

In addition to open-ended fields that you can specify for each document, you may also specify the following reserved fields:

  • _id: An optional unique identifier for the document. If _id is omitted, it is created automatically based on the ID type. For more information, see Document IDs.

  • $vector: An optional array of numbers representing a vector embedding. The $vector field is only supported for vector-enabled collections. For more information, see Vector and vectorize.

  • $vectorize: An optional string to generate vector embeddings from. The $vectorize field is only supported for collections that have vectorize enabled. For more information, see Vector and vectorize and Auto-generate embeddings with vectorize.

The document may not contain both a $vector and a $vectorize field.

options

InsertManyOptions

Optional. The options for this operation. See the options table for more details.
Properties of options:
Name Type Summary

ordered

boolean

Optional. Whether the insertions must be processed sequentially. If False, the documents may be inserted in an arbitrary order and possibly concurrently. If you don’t need ordered inserts, DataStax recommends setting this parameter to False for faster performance.

concurrency

number

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

If ordered is true, then concurrency must be 1 or unspecified.

Default: 8 if ordered is false. 1 if ordered is true.

chunkSize

number

Optional. The number of documents to include in a single API request. DataStax recommends leaving this parameter unspecified to use the system default.

Maximum: 100

Default: 50

maxTimeMS

number

Optional. The maximum time, in milliseconds, that the client should wait for each underlying HTTP request.

Default: The default value for the collection. This default is 30 seconds unless you specified a different default when you initialized the Collection object.
Name Type Summary

documents

List<? extends T>

A list of objects describing the documents to insert.

In addition to open-ended fields that you can specify for each document, you may also specify the following reserved fields:

  • _id: An optional unique identifier for the document. If _id is omitted, it is created automatically based on the ID type. For more information, see Document IDs.

  • $vector: An optional array of numbers representing a vector embedding. The $vector field is only supported for vector-enabled collections. For more information, see Vector and vectorize.

  • $vectorize: An optional string to generate vector embeddings from. The $vectorize field is only supported for collections that have vectorize enabled. For more information, see Vector and vectorize and Auto-generate embeddings with vectorize.

The document may not contain both a $vector and a $vectorize field.

options

InsertManyOptions

Optional. The options for this operation. See the methods of the InsertManyOptions class for more details.
Methods of the InsertManyOptions class:
Name Type Summary

ordered()

boolean

Optional. Whether the insertions must be processed sequentially. If false, the documents may be inserted in an arbitrary order and possibly concurrently. If you don’t need ordered inserts, DataStax recommends setting this parameter to false for faster performance.

concurrency()

int

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

If ordered is true, then concurrency must be 1 or unspecified.

Default: 1.

chunkSize()

int

Optional. The number of documents to include in a single API request. DataStax recommends leaving this parameter unspecified to use the system default.

Maximum: 100

Default: 50

timeout

int

Optional. The maximum time, in milliseconds, that the client should wait for each underlying HTTP request.

Default: The default value for the collection. This default is 30 seconds unless you specified a different default when you initialized the Collection object.

Use the insertMany command with these parameters:

Name Type Summary

documents

array

An array of JSON objects describing the documents to insert.

In addition to open-ended fields that you can specify for each document, you may also specify the following reserved fields:

  • _id: An optional unique identifier for the document. If _id is omitted, it is created automatically based on the ID type. For more information, see Document IDs.

  • $vector: An optional array of numbers representing a vector embedding. The $vector field is only supported for vector-enabled collections. For more information, see Vector and vectorize.

  • $vectorize: An optional string to generate vector embeddings from. The $vectorize field is only supported for collections that have vectorize enabled. For more information, see Vector and vectorize and Auto-generate embeddings with vectorize.

The document may not contain both a $vector and a $vectorize field.

options

object

Optional. The options for this operation. See the options table for more details.
Properties of options:
Name Type Summary

ordered

boolean

Optional. Whether the insertions must be processed sequentially. If false, the documents may be inserted in an arbitrary order and possibly concurrently. If you don’t need ordered inserts, DataStax recommends setting this parameter to false for faster performance.

Default: false

Examples

The following examples demonstrate how to insert multiple documents into a collection.

Insert documents

The documents can have different structures.

  • Python

  • TypeScript

  • Java

  • curl

from astrapy import DataAPIClient

# Get an existing collection
client = DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
database = client.get_database("ASTRA_DB_API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")

# Insert documents into the collection
result = collection.insert_many([
    {
      "name": "Jane Doe",
      "age": 42
    },
    {
      "nickname": "Bobby",
      "color": "blue",
      "foods": ["carrots", "chocolate"]
    }
])
import { DataAPIClient, InsertManyError } from '@datastax/astra-db-ts';

// Get an existing collection
const client = new DataAPIClient('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const collection = database.collection('COLLECTION_NAME');

// Insert documents into the collection
(async function () {
  try {
    const result = await collection.insertMany([
      {
        name: 'Jane Doe',
        age: 42
      },
      {
        nickname: "Bobby",
        color: "blue",
        foods: ["carrots", "chocolate"]
      }
    ]);
  } catch (error) {
    if (error instanceof InsertManyError) {
      console.log(error.partialResult);
    }
  }
})();
package com.datastax.astra.client.collection;

import com.datastax.astra.client.Collection;
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.model.Document;
import com.datastax.astra.client.model.InsertManyResult;

public class InsertMany {

    public static void main(String[] args) {
        // Get an existing collection
        Collection<Document> collection = new DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
            .getDatabase("ASTRA_DB_API_ENDPOINT")
            .getCollection("COLLECTION_NAME");

        // Insert documents to the collection
        Document document1 = new Document()
            .append("name", "Jane Doe")
            .append("age", 42);
        Document document2 = new Document()
            .append("nickname", "Bobby")
            .append("color", "blue")
            .append("foods", Arrays.asList("carrots", "chocolate"));
        InsertManyResult result = collection.insertMany(List.of(document1, document2));
        System.out.println("IDs inserted: " + result.getInsertedIds());
    }
}
curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/COLLECTION_NAME" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "insertMany": {
    "documents": [
      {
        "name": "Jane Doe",
        "age": 42
      },
      {
        "nickname": "Bobby",
        "color": "blue",
        "foods": ["carrots", "chocolate"]
      }
    ]
  }
}'

Insert documents with vector embeddings

Use the reserved $vector field to insert documents with pregenerated vector embeddings.

The $vector field is only supported for vector-enabled collections. For more information, see Vector and vectorize.

You may also insert a mix of documents with and without the $vector field.

  • Python

  • TypeScript

  • Java

  • curl

from astrapy import DataAPIClient


# Get an existing collection
client = DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
database = client.get_database("ASTRA_DB_API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")

# Insert documents to the collection
result = collection.insert_many([
    {
      "name": "Jane Doe",
      "age": 42,
      "$vector": [.45, .32, .31]
    },
    {
      "nickname": "Bobby",
      "$vector": [.08, .68, .30]
    }
])
import { DataAPIClient, InsertManyError } from '@datastax/astra-db-ts';

// Get an existing collection
const client = new DataAPIClient('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const collection = database.collection('COLLECTION_NAME');

// Insert documents into the collection
(async function () {
  try {
    const result = await collection.insertMany([
      {
        name: 'Jane Doe',
        age: 42,
        $vector: [.45, .32, .31]
      },
      {
        nickname: "Bobby",
        $vector: [.08, .68, .30]
      }
    ]);
  } catch (error) {
    if (error instanceof InsertManyError) {
      console.log(error.partialResult);
    }
  }
})();
package com.datastax.astra.client.collection;

import com.datastax.astra.client.Collection;
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.model.Document;
import com.datastax.astra.client.model.InsertManyResult;

public class InsertMany {

    public static void main(String[] args) {
        // Get an existing collection
        Collection<Document> collection = new DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
            .getDatabase("ASTRA_DB_API_ENDPOINT")
            .getCollection("COLLECTION_NAME");

        // Insert documents to the collection
        Document document1 = new Document()
            .append("name", "Jane Doe")
            .append("age", 42)
            .vector(new float[]{0.45f, 0.32f, 0.41f});
        Document document2 = new Document()
            .append("nickname", "Bobby")
            .vector(new float[]{0.08f, 0.68f, 0.3f});
        InsertManyResult result = collection.insertMany(List.of(document1, document2));
        System.out.println("IDs inserted: " + result.getInsertedIds());
    }
}
curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/COLLECTION_NAME" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "insertMany": {
    "documents": [
      {
        "name": "Jane Doe",
        "age": 42,
        "$vector": [.45, .32, .31]
      },
      {
        "nickname": "Bobby",
        "$vector": [.08, .68, .30]
      }
    ]
  }
}'

Insert documents and generate vector embeddings

Use the reserved $vectorize field to generate a vector embedding automatically. The value of $vectorize can be any string.

The $vectorize field is only supported for collections that have vectorize enabled. For more information, see Vector and vectorize and Auto-generate embeddings with vectorize.

You may also insert a mix of documents with and without the $vectorize field.

  • Python

  • TypeScript

  • Java

  • curl

from astrapy import DataAPIClient


# Get an existing collection
client = DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
database = client.get_database("ASTRA_DB_API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")

# Insert documents into the collection
result = collection.insert_many([
    {
      "name": "Jane Doe",
      "age": 42,
      "$vectorize": "Text to vectorize for this document",
    },
    {
      "nickname": "Bobby",
      "$vectorize": "Text to vectorize for this document",
    }
])
import { DataAPIClient, InsertManyError } from '@datastax/astra-db-ts';

// Get an existing collection
const client = new DataAPIClient('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const collection = database.collection('COLLECTION_NAME');

// Insert documents into the collection
(async function () {
  try {
    const result = await collection.insertMany([
      {
        name: 'Jane Doe',
        age: 42,
        $vectorize: "Text to vectorize for this document"
      },
      {
        nickname: "Bobby",
        $vectorize: "Text to vectorize for this document"
      }
    ]);
  } catch (error) {
    if (error instanceof InsertManyError) {
      console.log(error.partialResult);
    }
  }
})();
package com.datastax.astra.client.collection;

import com.datastax.astra.client.Collection;
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.model.Document;
import com.datastax.astra.client.model.InsertManyResult;

public class InsertMany {

    public static void main(String[] args) {
        // Get an existing collection
        Collection<Document> collection = new DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
            .getDatabase("ASTRA_DB_API_ENDPOINT")
            .getCollection("COLLECTION_NAME");

        // Insert documents into the collection
        Document document1 = new Document()
            .append("name", "Jane Doe")
            .append("age", 42)
            .append("$vectorize", "Text to vectorize for this document");
        Document document2 = new Document()
            .append("nickname", "Bobby")
            .append("$vectorize", "Text to vectorize for this document");
        InsertManyResult result = collection.insertMany(List.of(document1, document2));
        System.out.println("IDs inserted: " + result.getInsertedIds());
    }
}
curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/COLLECTION_NAME" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "insertMany": {
    "documents": [
      {
        "name": "Jane Doe",
        "age": 42,
        "$vectorize": "Text to vectorize for this document"
      },
      {
        "nickname": "Bobby",
        "$vectorize": "Text to vectorize for this document"
      }
    ]
  }
}'

Insert documents and specify the IDs

  • Python

  • TypeScript

  • Java

  • curl

from astrapy import DataAPIClient


# Get an existing collection
client = DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
database = client.get_database("ASTRA_DB_API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")

# Insert documents into the collection
result = collection.insert_many([
    {
      "name": "Jane Doe",
      "_id": 1,
    },
    {
      "nickname": "Bobby",
      "_id": "23",
    }
])
import { DataAPIClient, InsertManyError } from '@datastax/astra-db-ts';

// Get an existing collection
const client = new DataAPIClient('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const collection = database.collection('COLLECTION_NAME');

// Insert documents into the collection
(async function () {
  try {
    const result = await collection.insertMany([
      {
        name: 'Jane Doe',
        _id: 1,
      },
      {
        nickname: "Bobby",
        _id: '23'
      }
    ]);
  } catch (error) {
    if (error instanceof InsertManyError) {
      console.log(error.partialResult);
    }
  }
})();
package com.datastax.astra.client.collection;

import com.datastax.astra.client.Collection;
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.model.Document;
import com.datastax.astra.client.model.InsertManyResult;

public class InsertMany {

    public static void main(String[] args) {
        // Get an existing collection
        Collection<Document> collection = new DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
            .getDatabase("ASTRA_DB_API_ENDPOINT")
            .getCollection("COLLECTION_NAME");

        // Insert documents to the collection
        Document document1 = new Document(1)
            .append("name", "Jane Doe");
        Document document2 = new Document("23")
            .append("nickname", "Bobby");
        InsertManyResult result = collection.insertMany(List.of(document1, document2));
        System.out.println("IDs inserted: " + result.getInsertedIds());
    }
}
curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/COLLECTION_NAME" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "insertMany": {
    "documents": [
      {
        "name": "Jane Doe",
        "_id": 1
      },
      {
        "nickname": "Bobby",
        "_id": "23"
      }
    ]
  }
}'

Insert documents and specify insertion behavior

The documents can have different structures.

  • Python

  • TypeScript

  • Java

  • curl

from astrapy import DataAPIClient

# Get an existing collection
client = DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
database = client.get_database("ASTRA_DB_API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")

# Insert documents into the collection
result = collection.insert_many(
    [
      {
        "name": "Jane Doe",
        "age": 42
      },
      {
        "nickname": "Bobby",
        "color": "blue",
        "foods": ["carrots", "chocolate"]
      }
    ],
    chunk_size=2,
    concurrency=2,
    ordered=False,
    max_time_ms=1000
)
import { DataAPIClient, InsertManyError } from '@datastax/astra-db-ts';

// Get an existing collection
const client = new DataAPIClient('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const collection = database.collection('COLLECTION_NAME');

// Insert documents into the collection
(async function () {
  try {
    const result = await collection.insertMany(
      [
        {
          name: 'Jane Doe',
          age: 42
        },
        {
          nickname: "Bobby",
          color: "blue",
          foods: ["carrots", "chocolate"]
        }
      ],
      {
        chunkSize: 2,
        concurrency: 2,
        ordered: false,
        maxTimeMS: 1000
      }
    );
  } catch (error) {
    if (error instanceof InsertManyError) {
      console.log(error.partialResult);
    }
  }
})();
package com.datastax.astra.client.collection;

import com.datastax.astra.client.Collection;
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.model.Document;
import com.datastax.astra.client.model.InsertManyOptions;
import com.datastax.astra.client.model.InsertManyResult;

public class InsertMany {

    public static void main(String[] args) {
        // Get an existing collection
        Collection<Document> collection = new DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
            .getDatabase("ASTRA_DB_API_ENDPOINT")
            .getCollection("COLLECTION_NAME");

        // Define the insertion options
        InsertManyOptions options = new InsertManyOptions()
            .chunkSize(20)
            .concurrency(3)
            .ordered(false)
            .timeout(1000);

        // Insert documents into the collection
        Document document1 = new Document()
            .append("name", "Jane Doe")
            .append("age", 42);
        Document document2 = new Document()
            .append("nickname", "Bobby")
            .append("color", "blue")
            .append("foods", Arrays.asList("carrots", "chocolate"));
        InsertManyResult result = collection.insertMany(List.of(document1, document2), options);
        System.out.println("IDs inserted: " + result.getInsertedIds());
    }
}
curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/COLLECTION_NAME" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "insertMany": {
    "documents": [
      {
        "name": "Jane Doe",
        "age": 42
      },
      {
        "nickname": "Bobby",
        "color": "blue",
        "foods": ["carrots", "chocolate"]
      }
    ],
    "options": {
      "ordered": false
    }
  }
}'

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