API reference overview

The Data API and DevOps API are the official way to programmatically interact with Astra DB Serverless.

Throughout the Astra DB Serverless documentation, you can find instructions that use the DevOps API, the Data API clients (Python, TypeScript, and Java), as well as cURL, Astra CLI, and the Astra Portal. The examples provided depend on the task described.

In addition to the method and command examples provided in the Astra DB Serverless documentation, you can also find links to generated reference documentation for the clients and the APIs.

If you’re using a legacy connection method for an existing project, see Legacy APIs.

Prerequisites

To use the Astra DB Serverless APIs, you need the following:

An active Astra account.
An Astra DB Serverless database. The Data API supports Serverless (Vector) databases.
An application token with the Database Administrator role.

Data API

Use the Data API to perform actions on databases, collections, and documents in Astra DB Serverless.

API reference

See also:

Data API clients

You can interact with the Data API directly or use one of the DataStax Data API clients for Python, TypeScript, or Java.

When you create apps using the Data API Python, TypeScript, and Java clients, your main entry point is to instantiate a DataAPIClient object. It’s the conceptual start of the overall coding hierarchy:

DataAPIClient → Databases → Collections → Documents

Conceptually separate from the coding hierarchy are the administration objects you use for database administration:

AstraDBAdmin → AstraDbDatabaseAdmin

The client can spawn specific objects for use in various types of subsequent interactions.

Within each reference topic, task-based sections present per-language examples in adjacent tabs. Depending on a given task’s context, the tabs may include Python, TypeScript, Java, cURL, and the Astra CLI.

Python client

AstraPy is the official Python client for Astra DB Serverless. It requires Python 3.8 or later.

API reference

For detailed examples, see the Python tab in the following topics:

See also:

AstraPy on GitHub

TypeScript client

astra-db-ts is the official TypeScript client for Astra DB Serverless. It requires Node.js v16.20.2 or later.

API reference

For detailed examples, see the TypeScript tab in the following topics:

See also:

astra-db-ts on GitHub

Java client

astra-db-java is the official Java client for Astra DB Serverless. It requires Java 11 or later.

API reference

For detailed examples, see the Java tab in the following topics:

See also:

astra-db-java on GitHub

DevOps API

Use the DevOps API to perform lifecycle actions on organizations and databases in Astra DB Serverless.

API reference

See also:

Naming conventions

Property names must start and end with a letter or an underscore, and may only contain the following characters:

a-z
A-Z
0-9
_ (underscore)

Names must be between 1 and 48 characters.

The _id property is reserved and interpreted as a document’s identity property.

The dollar sign $ is reserved for system-defined operator and property names. For example, $exists, $and, $or, and $vector.

Data types

The Data API supports the following data types. If you’re using a Data API client, consult the client reference for details on working with dates, UUIDs, and ObjectIDs.

String
Number
Object (JSON object)
Array
Boolean
Vector (via $vector)
Date (via $date)
Null
UUID (via $uuid)
ObjectId (via $objectId)

Limits

The Data API includes guardrails to ensure best practices, foster availability, and promote optimal configurations for your Astra DB Serverless databases.

Entity Limit Notes

Entity	Limit	Notes
Number of collections per database	Five	Up to five collections in a Serverless (Vector) database.
Page size	20	A page may contain up to 20 documents. After that per-page maximum is reached, you can load any additional documents on the next page via the `nextPageState` generated ID found in a JSON API command’s response.
Sort page size	100	Document page size for sorting; implemented as separate from page size because sort operations need more rows per page.
Maximum property name	100	Maximum of 100 characters in a property name.
Maximum path length	1,000	Maximum of 1,000 characters in a path name; total for all segments, including any dots (.) between properties in a path.
String property maximum bytes	8,000	Maximum of 8,000 bytes (UTF-8 encoded) for `string` length in an indexed property. The Data API uses UTF-8 encoding regardless of the original encoding in the request.
Number property maximum characters	100	Maximum of 100 characters for `number` length in a property.
Maximum elements per array	1,000	Maximum number of elements in an array. This limit applies to indexed properties only. This limit is ignored for non-indexed properties.
Maximum dimensions in vector-enabled collection	4,096	Maximum size of dimensions you can define for a vector-enabled collection.
Maximum number of properties per JSON object	1,000	Maximum number of properties for a JSON object. This limit applies to indexed properties only. This limit is ignored for non-indexed properties. A given JSON object may have nested objects, also known as sub-documents. This maximum total count of 1,000 refers to all the indexed properties in the main document, plus a count of 1 for each sub-document (if any).
Maximum number of properties per JSON document	2,000	Maximum number of properties allowed in a single JSON document is 2,000. This limit includes intermediate properties as well as leaf properties. For example, given this document: `{ "root": { "branch": { "leaf": 42 } } }` For the purposes of the limit, the document has three properties: `root`, `root.branch`, and `root.branch.leaf`.
Maximum document size in characters	4 million	Maximum size of each document in a collection is 4 million characters.
Maximum inserted batch size in characters	20 million	Maximum size of an entire batch of documents submitted via an `insertMany` or `updateMany` command is 20 million characters.
Maximum number of documents deleted per transaction	20	Maximum number of documents that can be deleted in each transaction.
Maximum number of documents updated per transaction	20	Maximum number of documents that can be updated in each transaction.
Maximum number of documents inserted per transaction	100	Maximum number of documents that can be inserted in each transaction when using `insertMany`.
Maximum size `_id` values array via `$in`	100	Maximum size of an `_id` values array that can be sent via the `$in` operator.
Maximum number of documents returned with each vector search	1,000	Maximum number of documents returned with each vector search.

Number of collections per database

Five

Up to five collections in a Serverless (Vector) database.

Page size

A page may contain up to 20 documents. After that per-page maximum is reached, you can load any additional documents on the next page via the nextPageState generated ID found in a JSON API command’s response.

Sort page size

100

Document page size for sorting; implemented as separate from page size because sort operations need more rows per page.

Maximum property name

100

Maximum of 100 characters in a property name.

Maximum path length

1,000

Maximum of 1,000 characters in a path name; total for all segments, including any dots (.) between properties in a path.

String property maximum bytes

8,000

Maximum of 8,000 bytes (UTF-8 encoded) for string length in an indexed property. The Data API uses UTF-8 encoding regardless of the original encoding in the request.

Number property maximum characters

100

Maximum of 100 characters for number length in a property.

Maximum elements per array

1,000

Maximum number of elements in an array. This limit applies to indexed properties only. This limit is ignored for non-indexed properties.

Maximum dimensions in vector-enabled collection

4,096

Maximum size of dimensions you can define for a vector-enabled collection.

Maximum number of properties per JSON object

1,000

Maximum number of properties for a JSON object. This limit applies to indexed properties only. This limit is ignored for non-indexed properties.

A given JSON object may have nested objects, also known as sub-documents. This maximum total count of 1,000 refers to all the indexed properties in the main document, plus a count of 1 for each sub-document (if any).

Maximum number of properties per JSON document

2,000

Maximum number of properties allowed in a single JSON document is 2,000. This limit includes intermediate properties as well as leaf properties. For example, given this document:

{
  "root": {
    "branch": {
      "leaf": 42
    }
  }
}

For the purposes of the limit, the document has three properties: root, root.branch, and root.branch.leaf.

Maximum document size in characters

4 million

Maximum size of each document in a collection is 4 million characters.

Maximum inserted batch size in characters

20 million

Maximum size of an entire batch of documents submitted via an insertMany or updateMany command is 20 million characters.

Maximum number of documents deleted per transaction

Maximum number of documents that can be deleted in each transaction.

Maximum number of documents updated per transaction

Maximum number of documents that can be updated in each transaction.

Maximum number of documents inserted per transaction

100

Maximum number of documents that can be inserted in each transaction when using insertMany.

Maximum size _id values array via $in

100

Maximum size of an _id values array that can be sent via the $in operator.

Maximum number of documents returned with each vector search

1,000

Maximum number of documents returned with each vector search.

Exceeded limit returns 200 OK with error

If your request is valid but the command exceeds a limit, the Data API responds with HTTP 200 OK and an error message.

It is also possible to receive a response containing both data and errors. Always inspect the response for error messages.

For example, if you exceed the per-transaction limit of 100 documents in an insertMany command, the Data API response contains the following message:

{
  "errors": [
    {
      "message": "Request invalid: field 'command.documents' value \"[...]\" not valid. Problem: amount of documents to insert is over the max limit (101 vs 100).",
      "errorCode": "COMMAND_FIELD_INVALID"
    }
  ]
}

Operators

Data API provides logical and update operators that you can use in filters.

For examples of these filters in Data API request payloads, see the cURL examples in the Documents reference or the Data API vector Postman collection.

Operator type Name Purpose

Operator type	Name	Purpose
Logical query	`$and`	Joins query clauses with a logical `AND`, returning the documents that match the conditions of both clauses.
	`$or`	Joins query clauses with a logical `OR`, returning the documents that match the conditions of either clause.
	`$not`	Returns documents that do not match the conditions of the filter clause.
Range query	`$gt`	Matches documents where the given property is greater than the specified value.
	`$gte`	Matches documents where the given property is greater than or equal to the specified value.
	`$lt`	Matches documents where the given property is less than the specified value.
	`$lte`	Matches documents where the given property is less than or equal to the specified value.
Comparison query	`$eq`	Matches documents where the value of a property equals the specified value. This is the default when you do not specify an operator.
	`$ne`	Matches documents where the value of a property does not equal the specified value.
	`$in`	Matches any of the values specified in the array.
	`$nin`	Matches any of the values that are NOT IN the array.
Element query	`$exists`	Matches documents that have the specified property.
Array query	`$all`	Matches arrays that contain all elements in the specified array.
	`$size`	Selects documents where the array has the specified number of elements.
