- Reference >
- MongoDB Wire Protocol
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 data in the MongoDB wire protocol is little-endian.
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
}
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. |
Request Opcodes¶
The following are the supported opCode:
Opcode Name | Value | Comment |
---|---|---|
OP_REPLY | 1 | Reply to a client request. responseTo is set. |
OP_MSG | 1000 | Generic msg command followed by a string. |
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. |
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:
|
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:
|
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:
|
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, $explain, and $snapshot. |
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:
|
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_MSG¶
Deprecated since version Drivers: do not need to implement OP_MSG.
OP_MSG sends a diagnostic message to the database. The database sends back a fixed response. The format is:
struct {
MsgHeader header; // standard message header
cstring message; // message for the database
}
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:
|
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. |
Thank you for your feedback!
We're sorry! You can Report a Problem to help us improve this page.