Insert a document

This documentation reflects client version 1.5.x. For 2.x documentation, refer to the client reference for Python, TypeScript, or Java.

Inserts a single document 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 About collections with the Data API.

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

Method signature

  • Python

  • TypeScript

  • Java

  • curl

The following method belongs to the astrapy.Collection class.

insert_one(
  document: Dict[str, Any],
  *,
  max_time_ms: int,
) -> InsertOneResult

The following method belongs to the Collection class.

async insertOne(
  document: MaybeId<Schema>,
  options?: {
    maxTimeMS?: number,
  },
): InsertOneResult<Schema>

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

InsertOneResult insertOne(
  T document
)
InsertOneResult insertOne(
  T document,
  InsertOneOptions 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 '{
  "insertOne": {
    "document": DOCUMENT_JSON_OBJECT
  }
}'

Result

  • Python

  • TypeScript

  • Java

  • curl

Inserts the specified document and returns an InsertOneResult object that includes the ID of the inserted document and details about the success of the operation.

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

Example response:

InsertOneResult(inserted_id='92b3c4f4-db44-4440-b4c4-f4db54e440b8', raw_results=...)

Inserts the specified document and returns a promise that resolves to an InsertOneResult<Schema> object that includes the ID of the inserted document.

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

Example response:

{ insertedId: '92b3c4f4-db44-4440-b4c4-f4db54e440b8' }

Inserts the specified document and returns a wrapper (InsertOneResult) that includes the ID of the inserted document.

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

Inserts the specified document and returns a JSON object that includes the ID of the inserted document.

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

Example response:

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

Parameters

  • Python

  • TypeScript

  • Java

  • curl

Name Type Summary

document

Dict[str, Any]

A dictionary describing the document to insert.

In addition to open-ended fields that you can specify, 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 in collections.

  • $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 in collections and Auto-generate embeddings with vectorize.

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

max_time_ms

int

Optional. The maximum time, in milliseconds, that the client should wait for the 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

document

MaybeId<Schema>

An object describing the document to insert.

In addition to open-ended fields that you can specify, 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 in collections.

  • $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 in collections and Auto-generate embeddings with vectorize.

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

options

InsertOneOptions

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

maxTimeMS

number

Optional. The maximum time, in milliseconds, that the client should wait for the 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

document

T

An object describing the document to insert.

In addition to open-ended fields that you can specify, 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 in collections.

  • $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 in collections and Auto-generate embeddings with vectorize.

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

options

InsertOneOptions

Optional. The options to apply to the insert operation.

Use the insertOne command with these parameters:

Name Type Summary

document

object

A JSON object describing the document to insert.

In addition to open-ended fields that you can specify, 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 in collections.

  • $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 in collections and Auto-generate embeddings with vectorize.

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

Examples

The following examples demonstrate how to insert a document into a collection.

Insert a document

  • 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 a document into the collection
result = collection.insert_one({
    "name": "Jane Doe",
    "age": 42
})
import { DataAPIClient } 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 a document into the collection
(async function () {
  const result = await collection.insertOne({
    name: 'Jane Doe',
    age: 42
  });
})();
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.InsertOneResult;

public class InsertOne {

    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 a document into the collection
        Document document = new Document()
            .append("name", "Jane Doe")
            .append("age", 42);
        InsertOneResult result = collection.insertOne(document);
        System.out.println(result.getInsertedId());
    }
}
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 '{
  "insertOne": {
    "document": {
      "purchase_type": "Online",
      "customer": {
        "name": "Jim A.",
        "phone": "123-456-1111",
        "age": 51,
        "credit_score": 782,
        "address": {
          "street": "1234 Broadway",
          "city": "New York",
          "state": "NY"
        }
      },
      "purchase_date": { "$date": 1690045891 },
      "seller": {
        "name": "Jon B.",
        "location": "Manhattan NYC"
      },
      "items": [
        {
          "car": "BMW 330i Sedan",
          "color": "Silver"
        },
        "Extended warranty - 5 years"
      ],
      "amount": 47601,
      "status": "active",
      "preferred_customer": true
    }
  }
}'

Insert a document with vector embeddings

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

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

  • 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 a document into the collection
result = collection.insert_one(
    {
      "name": "Jane Doe",
      "$vector": [.08, .68, .30],
    },
)
import { DataAPIClient } 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 a document into the collection
(async function () {
  const result = await collection.insertOne({
  name: 'Jane Doe',
  $vector: [.08, .68, .30],
});
})();
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.InsertOneResult;

public class InsertOne {

    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 a document into the collection
        Document document = new Document()
            .append("name", "Jane Doe")
            .append("$vector", new float[] {.08f, .68f, .30f});
        InsertOneResult result = collection.insertOne(document);
        System.out.println(result.getInsertedId());
    }
}
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 '{
  "insertOne": {
    "document": {
      "name": "Jane Doe",
      "$vector": [.08, .68, .30]
    }
  }
}'

Insert a document 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 in collections and Auto-generate embeddings with vectorize.

  • 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 a document into the collection
result = collection.insert_one(
    {
      "name": "Jane Doe",
      "$vectorize": "Text to vectorize",
    },
)
import { DataAPIClient } 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 a document into the collection
(async function () {
  const result = await collection.insertOne({
    name: 'Jane Doe',
    $vectorize: 'Text to vectorize',
  });
})();
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.InsertOneResult;

public class InsertOne {

    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 a document into the collection
        Document document = new Document()
            .append("name", "Jane Doe")
            .append("$vectorize", "Text to vectorize");
        InsertOneResult result = collection.insertOne(document);
        System.out.println(result.getInsertedId());
    }
}
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 '{
  "insertOne": {
    "document": {
      "name": "Jane Doe",
      "$vectorize": "Text to vectorize"
    }
  }
}'

Insert a document and specify the ID

  • 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 a document into the collection
result = collection.insert_one(
    {
        "_id": 1,
        "name": "Jane Doe",
    },
)
import { DataAPIClient } 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 a document into the collection
(async function () {
  const result = await collection.insertOne({
    _id: '1',
    name: 'Jane Doe',
  });
})();
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.InsertOneResult;

public class InsertOne {

    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 a document into the collection
        Document document = new Document("1")
            .append("name", "Jane Doe")
            .append("age", 42);
        InsertOneResult result = collection.insertOne(document);
        System.out.println(result.getInsertedId());
    }
}
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 '{
  "insertOne": {
    "document": {
      "name": "Jane Doe",
      "_id": "1"
    }
  }
}'

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