Migrate to the Data API from MongoDB
If you are familiar with MongoDB’s API, you will find many similarities in the Data API. However, the Data API isn’t fully compatible with MongoDB’s API.
To help you migrate your applications from MongoDB to Astra, this page describes key similarities and differences between the MongoDB API and the Data API.
Connect to the Data API
You can interact with the Data API directly through HTTP or through one of the clients that DataStax provides.
While there are many MongoDB drivers, the MongoDB Data API and HTTP endpoints are deprecated. DataStax continues to support HTTP as a viable option for interacting with the Data API.
Both the MongoDB drivers and the 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.
-
The Data API 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 Data API clients do not cancel a running server job upon hitting the |
Client code example
Data API client code is similar to MongoDB driver code. The following examples compare some MongoDB Node.js driver code with Data API 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
-
Data API 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 = "APPLICATION_TOKEN";
const endpoint = "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 the Data API both use a four-layer architecture, the names of these layers and some underlying functionality are different.
These differences exist because the Astra 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 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. |
Command compatibility matrix
The following table compares command compatibility at different architecture layers:
| Astra layer | MongoDB command | Data API command | Comments |
|---|---|---|---|
Databases |
Access a database |
||
Keyspaces |
See Database |
In the Data API, 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 |
||
Collections |
List collections |
The Data API clients also provide a List collection names command. |
|
Collections |
Delete a collection |
The Data API doesn’t support methods like |
|
Documents |
Insert one |
||
Documents |
Insert many |
The Data API supports |
|
Documents |
Find one |
||
Documents |
Find multiple |
There are many nuances to the |
|
Documents |
Find distinct |
This command is a client-side operation that can have performance and billing implications when searching large datasets. The Data API doesn’t offer direct support for this command in HTTP.
However, you can use Find with |
|
Documents |
Update one |
For a more verbose response that includes the original or updated document, use the Data API Find one and update command.
|
|
Documents |
Update many |
|
|
Documents |
Replace one |
The 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 |
|
Documents |
Count documents |
The Data API supports filtered and unfiltered counting. This command isn’t recommended for counting large datasets. For more information, see Count documents. |
|
Documents |
Estimated document count |
||
Documents |
Delete one |
For a more verbose response that includes the deleted document, use the Data API Find one and delete command. |
|
Documents |
Delete multiple |
Indexing
Indexing is significantly different in MongoDB and the Data API:
| MongoDB function | Data API function | Comments |
|---|---|---|
Multiple index types |
Single field indexes only |
|
Automatic indexing for |
Automatic indexing for all document properties with the option for selective indexing. |
|
Dynamic index management |
No dynamic index management. |
In Astra, indexing is a collection-level configuration that you set when you create a collection. Collection settings are immutable after creation. |
ObjectIds and UUIDs
The Data API supports a variety of _id types, including MongoDB’s ObjectId type.
For more information, see Document IDs.
Vector search
Astra supports Vector search similar to MongoDB Atlas Vector Search.
However, whereas Atlas Vector Search is part of an aggregation pipeline, Astra’s vector search is directly integrated in commands, like Find, as a sort clause.
Additionally, Astra 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 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 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
$geoand geometry specifiers -
Miscellaneous operators
$comment,$rand, and$natural
The Data API doesn’t support $nor, but you can use compound $not and $and operators instead.
For more information and examples, see Filter operators for collections, Update operators for collections, $date, and the references for the methods that use these operators, such as Find.
Response modifiers
The Data API offers options to modify the order and content of a response beyond query filters:
-
limit -
sort -
skip -
projection(including$slice)
|
In the Data API, some combinations of |
Cursors and pagination
Like the MongoDB drivers, the Data API clients use cursors to manage large responses. Over HTTP, the 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 Data API with MongooseJS. For more information, see Integrate MongooseJS with Astra DB Serverless.
Administration
You can use the 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 cannot 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 |
|---|---|---|
Some DevOps API functions are also available through the Data API clients. For more information, see Databases reference. |
||
For more information, see Integrate HashiCorp Terraform with Astra DB Serverless. |
||
Incompatible functionality
The Data API doesn’t provide a mechanism for change streams, but you can use CDC for Astra DB separately from the Data API. To enable this feature for Serverless (Vector) databases, contact DataStax Support.
The following MongoDB driver functionality isn’t available in the Data API:
