Busca en todas las páginas de la documentación
Amazon DocumentDB confuses people the same way RDS does, then adds one more twist. Like RDS, the AWS SDK provisions and operates the database but does not run your queries. The extra twist lives in the phrase "MongoDB-compatible" - a precise, load-bearing phrase that is easy to misread as "it is MongoDB." It is not.
DocumentDB is a database engine built by AWS that implements the MongoDB wire protocol. Your MongoDB drivers, your mongosh shell, and most of your query code work against it because it speaks the same language on the wire. But the engine underneath is AWS's own, built on the same distributed storage model as Aurora, not the MongoDB server.
This page builds the mental model behind that distinction, because every other page in this section is an application of two ideas: the control-plane / data-plane split, and what "wire-compatible" does and does not buy you.
insertOne, find, aggregations).@aws-sdk/client-docdb client never runs your document queries. It manages the cluster as infrastructure and hands you an endpoint; a normal MongoDB driver like pymongo or the node mongodb package does the querying.Start with the distinction the whole service is organized around, then layer the compatibility idea on top.
The control plane is the set of operations that manage the database as infrastructure. Creating a cluster, adding an instance, changing its size, taking a snapshot, restoring, adding a second region - these are control-plane actions, and every one of them is an AWS SDK call on the docdb client. They are administrative, relatively rare, and often slow because real compute and storage are provisioned behind them.
The data plane is the set of operations that read and write your documents. insertOne, find, an aggregation pipeline, a transaction - these run over a database connection using a MongoDB driver that speaks the MongoDB wire protocol. The AWS SDK is not involved. Your app connects to a hostname on port 27017 over TLS and behaves as it would against a MongoDB server.
Here is the control-plane half - the SDK creating a cluster and returning where it lives. Nothing here runs a query.
# --- Python (boto3) ---
import boto3
docdb = boto3.client("docdb", region_name="us-east-1")
# Control plane: create the cluster (this is ALL the SDK does for your data).
docdb.create_db_cluster(
DBClusterIdentifier="app-docdb",
Engine="docdb", # the DocumentDB engine, not "mongodb"
MasterUsername="appuser",
ManageMasterUserPassword=True, # password stored in Secrets Manager
StorageEncrypted=True,
)
print("creating app-docdb - the SDK's job ends at the endpoint")// --- TypeScript (AWS SDK v3) ---
import { DocDBClient, CreateDBClusterCommand } from "@aws-sdk/client-docdb";
const docdb = new DocDBClient({ region: "us-east-1" });
// Control plane: create the cluster (this is ALL the SDK does for your data).
await docdb.send(new CreateDBClusterCommand({
DBClusterIdentifier: "app-docdb",
Engine: "docdb", // the DocumentDB engine, not "mongodb"
MasterUsername: "appuser",
ManageMasterUserPassword: true, // password stored in Secrets Manager
StorageEncrypted: true,
}));
console.log("creating app-docdb - the SDK's job ends at the endpoint");Once the cluster has an instance and is available, your app connects with a MongoDB driver. That connection is the data plane, and it never touches the AWS SDK.
Two mechanics matter: the cluster topology, and what "wire-compatible" means once you are connected.
Topology mirrors Aurora. A DocumentDB cluster owns the shared, auto-replicated storage volume; instances are the compute you attach to it. You call CreateDBCluster to create the cluster, then CreateDBInstance one or more times with that DBClusterIdentifier. The first instance becomes the writer; the rest are readers. The cluster exposes two DNS names: a cluster endpoint that always points at the current writer, and a reader endpoint that load-balances read-only connections across replicas. Both listen on port 27017. This is the same separation of storage and compute that Aurora uses, which is why adding a reader takes seconds and does not copy data.
Wire compatibility is what lets your driver connect. DocumentDB implements the MongoDB wire protocol at a specific version - you choose 3.6, 4.0, or 5.0 compatibility through the cluster's EngineVersion. Because the protocol matches, pymongo, the node mongodb driver, mongosh, and most tools work unchanged. You point the same connection string at the cluster endpoint and run the same find and insert calls.
Here is the data-plane half. Note the fence is labeled as a MongoDB driver, not the AWS SDK.
# --- Python (pymongo driver - NOT the AWS SDK) ---
from pymongo import MongoClient
# host came from DescribeDBClusters; the SDK plays no part in this query.
client = MongoClient(
"app-docdb.cluster-abc123.us-east-1.docdb.amazonaws.com",
port=27017, tls=True, tlsCAFile="global-bundle.pem",
username="appuser", password="from-secrets-manager",
retryWrites=False, # DocumentDB does not support retryable writes
)
client["shop"]["orders"].insert_one({"sku": "A-1", "qty": 2})Compatibility is partial. Some MongoDB operators, commands, and features are not implemented, and the supported set differs by version. The engine is AWS's own, so behavior around indexes, aggregation stages, and transactions can differ from a real MongoDB server. The practical habit: validate the specific operators and commands your application uses against the version you provision, rather than assuming full parity.
Three points extend the base model.
There is no Data API. Aurora has one deliberate exception where the SDK runs your SQL over HTTPS. DocumentDB has no equivalent - every document read and write goes through a MongoDB driver over a persistent TLS connection. That makes connection management your responsibility, and it is why connection pooling and driver reuse matter more here than they would with a connectionless interface.
Elastic clusters are the "scale-out" shape. Standard DocumentDB scales compute by instance size and by adding readers. For workloads that need horizontal write scaling, DocumentDB elastic clusters shard data across capacity units and are managed through a separate client, @aws-sdk/client-docdb-elastic, with its own CreateCluster call sized by shardCapacity and shardCount. DocumentDB does not offer an Aurora-Serverless-v2-style single-instance auto-scaler; elastic clusters are the closest "pay for variable capacity" model, and they get their own page.
Global clusters extend it across regions. CreateGlobalCluster turns a primary cluster into the write region of a multi-region topology with up to five read-only secondary regions and low replication lag - the DR and read-locality story, covered on its own page.
The habit to internalize: before you write DocumentDB code, decide which plane you are in. Creating, sizing, snapshotting, restoring, or replicating is a docdb (or docdb-elastic) SDK call. Reading or writing documents is a MongoDB driver over TLS. Almost every question in this section resolves the moment you name the plane.
docdb client provisions and operates the cluster; a MongoDB driver runs find, insert, and aggregations over the endpoint.CreateDBCluster is enough to connect." - A cluster owns storage but has no compute until you add an instance with CreateDBInstance. You connect to an instance-backed endpoint, not to bare storage.No. DocumentDB is an AWS-built database engine that implements the MongoDB wire protocol, so MongoDB drivers and tools can connect to it. The underlying engine, distributed storage, and supported feature set are AWS's own and differ from a MongoDB server.
No. The @aws-sdk/client-docdb client only provisions and operates the cluster - create, size, snapshot, restore, replicate. Your app runs find, insertOne, and aggregations through a MongoDB driver like pymongo or the node mongodb package over the cluster endpoint.
It means DocumentDB speaks the same protocol on the wire that a MongoDB server of a given version (3.6, 4.0, or 5.0) speaks. Your drivers and query calls work unchanged, but only for the operators and commands DocumentDB implements - compatibility is partial, not total.
Closely. A DocumentDB cluster owns shared, auto-replicated storage, and instances are compute attached to it - one writer plus readers, addressed by a cluster endpoint and a reader endpoint. Adding a reader attaches to the shared volume rather than copying data.
No. Unlike Aurora, DocumentDB has no HTTPS Data API. Every read and write goes through a MongoDB driver over a persistent TLS connection on port 27017, which is why connection management and pooling matter.
Choose the cluster's EngineVersion for the compatibility your app needs (5.0 is the most current). Then validate the specific operators, aggregation stages, and index types you rely on against that version, because the supported set differs between versions.
Standard clusters scale by instance size and added readers. For horizontal write scaling, use DocumentDB elastic clusters, a sharded model managed through the separate docdb-elastic client and sized by shard capacity and count. There is no single-instance serverless auto-scaler like Aurora Serverless v2.
Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).
Revisado por Chris St. John·Última actualización: 24 jul 2026