MongoDB Wire Protocol

Introduction

The MongoDB Wire Protocol is a simple socket-based, request-responsestyle protocol. Clients communicate with the database server through aregular 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 mongosinstances is 27017. The port number for mongod andmongos 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 messagestructure.
• The types used in this document (cstring, int32, etc.) arethe same as those defined in the BSON specification.
• To denote repetition, the document uses the asterisk notation fromthe BSON specification.For example, int64* indicates that one or more of thespecified type can be written to the socket, one after another.
• The standard message header is typed as MsgHeader. Integerconstants are in capitals (e.g. ZERO for the integer value of0).

Standard Message Header

In general, each message consists of a standard message header followedby request-specific data. The standard message header is structured asfollows:

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
}

Request Opcodes

Note

Starting with MongoDB 2.6 and maxWireVersion 3,MongoDB drivers use the database commandsinsert, update, and deleteinstead of OP_INSERT, OP_UPDATE, and OP_DELETE foracknowledged writes. Most drivers continue to use opcodes forunacknowledged writes.

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

The following are the supported opCode:

Client Request Messages

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

Only the OP_QUERY andOP_GET_MORE messages result in aresponse from the database. There will be no response sent for any othermessage.

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. Theformat 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
}

There is no response to an OP_UPDATE message.

OP_INSERT

The OP_INSERT message is used to insert one or more documents into acollection. 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
}

There is no response to an OP_INSERT message.

OP_QUERY

The OP_QUERY message is used to query the database for documents in acollection. 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.
}

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

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

OP_GET_MORE

The OP_GET_MORE message is used to query the database for documents in acollection. 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
}

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

OP_DELETE

The OP_DELETE message is used to remove one or more documents from acollection. 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.
}

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 thedatabase. This is necessary to ensure that database resources arereclaimed at the end of the query. The format of the OP_KILL_CURSORSmessage 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
}

If a cursor is read until exhausted (read until OP_QUERYor OP_GET_MORE returns zerofor the cursor id), there is no need to kill the cursor.

OP_MSG

New in version MongoDB: 3.6

OP_MSG is an extensible message format designed to subsume thefunctionality 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
}

Flag Bits

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

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

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

Sections

An OP_MSG message contains one or more sections. Each section startswith a kind byte indicating its type. Everything after the kindbyte constitutes the section’s payload.

The available kinds of sections follow.

Kind 0: Body

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

All top-level fields MUST have a unique name.

Kind 1: Document Sequence

Checksum

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

Starting in MongoDB 4.2:

• mongod instances, mongos instances, andmongo shell instances will exchange messages withchecksums if not using TLS/SSL connection.
• mongod instances, mongos instances, andmongo shell instances will skip the checksum if usingTLS/SSL connection.

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

The presence of a checksum is indicated by the checksumPresent flagbit.

Database Response Messages

OP_REPLY

The OP_REPLY message is sent by the database in response to anOP_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
}

Footnotes