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 HCD, 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 timeout limit. Instead, the client stops waiting for the server-side operation and proceeds to the next client-side command.

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 HCD 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	HCD 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

HCD 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:

HCD layer MongoDB command Data API command Comments

HCD layer	MongoDB command	Data API command	Comments
Databases	Access a database	Connect to a database
Keyspaces	See Database	Connect to a database
Collections	Create a collection	Create a collection
Collections	Access a collection	Create a collection
Collections	List collections	List collection metadata	The Data API clients also provide a List collection names command.
Collections	Delete a collection	Drop a collection	The Data API doesn’t support methods like `collection.rename()`. Collection configuration is immutable after creation.
Documents	Insert one	Insert one
Documents	Insert many	Insert many	The Data API 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.
Documents	Find distinct	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 `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 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 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	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	Estimate document count
Documents	Delete one	Delete one	For a more verbose response that includes the deleted document, use the 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

Collections

Create a collection

Collections

Access a collection

Create a collection

Collections

List collections

List collection metadata

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

Collections

Delete a collection

Drop a collection

The Data API doesn’t support methods like collection.rename(). Collection configuration is immutable after creation.

Documents

Insert one

Documents

Insert many

The Data API 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.

Documents

Find distinct

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 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 Data API Find one and update command.

upsert is supported.

Documents

Update many

upsert is supported.

Documents

Replace one

Find one and replace

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 findOneAndReplace.

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

Estimate 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

Delete many

Indexing

Indexing is significantly different in MongoDB and the Data API:

MongoDB function Data API function Comments

MongoDB function	Data API 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 HCD, 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 HCD, 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

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

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 $geo and 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 filter, limit, sort, and skip are incompatible. For more information, see Sort clauses for collections.

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.

Migrate to the Data API from MongoDB

Connect to the Data API

Client code example

Architecture

Command compatibility matrix

Indexing

ObjectIds and UUIDs

Vector search

Operators

Response modifiers

Was this helpful?

Give Feedback