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 active Astra DB Serverless database. The Data API supports Serverless (Vector) databases.
-
An application token with sufficient permissions to perform the requested operations.
-
A tool to handle API calls, such as curl.
Export environment variables
Whether you use curl
or a Data API client, it is helpful to set your application token and your database’s API endpoint as environment variables.
For more information on obtaining these values, see Manage application tokens.
You can use any method you prefer to set environment variables. The following code samples are for example purposes only.
-
Linux or macOS
-
Windows
export ASTRA_DB_API_ENDPOINT=API_ENDPOINT # Your database API endpoint
export ASTRA_DB_APPLICATION_TOKEN=TOKEN # Your database application token
set ASTRA_DB_API_ENDPOINT=API_ENDPOINT # Your database API endpoint
set ASTRA_DB_APPLICATION_TOKEN=TOKEN # Your database application token
As you learn about the Data API, you might set additional environment variables for commonly used values, such as COLLECTION_NAME
or NAMESPACE_NAME
.
Optional curl arguments
The Data API and DevOps API curl examples throughout the Astra DB Serverless documentation include some optional arguments, such as -s
, -sS
, and | jq
.
You can omit or modify these arguments as needed.
Filepaths assume *nix
Throughout the Astra DB Serverless documentation, filepaths assume a *nix environment.
If you use Microsoft Windows, you might need to adjust the filepaths given in the examples.
DevOps API
Use the DevOps API to perform lifecycle actions on organizations and databases in Astra DB Serverless.
See also:
Data API
Use the Data API to perform actions on Astra DB Serverless (Vector) databases and the collections and data (documents) within those collections.
The Data API is a schema-less, document-based, modern API that provides easy and intuitive access to structured vector data in your Serverless (Vector) databases. It leverages the scalability, performance, and real-time indexing capabilities of Apache Cassandra® to support GenAI application development. To get the most relevant results possible, you can execute vector search queries, apply complex document filtering, or both.
The Data API is an entry point for Astra DB Serverless to integrate with the GenAI ecosystem, which includes tools like LangChain, LlamaIndex, and a variety of embedding providers.
Use the Data API and clients to create applications that interact with your Serverless (Vector) databases, including a variety of query and update operators to filter documents and sort response data, as well as vector search commands that return similarity scores.
For more information, see the following:
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:
Conceptually separate from the coding hierarchy are the administration objects you use for database administration:
Clients can spawn specific objects for use in subsequent interactions.
-
Python
-
TypeScript
-
Java
AstraPy is the official Python client for Astra DB Serverless. It requires Python 3.8 or later.
astra-db-ts is the official TypeScript client for Astra DB Serverless. It requires Node.js v18 or later.
astra-db-java is the official Java client for Astra DB Serverless. It requires Java 11 or later.
For more information and examples, see the client language tabs in the following documentation:
Naming conventions
Astra DB has the following naming conventions for databases, namespaces, keyspaces, collections, tables, and vectorize API keys:
-
Must start and end with a letter or number
-
Can contain uppercase letters A-Z, lowercase letters a-z, numbers 0-9, and underscores (
_
) -
Must contain at least two characters
-
Can’t exceed the maximum character limit for the entity type:
-
Namespaces and keyspaces: 48 characters
-
Databases, collections, tables, and vectorize API keys: 50 characters
-
The Data API has the following naming conventions for document properties:
-
Must start and end with a letter or an underscore (
_
). -
Can contain uppercase letters A-Z, lowercase letters a-z, numbers 0-9, and underscores (
_
) -
Must contain at least one character
-
Can’t exceed 48 characters
-
Can’t be exactly
_id
, which is reserved and interpreted as a document’s identity property
The dollar sign ($
) is reserved for system-defined operator and property names, such as $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.
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 |
---|---|---|
Number of collections per database |
5 or 10 |
Serverless (Vector) databases created after June 24, 2024 can have up to 10 collections. Databases created before this date can have up to 5 collections. The collection limit is based on Storage Attached Indexing (SAI). For more information, see The indexing option. |
Page size |
20 |
For certain operations, 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:
Some operations, such as |
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 length |
100 |
Maximum of 100 characters in a document 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. |
Maximum indexed string property size in bytes |
8,000 |
Maximum of 8,000 bytes (UTF-8 encoded) for |
Maximum number property length |
100 |
Maximum of 100 characters for the length of a |
Maximum elements per array |
1,000 |
Maximum number of elements in an array. This limit applies to indexed properties only. |
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. 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, the following document has three properties that apply to this limit:
|
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 |
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 |
Maximum size |
100 |
Maximum size of an |
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 to find, update, replace, and delete documents:
Operator type | Name | Purpose |
---|---|---|
Logical query |
|
Joins query clauses with a logical |
|
Joins query clauses with a logical |
|
|
Returns documents that do not match the conditions of the filter clause. |
|
Range query |
|
Matches documents where the given property is greater than the specified value. |
|
Matches documents where the given property is greater than or equal to the specified value. |
|
|
Matches documents where the given property is less than the specified value. |
|
|
Matches documents where the given property is less than or equal to the specified value. |
|
Comparison query |
|
Matches documents where the value of a property equals the specified value. This is the default when you do not specify an operator. |
|
Matches documents where the value of a property does not equal the specified value. |
|
|
Matches any of the values specified in the array. |
|
|
Matches any of the values that are NOT IN the array. |
|
Element query |
|
Matches documents that have the specified property. |
Array query |
|
Matches arrays that contain all elements in the specified array. |
|
Selects documents where the array has the specified number of elements. |
|
Property update |
|
Used in an update operation to set a property to the current date. |
|
Increments the value of the property by the specified amount. |
|
|
Updates the property only if the specified value is less than the existing property value. |
|
|
Updates the property only if the specified value is greater than the existing property value. |
|
|
Multiply the value of a property in the document. |
|
|
Renames the specified property in each matching document. |
|
|
Sets the value of a property in each matching document. |
|
|
Set the value of a property in the document if an upsert is performed. |
|
|
Removes the specified property from each matching document. |
|
Array update |
|
Adds elements to the array only if they do not already exist in the set. |
|
Removes the first or last item of the array, depending on the value of the operator.
Use |
|
|
Adds or appends data to the end of the property value. If the value is not yet an array and the property has no value, this operator creates a one-element array that contains the given item. If the value is not yet an array and the property has a non-array value, this operator creates a two-element array that has the existing value as the first entry and the given item as the second entry. |
|
|
An array update that modifies the |
|
|
An array update that modifies the |