Migrate to the Data API

If you are new to Astra DB or the Data API, this page provides guidance on moving from a similar API or tool to the Data API.

Migrate from MongoDB

Both MongoDB and Astra DB provide APIs to interact with your data.

If you are familiar with MongoDB’s API, you will find many similarities in the Astra DB Data API, and you can quickly get started with Astra DB. However, the Data API isn’t fully compatible with MongoDB’s API. The following information describes key similarities and differences between MongoDB and Astra DB.

Connect

You can interact with the Astra DB Data API directly through HTTP or through the Python, TypeScript, and Java clients.

While there are many MongoDB drivers, the MongoDB Data API and HTTPS endpoints are deprecated. Astra DB continues to support HTTPS as a viable option for interacting with the Astra DB Data API and DevOps API.

Both the MongoDB drivers and Astra DB Data API clients require you to instantiate a client object, but the manner of authentication is different:

MongoDB requires a connection URI, which can include authentication parameters.
Astra DB requires an application token and your database’s API endpoint. The permissions required for the token depend on the commands you want to execute

For more information, see Get started with the Data API.

Timeouts

The Astra DB Data API clients do not cancel a running server job upon hitting the timeout limit. Instead, the client stops waiting for the server-side operation and proceeds to the next client-side command.

Client code example

Astra DB Data API client code is similar to MongoDB driver code. The following examples compare some MongoDB Node.js driver code with Astra DB TypeScript client code. Both examples query a database, and they both assume you have a database with some data loaded and ready to query.

MongoDB Node.js driver
Astra DB TypeScript client

const { MongoClient } = import("mongodb");

// Replace the uri string with your connection string.
const uri = "CONNECTION_STRING_URL";

const client = new MongoClient(uri);

async function run() {
  try {
    const database = client.db('sample_mflix');
    const movies = database.collection('movies');

    // Query for a movie that has the title 'Back to the Future'
    const query = { title: 'Back to the Future' };
    const movie = await movies.findOne(query);

    console.log(movie);
  } finally {
    // Ensures that the client will close when you finish/error
    await client.close();
  }
}
run().catch(console.dir);

import { DataAPIClient } from "@datastax/astra-db-ts";

const token = "ASTRA_DB_APPLICATION_TOKEN";
const endpoint = "ASTRA_DB_API_ENDPOINT";

const client = new DataAPIClient(token);

async function run() {
  try {
    const database = client.db(endpoint);
    const movies = database.collection("movies");

    // Query for a movie that has the title Back to the Future
    const query = { title: "Back to the Future" };
    const movie = await movies.findOne(query);

    console.log(movie);
  } finally {
    // Ensures that the client will close when you finish/error
    await client.close();
  }
}
run().catch(console.dir);

Architecture

While MongoDB and Astra DB both use a four-layer architecture, the names of these layers and some underlying functionality are different.

These differences exist because Astra DB is based on Apache Cassandra®, which uses keyspaces to group tables (and collections) in a database. In contrast, MondoDB organizes data using databases and collections.

MongoDB architecture layer	Astra DB architecture layer	Definition
Cluster	Database	The top-level container for your data.
Database	Keyspace	A logical container for collections of data.
Collection	Collection	A group of documents.
Document	Document	A record in a collection.

MongoDB architecture layer

Astra DB architecture layer

Definition

Cluster

Database

The top-level container for your data.

Database

Keyspace

A logical container for collections of data.

Collection

A group of documents.

Document

A record in a collection.

Command compatibility matrix

The following table compares command compatibility at different architecture layers:

Astra DB layer MongoDB command Astra DB command Comments

Astra DB layer	MongoDB command	Astra DB command	Comments
Databases	Access a database	Connect to a database
Keyspaces	See Database	Connect to a database	In Astra DB, when you connect to a database, you set a working keyspace. You can change the working keyspace, but you don’t need an extra command to establish the initial working keyspace.
Collections	Create a collection	Create a collection
Collections	Access a collection	Get a collection
Collections	List collections	List collections	The Astra DB Data API clients also provide a List collection names command.
Collections	Delete a collection	Delete a collection	Astra DB doesn’t support methods like `collection.rename()`. Collection configuration is immutable after creation.
Documents	Insert one	Insert one
Documents	Insert many	Insert many	Astra DB supports `ordered` inserts, among other options.
Documents	Find one	Find one
Documents	Find multiple	Find	There are many nuances to the `find` command and the compatibility of `filter`, `limit`, `sort`, and `skip` options. For more information, see Sort clauses and Find documents using filter clauses.
Documents	Find distinct	Distinct	This command is a client-side operation that can have performance and billing implications when searching large datasets. Astra DB doesn’t offer direct support for this command in HTTP. However, you can use Find with `jq` or another utility to extract desired values from the response. This is effectively the same approach taken by the clients.
Documents	Update one	Update one	For a more verbose response that includes the original or updated document, use the Astra DB Data API Find one and update command. `upsert` is supported.
Documents	Update many	Update many	`upsert` is supported.
Documents	Replace one	Find one and replace	The Astra DB Data API clients also provide a Replace one command, which performs the same operation but returns only the outcome of the operation. This command isn’t available over HTTP, but you can use a projection to minimize the response from `findOneAndReplace`.
Documents	Count documents	Count documents	Astra DB supports filtered and unfiltered counting. This command isn’t recommended for counting large datasets. For more information, see Count documents.
Documents	Estimated document count	Estimate document count
Documents	Delete one	Delete one	For a more verbose response that includes the deleted document, use the Astra DB Data API Find one and delete command.
Documents	Delete multiple	Delete many

Databases

Access a database

Connect to a database

Keyspaces

See Database

Connect to a database

In Astra DB, when you connect to a database, you set a working keyspace. You can change the working keyspace, but you don’t need an extra command to establish the initial working keyspace.

Collections

Create a collection

Collections

Access a collection

Get a collection

Collections

List collections

The Astra DB Data API clients also provide a List collection names command.

Collections

Delete a collection

Astra DB doesn’t support methods like collection.rename(). Collection configuration is immutable after creation.

Documents

Insert one

Documents

Insert many

Astra DB supports ordered inserts, among other options.

Documents

Find one

Documents

Find multiple

Find

There are many nuances to the find command and the compatibility of filter, limit, sort, and skip options. For more information, see Sort clauses and Find documents using filter clauses.

Documents

Find distinct

Distinct

This command is a client-side operation that can have performance and billing implications when searching large datasets.

Astra DB doesn’t offer direct support for this command in HTTP. However, you can use Find with jq or another utility to extract desired values from the response. This is effectively the same approach taken by the clients.

Documents

Update one

For a more verbose response that includes the original or updated document, use the Astra DB Data API Find one and update command.

upsert is supported.

Documents

Update many

upsert is supported.

Documents

Replace one

Find one and replace

The Astra DB Data API clients also provide a Replace one command, which performs the same operation but returns only the outcome of the operation. This command isn’t available over HTTP, but you can use a projection to minimize the response from findOneAndReplace.

Documents

Count documents

Astra DB supports filtered and unfiltered counting. This command isn’t recommended for counting large datasets. For more information, see Count documents.

Documents

Estimated document count

Estimate document count

Documents

Delete one

For a more verbose response that includes the deleted document, use the Astra DB Data API Find one and delete command.

Documents

Delete multiple

Delete many

Indexing

Indexing is significantly different in MongoDB and Astra DB:

MongoDB function Astra DB function Comments

MongoDB function	Astra DB function	Comments
Multiple index types	Single field indexes only
Automatic indexing for `_id` only. You must create and manage additional indexes.	Automatic indexing for all document properties with the option for selective indexing.
Dynamic index management	No dynamic index management.	In Astra DB, indexing is a collection-level configuration that you set when you create a collection. Collection settings are immutable after creation.

Multiple index types

Single field indexes only

Automatic indexing for _id only. You must create and manage additional indexes.

Automatic indexing for all document properties with the option for selective indexing.

Dynamic index management

No dynamic index management.

In Astra DB, indexing is a collection-level configuration that you set when you create a collection. Collection settings are immutable after creation.

ObjectIds and UUIDs

The Astra DB Data API supports a variety of _id types, including MongoDB’s ObjectId type. For more information, see Document IDs and The defaultId option.

Vector search

Astra DB supports Vector search similar to MongoDB Atlas Vector Search. However, whereas Atlas Vector Search is part of an aggregation pipeline, Astra DB’s vector search is directly integrated in commands, like Find, as a sort clause.

Additionally, Astra DB can generate embeddings on demand with vectorize. You can use $vectorize to run a vector search based on an embedding generated from any text string.

The Astra DB Data API offers commands and parameters for vector search and vectorize, including collection parameters for vectorize and the $vector and $vectorize reserved fields.

Operators

The Astra DB Data API doesn’t support all MongoDB operators. Unsupported operators include, but are not limited to, the following:

$type
$elemMatch
Evaluation operators, such as $expr, $jsonSchema, $mod, $regex, and $where
Bitwise operators, such as those prefixed with $bits
Geospatial operators, such as those prefixed with $geo and geometry specifiers
Miscellaneous operators $comment, $rand, and $natural

The Astra DB Data API doesn’t support $nor, but you can use compound $not and $and operators instead.

For more information and examples, see Operators, $date, and the references for the methods that use these operators, such as Find.

Response modifiers

The Astra DB Data API offers options to modify the order and content of a response beyond query filters:

limit
sort
skip
projection (including $slice)

In the Astra DB Data API, some combinations of filter, limit, sort, and skip are incompatible. For more information, see Sort clauses.

Cursors and pagination

Like the MongoDB drivers, the Astra DB Data API clients use cursors to manage large responses. Over HTTP, the Astra DB Data API uses pagination.

