MongoDB Wire Protocol

On this page

Introduction

TCP/IP Socket
Messages Types and Formats
Standard Message Header
Client Request Messages
Database Response Messages

This version of the documentation is archived and no longer supported. View the current documentation to learn how to upgrade your version of MongoDB.

Note

This MongoDB Wire Protocol Specification is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 United States License. You may not use or adapt this material for any commercial purpose, such as to create a commercial database or database-as-a-service offering.

Introduction

The MongoDB Wire Protocol is a simple socket-based, request-response style protocol. Clients communicate with the database server through a regular TCP/IP socket.

TCP/IP Socket

Clients should connect to the database with a regular TCP/IP socket. There is no connection handshake.

Port

The default port number for mongod and mongos instances is 27017. The port number for mongod and mongos is configurable and may vary.

Byte Ordering

All integers in the MongoDB wire protocol use little-endian byte order: that is, least-significant byte first.

Messages Types and Formats

There are two types of messages: client requests and database responses.

Note

This page uses a C-like struct to describe the message structure.
The types used in this document (cstring, int32, etc.) are the same as those defined in the BSON specification.
To denote repetition, the document uses the asterisk notation from the BSON specification. For example, int64* indicates that one or more of the specified type can be written to the socket, one after another.
The standard message header is typed as MsgHeader. Integer constants are in capitals (e.g. ZERO for the integer value of 0).

Standard Message Header

In general, each message consists of a standard message header followed by request-specific data. The standard message header is structured as follows:

struct MsgHeader {
    int32   messageLength; // total message size, including this
    int32   requestID;     // identifier for this message
    int32   responseTo;    // requestID from the original request
                           //   (used in responses from db)
    int32   opCode;        // request type - see table below for details
}

Field	Description
`messageLength`	The total size of the message in bytes. This total includes the 4 bytes that holds the message length.
`requestID`	A client or database-generated identifier that uniquely identifies this message. For the case of client-generated messages (e.g. OP_QUERY and OP_GET_MORE), it will be returned in the `responseTo` field of the OP_REPLY message. Clients can use the `requestID` and the `responseTo` fields to associate query responses with the originating query.
`responseTo`	In the case of a message from the database, this will be the `requestID` taken from the OP_QUERY or OP_GET_MORE messages from the client. Clients can use the `requestID` and the `responseTo` fields to associate query responses with the originating query.
`opCode`	Type of message. See Request Opcodes for details.

Request Opcodes

Note

Starting with MongoDB 2.6 and maxWireVersion 3, MongoDB drivers use the database commands insert, update, and delete instead of OP_INSERT, OP_UPDATE, and OP_DELETE for acknowledged writes. Most drivers continue to use opcodes for unacknowledged writes.

In version 4.2, MongoDB removes the deprecated internal OP_COMMAND and OP_COMMANDREPLY protocol.

The following are the supported opCode:

Opcode Name	Value	Comment
`OP_REPLY`	1	Reply to a client request. `responseTo` is set.
`OP_UPDATE`	2001	Update document.
`OP_INSERT`	2002	Insert new document.
`RESERVED`	2003	Formerly used for OP_GET_BY_OID.
`OP_QUERY`	2004	Query a collection.
`OP_GET_MORE`	2005	Get more data from a query. See Cursors.
`OP_DELETE`	2006	Delete documents.
`OP_KILL_CURSORS`	2007	Notify database that the client has finished with the cursor.
`OP_COMPRESSED`	2012	Wraps other opcodes using compression
`OP_MSG`	2013	Send a message using the format introduced in MongoDB 3.6.

Client Request Messages

Clients can send request messages that specify all but the OP_REPLY opCode. OP_REPLY is reserved for use by the database.

Only the OP_QUERY and OP_GET_MORE messages result in a response from the database. There will be no response sent for any other message.

You can determine if a message was successful with a getLastError command.

OP_UPDATE

The OP_UPDATE message is used to update a document in a collection. The format of a OP_UPDATE message is the following:

