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.

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, each a document to insert. Documents may specify their _id field or leave it out, in which case it will be added automatically. Each document may contain the $vector or the $vectorize fields, but not both.

ordered

bool

If False (default), the insertions can occur in arbitrary order and possibly concurrently. If True, they are processed sequentially. If you don’t need ordered inserts, DataStax recommends setting this parameter to False for faster performance.

DataStax recommends ordered = False, which typically results in a much higher insert throughput than an equivalent ordered insertion.

chunk_size

Optional[int]

How many documents to include in a single API request. The default is 50, and the maximum is 100.

concurrency

Optional[int]

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

max_time_ms

Optional[int]

A timeout, in milliseconds, for the operation. If not passed, the collection-level setting is used instead: If you are inserting many documents, this method will require multiple HTTP requests. You may need to increase the timeout duration for the method to complete successfully.
Name Type Summary

documents

MaybeId<Schema>[]

The documents to insert. If any document does not have an _id field, the server generates one. They may each contain a $vector or $vectorize field to enable semantic searching.

options?

InsertManyOptions

The options for this operation.

Options (InsertManyOptions):

Name Type Summary

ordered?

boolean

You may set the ordered option to true to stop the operation after the first error; otherwise all documents may be parallelized and processed in arbitrary order, improving, perhaps vastly, performance.

DataStax recommends ordered: false, which typically results in a much higher insert throughput than an equivalent ordered insertion.

concurrency?

number

You can set the concurrency option to control how many network requests are made in parallel on unordered insertions. Defaults to 8. This is not available for ordered insertions.

chunkSize?

number

Control how many documents are sent with each network request. The default is 50, and the maximum is 100.

maxTimeMS?

number

The maximum time in milliseconds that the client should wait for the operation to complete.
Name Type Summary

docList

List<? extends DOC>

A list of documents to insert. Documents may specify their _id field or leave it out, in which case it will be added automatically. If the collection is associated with an embedding service, it will generate vector embeddings automatically from the $vectorize field in each document. You can also set the $vector field directly.

options (optional)

InsertManyOptions

Set the different options for the insert operation. The options are ordered, concurrency, chunkSize.

The Java operation insertMany can take as many documents as you want as long as it fits in your JVM memory. It will split the documents in chunks of chunkSize and send them to the server in a distributed way through an ExecutorService.

As a best practice, try to always provide InsertManyOptions, even when using defaults, because it brings visibility to the readers:

InsertManyOptions.Builder
  .chunkSize(20)  // batch size, 100 is max
  .concurrency(8) // concurrent insertions
  .ordered(false) // unordered insertions
  .build();

The default value of chunkSize is 50, and the maximum value is 100. To set the size of the executor use concurrency. DataStax recommends ordered(false) for performance reasons because it can insert chunks in parallel.

If not provided the default values are chunkSize=50, concurrency=1 and ordered=false.
Name Type Summary

insertMany

command

Data API command to insert multiple documents. You can insert up to 100 documents per request.

documents

array

Contains the details of the records to add. It is an array of objects where each object represents a document.

With the exception of reserved fields (_id, $vector, and $vectorize), document data can be any valid JSON, including strings, integers, booleans, dates, objects, nested objects, and arrays:

    "documents": [
      {
        "string_example": "string value",
        "object_example": {
          "a": "one",
          "b": 2,
          "nested_object": {
            "c": false
          }
        },
        "date_example": { "$date": 1690045891 },
        "array_example": [
          {
            "d.e": "hello",
            "f.g": "goodbye"
          },
          "arbitrary string in an array"
        ]
      }
    ]

_id

reserved multi-type

An optional identifier for a document. If omitted, the server automatically generates a document ID. You can include identifiers in other fields as well. For more information, see Document IDs and The defaultId option.

$vector

reserved array

An optional reserved property used to store an array of numbers representing a vector embedding for a document. Serverless (Vector) databases have specialized handling for vector data, including optimized query performance for vector search.

$vector and $vectorize are mutually exclusive.

$vectorize

reserved string

An optional reserved property used to store a string that you want to use to automatically generate an embedding for a document.

$vector and $vectorize are mutually exclusive.

options.ordered

boolean

If false, insertions occur in an arbitrary order with possible concurrency. If true, insertions occur sequentially. If you don’t need ordered inserts, DataStax recommends "ordered": false, which typically results in a much higher insert throughput than an equivalent ordered insertion.

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