For more information and examples, refer to the references for commands that return cursors or pagination, such as Find.

MongooseJS

You can use the Astra DB Data API with MongooseJS. For more information, see Integrate MongooseJS with Astra DB Serverless.

Administration

You can use the Astra DB Data API clients to perform administrative operations on databases and keyspaces:

Create a database
Get database information
List databases
Delete a database
List keyspaces
Create a keyspace
Delete a keyspace

These commands are also available over HTTP through the DevOps API API. For more information, see Databases reference.

You can’t use MongoDB drivers for database or cluster administration. However, MongoDB offers other programmatic options for these tasks.

Outside of database operations, Astra DB offers administrative tools similar to those offered by MongoDB:

MongoDB tool	Astra DB tool	Comments
Atlas App Services Admin API	Astra DB DevOps API	Some DevOps API functions are also available through the Astra DB Data API clients. For more information, see Databases reference.
HashiCorp Terraform MongoDB Atlas Provider	HashiCorp Terraform Astra DB Provider	For more information, see Integrate HashiCorp Terraform with Astra DB Serverless.
Atlas CLI	Astra CLI

MongoDB tool

Astra DB tool

Comments

Atlas App Services Admin API

Astra DB DevOps API

Some DevOps API functions are also available through the Astra DB Data API clients. For more information, see Databases reference.

HashiCorp Terraform MongoDB Atlas Provider

HashiCorp Terraform Astra DB Provider

For more information, see Integrate HashiCorp Terraform with Astra DB Serverless.

Atlas CLI

Astra CLI

Incompatible functionality

The Astra DB Data API doesn’t provide a mechanism for change streams, but you can use the Astra DB CDC connector external to the Astra DB Data API. To enable this feature for Serverless (Vector) databases, contact DataStax Support.

The following MongoDB driver functionality isn’t available in Astra DB or the Astra DB Data API:

Migrate from CQL

You can use the Data API to manage your CQL tables. However, the Data API doesn’t support all CQL commands, arguments, objects, or types.

Unsupported commands

The Data API does not support LWTs, BATCH, or any CQL commands related to the following objects:

Aggregates
Materialized views
User management
User-defined types
User-defined functions
Triggers

Most of these unsupported commands are also not supported in CQL for Astra DB. For example, user management is handled through Astra DB RBAC.

Supported commands

The Data API offers functionality that is equivalent to the following CQL commands. However, the Data API doesn’t support all types, formats, or modifiers, as explained in CQL types and Support for existing tables. Follow the links in the list below to learn more about running these commands through the Data API.

ALTER TABLE
CREATE INDEX
CREATE TABLE
DELETE

Use DELETE to delete an entire row. To delete a single value from a row, use $unset in updateOne.
DESCRIBE
DROP INDEX
DROP TABLE
INSERT
SELECT

The Data API doesn’t support calling CQL functions, alias columns, DISTINCT, token(), or literal.
TRUNCATE
UPDATE
USE: The Data API doesn’t provide an explicit command for this. Instead, the target table is specified in the Data API request path.

CQL types

Unsupported types, formats, and modifiers include:

User-defined types (UDTs)
Counters
Time To Live (TTL)
Column timestamps
Frozen
Static
Tuple

The following types are partially supported or supported with limitations:

Unsupported types are flagged in Data API responses that contain table definitions, such as listTables. For example, the following partial response indicates that a tuple column is unsupported. The response includes the original CQL definition and the actions that are unavailable through the Data API. In this case, you can neither create tuple columns nor read/write from existing tuple columns.

"column_name": {
  "type": "UNSUPPORTED",
  "apiSupport": {
    "createTable": false,
    "insert": false,
    "read": false,
    "cqlDefinition": "frozen<tuple<text, text, int>>"
  }
}

For information about supported types, see Column data types.

Support for existing tables

You can use the Data API to manage existing CQL tables. In addition to the information about unsupported types and unsupported commands, the following restrictions apply when working with existing tables:

TTL is read-only. However, reading data that has a TTL on it can have unexpected results, such as reads returning different data when the TTL expires.
You can read, write, and filter existing static columns, but DataStax does not recommend modifying static columns with the Data API.

Using the Data API to update an existing static column can have unexpected results. If you require static columns, DataStax recommends using CQL instead of the Data API.
Frozen scalar columns are read-only. Frozen map, list, and set columns are not accessible through the Data API.
You can’t create timeuuid columns, but you can use the Data API to manage values in timeuuid columns. For more information, see UUID types.
You can’t create varchar columns, but you can use the Data API to manage values in varchar columns. For more information, see Other scalar types.

Migrate to the Data API

Migrate from MongoDB

Connect

Client code example

Architecture

Command compatibility matrix

Indexing

ObjectIds and UUIDs

Vector search

Operators

Response modifiers

MongooseJS

Administration

Incompatible functionality

Migrate from CQL

Unsupported commands

Supported commands

CQL types

Support for existing tables

See also

Was this helpful?

Give Feedback