struct OP_UPDATE {
    MsgHeader header;             // standard message header
    int32     ZERO;               // 0 - reserved for future use
    cstring   fullCollectionName; // "dbname.collectionname"
    int32     flags;              // bit vector. see below
    document  selector;           // the query to select the document
    document  update;             // specification of the update to perform
}

Field	Description
`header`	Message header, as described in Standard Message Header.
`ZERO`	Integer value of 0. Reserved for future use.
`fullCollectionName`	The full collection name; i.e. namespace. The full collection name is the concatenation of the database name with the collection name, using a `.` for the concatenation. For example, for the database `foo` and the collection `bar`, the full collection name is `foo.bar`.
`flags`	Bit vector to specify flags for the operation. The bit values correspond to the following: `0` corresponds to Upsert. If set, the database will insert the supplied object into the collection if no matching document is found. `1` corresponds to MultiUpdate.If set, the database will update all matching objects in the collection. Otherwise only updates first matching document. `2`-`31` are reserved. Must be set to 0.
`selector`	BSON document that specifies the query for selection of the document to update.
`update`	BSON document that specifies the update to be performed. For information on specifying updates see the Update Operations documentation.

There is no response to an OP_UPDATE message.

OP_INSERT

The OP_INSERT message is used to insert one or more documents into a collection. The format of the OP_INSERT message is

struct {
    MsgHeader header;             // standard message header
    int32     flags;              // bit vector - see below
    cstring   fullCollectionName; // "dbname.collectionname"
    document* documents;          // one or more documents to insert into the collection
}

Field	Description
`header`	Message header, as described in Standard Message Header.
`flags`	Bit vector to specify flags for the operation. The bit values correspond to the following: `0` corresponds to ContinueOnError. If set, the database will not stop processing a bulk insert if one fails (eg due to duplicate IDs). This makes bulk insert behave similarly to a series of single inserts, except lastError will be set if any insert fails, not just the last one. If multiple errors occur, only the most recent will be reported by getLastError. (new in 1.9.1) `1`-`31` are reserved. Must be set to 0.
`fullCollectionName`	The full collection name; i.e. namespace. The full collection name is the concatenation of the database name with the collection name, using a `.` for the concatenation. For example, for the database `foo` and the collection `bar`, the full collection name is `foo.bar`.
`documents`	One or more documents to insert into the collection. If there are more than one, they are written to the socket in sequence, one after another.

There is no response to an OP_INSERT message.

OP_QUERY

The OP_QUERY message is used to query the database for documents in a collection. The format of the OP_QUERY message is:

struct OP_QUERY {
    MsgHeader header;                 // standard message header
    int32     flags;                  // bit vector of query options.  See below for details.
    cstring   fullCollectionName ;    // "dbname.collectionname"
    int32     numberToSkip;           // number of documents to skip
    int32     numberToReturn;         // number of documents to return
                                      //  in the first OP_REPLY batch
    document  query;                  // query object.  See below for details.
  [ document  returnFieldsSelector; ] // Optional. Selector indicating the fields
                                      //  to return.  See below for details.
}

Field

Description

header

Message header, as described in Standard Message Header.

flags

Bit vector to specify flags for the operation. The bit values correspond to the following:

0 is reserved. Must be set to 0.
1 corresponds to TailableCursor. Tailable means cursor is not closed when the last data is retrieved. Rather, the cursor marks the final object's position. You can resume using the cursor later, from where it was located, if more data were received. Like any "latent cursor", the cursor may become invalid at some point (CursorNotFound) – for example if the final object it references were deleted.
2 corresponds to SlaveOk. Allow query of replica slave. Normally these return an error except for namespace "local".
3 corresponds to OplogReplay. Starting in MongoDB 4.4, you need not specify this flag because the optimization automatically happens for eligible queries on the oplog. See oplogReplay for more information.
4 corresponds to NoCursorTimeout. The server normally times out idle cursors after an inactivity period (10 minutes) to prevent excess memory use. Set this option to prevent that.
5 corresponds to AwaitData. Use with TailableCursor. If we are at the end of the data, block for a while rather than returning no data. After a timeout period, we do return as normal.
6 corresponds to Exhaust. Stream the data down full blast in multiple "more" packages, on the assumption that the client will fully read all data queried. Faster when you are pulling a lot of data and know you want to pull it all down. Note: the client is not allowed to not read all the data unless it closes the connection.
7 corresponds to Partial. Get partial results from a mongos if some shards are down (instead of throwing an error)
8-31 are reserved. Must be set to 0.

fullCollectionName

The full collection name; i.e. namespace. The full collection name is the concatenation of the database name with the collection name, using a . for the concatenation. For example, for the database foo and the collection bar, the full collection name is foo.bar.

numberToSkip

Sets the number of documents to omit - starting from the first document in the resulting dataset - when returning the result of the query.

numberToReturn

Limits the number of documents in the first OP_REPLY message to the query. However, the database will still establish a cursor and return the cursorID to the client if there are more results than numberToReturn. If the client driver offers 'limit' functionality (like the SQL LIMIT keyword), then it is up to the client driver to ensure that no more than the specified number of document are returned to the calling application. If numberToReturn is 0, the db will use the default return size. If the number is negative, then the database will return that number and close the cursor. No further results for that query can be fetched. If numberToReturn is 1 the server will treat it as -1 (closing the cursor automatically).

query

BSON document that represents the query. The query will contain one or more elements, all of which must match for a document to be included in the result set. Possible elements include $query, $orderby, $hint, and $explain.

returnFieldsSelector

Optional. BSON document that limits the fields in the returned documents. The returnFieldsSelector contains one or more elements, each of which is the name of a field that should be returned, and and the integer value 1. In JSON notation, a returnFieldsSelector to limit to the fields a, b and c would be:

{ a : 1, b : 1, c : 1}

The database will respond to an OP_QUERY message with an OP_REPLY message.

OP_GET_MORE

The OP_GET_MORE message is used to query the database for documents in a collection. The format of the OP_GET_MORE message is:

struct {
    MsgHeader header;             // standard message header
    int32     ZERO;               // 0 - reserved for future use
    cstring   fullCollectionName; // "dbname.collectionname"
    int32     numberToReturn;     // number of documents to return
    int64     cursorID;           // cursorID from the OP_REPLY
}

Field	Description
`header`	Message header, as described in Standard Message Header.
`ZERO`	Integer value of 0. Reserved for future use.
`fullCollectionName`	The full collection name; i.e. namespace. The full collection name is the concatenation of the database name with the collection name, using a `.` for the concatenation. For example, for the database `foo` and the collection `bar`, the full collection name is `foo.bar`.
`numberToReturn`	Limits the number of documents in the first OP_REPLY message to the query. However, the database will still establish a cursor and return the `cursorID` to the client if there are more results than `numberToReturn`. If the client driver offers 'limit' functionality (like the SQL LIMIT keyword), then it is up to the client driver to ensure that no more than the specified number of document are returned to the calling application. If `numberToReturn` is `0`, the db will used the default return size.
`cursorID`	Cursor identifier that came in the OP_REPLY. This must be the value that came from the database.

The database will respond to an OP_GET_MORE message with an OP_REPLY message.

OP_DELETE

The OP_DELETE message is used to remove one or more documents from a collection. The format of the OP_DELETE message is:

struct {
    MsgHeader header;             // standard message header
    int32     ZERO;               // 0 - reserved for future use
    cstring   fullCollectionName; // "dbname.collectionname"
    int32     flags;              // bit vector - see below for details.
    document  selector;           // query object.  See below for details.
}

Field	Description
`header`	Message header, as described in Standard Message Header.
`ZERO`	Integer value of 0. Reserved for future use.
`fullCollectionName`	The full collection name; i.e. namespace. The full collection name is the concatenation of the database name with the collection name, using a `.` for the concatenation. For example, for the database `foo` and the collection `bar`, the full collection name is `foo.bar`.
`flags`	Bit vector to specify flags for the operation. The bit values correspond to the following: `0` corresponds to SingleRemove. If set, the database will remove only the first matching document in the collection. Otherwise all matching documents will be removed. `1`-`31` are reserved. Must be set to 0.
`selector`	BSON document that represent the query used to select the documents to be removed. The selector will contain one or more elements, all of which must match for a document to be removed from the collection.