Property update	`$currentDate`	Used in an update operation. In the following example, the `createdAt` property is updated to use the current date: `{ "findOneAndUpdate": { "filter": {"_id": "doc1"}, "update": { "$currentDate": { "createdAt": true } } } }`
	`$inc`	Increments the value of the property by the specified amount.
	`$min`	Updates the property only if the specified value is less than the existing property value.
	`$max`	Updates the property only if the specified value is greater than the existing property value.
	`$mul`	Multiply the value of a property in the document. Example: `{ "findOneAndUpdate": { "filter": { "_id": "upsert-id" }, "update": { "$currentDate": { "field": true }, "$mul": { "min_col": 5.2 } }, "options": { "returnDocument": "after" } } }`
	`$rename`	Renames the specified property in each matching document.
	`$set`	Sets the value of a property in each matching document.
	`$setOnInsert`	Set the value of a property in the document if an upsert is performed. Example: `{ "findOneAndUpdate": { "filter": { "_id": "upsert-id" }, "update": { "$currentDate": { "field": true }, "$setOnInsert": { "customer.name": "James B." } }, "options": { "returnDocument": "after" } } }`
	`$unset`	Removes the specified property from each matching document.
Array update	`$addToSet`	Adds elements to the array only if they do not already exist in the set.
	`$pop`	Removes the first or last item of the array, depending on the value of the operator (`-1` to remove the first item; `1` to remove the last item).
	`$push`	Adds or appends data to the end of the property value. Or, if the value is not yet an array: * If the property has no value, creates a one-element array (containing the item given). * If the property has a non-array value, creates a two-element array, with the old value as the first entry, and the specified item as the second entry.
	`$each`	An array update that modifies the `$push` and `$addToSet` operators to append multiple items for array updates.
	`$position`	An array update that modifies the `$push` operator to specify the position in the array to add elements.

Logical query

$and

Joins query clauses with a logical AND, returning the documents that match the conditions of both clauses.

$or

Joins query clauses with a logical OR, returning the documents that match the conditions of either clause.

$not

Returns documents that do not match the conditions of the filter clause.

Range query

$gt

Matches documents where the given property is greater than the specified value.

$gte

Matches documents where the given property is greater than or equal to the specified value.

$lt

Matches documents where the given property is less than the specified value.

$lte

Matches documents where the given property is less than or equal to the specified value.

Comparison query

$eq

Matches documents where the value of a property equals the specified value. This is the default when you do not specify an operator.

$ne

Matches documents where the value of a property does not equal the specified value.

$in

Matches any of the values specified in the array.

$nin

Matches any of the values that are NOT IN the array.

Element query

$exists

Matches documents that have the specified property.

Array query

$all

Matches arrays that contain all elements in the specified array.

$size

Selects documents where the array has the specified number of elements.

Property update

$currentDate

Used in an update operation. In the following example, the createdAt property is updated to use the current date:

{
  "findOneAndUpdate": {
    "filter": {"_id": "doc1"},
    "update": {
      "$currentDate": {
        "createdAt": true
        }
      }
    }
}

$inc

Increments the value of the property by the specified amount.

$min

Updates the property only if the specified value is less than the existing property value.

$max

Updates the property only if the specified value is greater than the existing property value.

$mul

Multiply the value of a property in the document. Example:

{
    "findOneAndUpdate": {
        "filter": {
            "_id": "upsert-id"
        },
        "update": {
            "$currentDate": {
                "field": true
            },
            "$mul": {
                "min_col": 5.2
            }
        },
        "options": {
            "returnDocument": "after"
        }
    }
}

$rename

Renames the specified property in each matching document.

$set

Sets the value of a property in each matching document.

$setOnInsert

Set the value of a property in the document if an upsert is performed. Example:

{
    "findOneAndUpdate": {
        "filter": {
            "_id": "upsert-id"
        },
        "update": {
            "$currentDate": {
                "field": true
            },
            "$setOnInsert": {
                "customer.name": "James B."
            }
        },
        "options": {
            "returnDocument": "after"
        }
    }
}

$unset

Removes the specified property from each matching document.

Array update

$addToSet

Adds elements to the array only if they do not already exist in the set.

$pop

Removes the first or last item of the array, depending on the value of the operator (-1 to remove the first item; 1 to remove the last item).

$push

Adds or appends data to the end of the property value. Or, if the value is not yet an array: * If the property has no value, creates a one-element array (containing the item given). * If the property has a non-array value, creates a two-element array, with the old value as the first entry, and the specified item as the second entry.

$each

An array update that modifies the $push and $addToSet operators to append multiple items for array updates.

$position

An array update that modifies the $push operator to specify the position in the array to add elements.

API reference overview

Prerequisites

Data API

Data API clients

Python client

TypeScript client

Java client

DevOps API

Naming conventions

Data types

Limits

Exceeded limit returns 200 OK with error

Operators

Was this helpful?

Give Feedback