Docs4dev
Docs
mongodb / v3.6 / reference / reference-mongodb-wire-protocol.html

MongoDB Wire Protocol

On this page

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.

Warning

OP_COMMAND and OP_COMMANDREPLY are cluster internal and should not be implemented by clients or drivers.

Changed in version 3.6: The OP_COMMAND and OP_COMMANDREPLY format and protocol are deprecated and may be removed in a future release of MongoDB.

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_COMMAND 2010 Cluster internal protocol representing a command request.
OP_COMMANDREPLY 2011 Cluster internal protocol representing a reply to an OP_COMMAND.
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 from the MongoDB Manual.

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. Internal replication use only - driver should not set.
  • 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