There is no response to an OP_DELETE message.

OP_KILL_CURSORS

The OP_KILL_CURSORS message is used to close an active cursor in the database. This is necessary to ensure that database resources are reclaimed at the end of the query. The format of the OP_KILL_CURSORS message is:

struct {
    MsgHeader header;            // standard message header
    int32     ZERO;              // 0 - reserved for future use
    int32     numberOfCursorIDs; // number of cursorIDs in message
    int64*    cursorIDs;         // sequence of cursorIDs to close
}

Field	Description
`header`	Message header, as described in Standard Message Header.
`ZERO`	Integer value of 0. Reserved for future use.
`numberOfCursorIDs`	The number of cursor IDs that are in the message.
`cursorIDs`	"Array" of cursor IDs to be closed. If there are more than one, they are written to the socket in sequence, one after another.

If a cursor is read until exhausted (read until OP_QUERY or OP_GET_MORE returns zero for the cursor id), there is no need to kill the cursor.

OP_COMPRESSED

New in version MongoDB: 3.4

Any opcode can be compressed and wrapped in an OP_COMPRESSED header. The OP_COMPRESSED message contains the original compressed opcode message alongside the metadata necessary to process and decompress it.

The format of the OP_COMPRESSED message is:

struct {
    MsgHeader header;            // standard message header
    int32  originalOpcode;     // value of wrapped opcode
    int32  uncompressedSize;   // size of deflated compressedMessage, excluding MsgHeader
    uint8  compressorId;       // ID of compressor that compressed message
    char    *compressedMessage;  // opcode itself, excluding MsgHeader
}

Field	Description
`MsgHeader`	Message header, as described in Standard Message Header.
`originalOpcode`	Contains the value of the wrapped opcode.
`uncompressedSize`	The size of the deflated `compressedMessage`, which excludes the `MsgHeader`.
`compressorId`	The ID of the compressor that compressed the message. A list of `compressorId` values is provided below.
`compressedMessage`	The opcode itself, excluding the `MsgHeader`.

Each compressor is assigned a predefined compressor ID as follows:

compressorId	Handshake Value	Description
`0`	noop	The content of the message is uncompressed. This is used for testing.
`1`	snappy	The content of the message is compressed using snappy.
`2`	zlib	The content of the message is compressed using zlib.
`3`	zstd	The content of the message is compressed using zstd.
`4-255`	reserved	Reserved for future use.

OP_MSG

New in version MongoDB: 3.6

OP_MSG is an extensible message format designed to subsume the functionality of other opcodes. This opcode has the following format:

OP_MSG {
    MsgHeader header;          // standard message header
    uint32 flagBits;           // message flags
    Sections[] sections;       // data sections
    optional<uint32> checksum; // optional CRC-32C checksum
}

Field	Description
`header`	Standard message header, as described in Standard Message Header.
`flagBits`	An integer bitmask containing message flags, as described in Flag Bits.
`sections`	Message body sections, as described in Sections.
`checksum`	An optional CRC-32C checksum, as described in Checksum.

Flag Bits

The flagBits integer is a bitmask encoding flags that modify the format and behavior of OP_MSG.

The first 16 bits (0-15) are required and parsers MUST error if an unknown bit is set.

The last 16 bits (16-31) are optional, and parsers MUST ignore any unknown set bits. Proxies and other message forwarders MUST clear any unknown optional bits before forwarding messages.

Bit	Name	Request	Response	Description
0	`checksumPresent`	✓	✓	The message ends with 4 bytes containing a CRC-32C [1] checksum. See Checksum for details.
1	`moreToCome`	✓	✓	Another message will follow this one without further action from the receiver. The receiver MUST NOT send another message until receiving one with `moreToCome` set to 0 as sends may block, causing deadlock. Requests with the `moreToCome` bit set will not receive a reply. Replies will only have this set in response to requests with the `exhaustAllowed` bit set.
16	`exhaustAllowed`	✓		The client is prepared for multiple replies to this request using the `moreToCome` bit. The server will never produce replies with the `moreToCome` bit set unless the request has this bit set. This ensures that multiple replies are only sent when the network layer of the requester is prepared for them. Important MongoDB 3.6 ignores this flag, and will respond with a single message.

Sections

An OP_MSG message contains one or more sections. Each section starts with a kind byte indicating its type. Everything after the kind byte constitutes the section's payload.

The available kinds of sections follow.

Kind 0: Body

A body section is encoded as a single BSON object. The size in the BSON object also serves as the size of the section. This section kind is the standard command request and reply body.

All top-level fields MUST have a unique name.

Kind 1: Document Sequence

Type	Description
int32	Size of the section in bytes.
C String	Document sequence identifier. In all current commands this field is the (possibly nested) field that it is replacing from the body section. This field MUST NOT also exist in the body section.
Zero or more BSON objects	Objects are sequenced back to back with no separators. Each object is limited to the `maxBSONObjectSize` of the server. The combination of all objects is not limited to `maxBSONObjSize`. The document sequence ends once `size` bytes have been consumed. Parsers MAY choose to merge these objects into the body as an array at the path specified by the sequence identifier when converting to language-level objects.

Checksum

Each message MAY end with a CRC-32C [1] checksum that covers all bytes in the message except for the checksum itself.

Starting in MongoDB 4.2:

mongod instances, mongos instances, and mongo shell instances will exchange messages with checksums if not using TLS/SSL connection.
mongod instances, mongos instances, and mongo shell instances will skip the checksum if using TLS/SSL connection.

Drivers and older binaries will ignore the checksum if presented with messages with checksum.

The presence of a checksum is indicated by the checksumPresent flag bit.

Database Response Messages

OP_REPLY

The OP_REPLY message is sent by the database in response to an OP_QUERY or OP_GET_MORE message. The format of an OP_REPLY message is:

struct {
    MsgHeader header;         // standard message header
    int32     responseFlags;  // bit vector - see details below
    int64     cursorID;       // cursor id if client needs to do get more's
    int32     startingFrom;   // where in the cursor this reply is starting
    int32     numberReturned; // number of documents in the reply
    document* documents;      // documents
}

Field	Description
`header`	Message header, as described in Standard Message Header.
`responseFlags`	Bit vector to specify flags. The bit values correspond to the following: `0` corresponds to CursorNotFound. Is set when `getMore` is called but the cursor id is not valid at the server. Returned with zero results. `1` corresponds to QueryFailure. Is set when query failed. Results consist of one document containing an "$err" field describing the failure. `2` corresponds to ShardConfigStale. Drivers should ignore this. Only `mongos` will ever see this set, in which case, it needs to update config from the server. `3` corresponds to AwaitCapable. Is set when the server supports the AwaitData Query option. If it doesn't, a client should sleep a little between getMore's of a Tailable cursor. Mongod version 1.6 supports AwaitData and thus always sets AwaitCapable. `4`-`31` are reserved. Ignore.
`cursorID`	The `cursorID` that this OP_REPLY is a part of. In the event that the result set of the query fits into one OP_REPLY message, `cursorID` will be 0. This `cursorID` must be used in any OP_GET_MORE messages used to get more data, and also must be closed by the client when no longer needed via a OP_KILL_CURSORS message.
`startingFrom`	Starting position in the cursor.
`numberReturned`	Number of documents in the reply.
`documents`	Returned documents.

Footnotes

[1]	(1, 2) 32-bit CRC computed with the Castagnoli polynomial as described by https://tools.ietf.org/html/rfc4960#page-140.

Back

Collation Locales and Default Parameters

Log Messages

Note

Introduction

TCP/IP Socket

Port

Byte Ordering

Messages Types and Formats

Note

Standard Message Header

Request Opcodes

Note

Client Request Messages

OP_UPDATE

OP_INSERT

OP_QUERY

OP_GET_MORE

OP_DELETE

OP_KILL_CURSORS

OP_COMPRESSED

OP_MSG

Flag Bits

Important

Sections

Kind 0: Body

Kind 1: Document Sequence

Checksum

Database Response Messages

OP_REPLY