MongoDB Wire Protocol
- MongoDB Wire Protocol is a protocol used for communication between mongo client and server. The protocol is directly based on TCP.
- No application-level handshake is required to establish a connection
- All data is little-endian
standard message header
All messages have the same header
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
}
OpCode has the following:
| Name | Value | Comment |
| OP_REPLY | 1 | Reply to a client request. responseTo is set. |
| OP_MSG | 1000 | Generic msg command followed by a string. |
| ON_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. |
The write driver only uses the first 9
client request message
The client can send other messages except OP_REPLY to the server. Only OP_QUERY and OP_GET_MORE have response messages, and the rest have none. You can use getLastError to judge whether commands such as update and delete are executed successfully.
ON_UPDATE
update document, format:
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
}
flags : bit vector, the following is the meaning of each bit:
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: reserved, must be 0
OP_INSERT
insert document, format:
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
}
flags：
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.
1-31：reserved，must 0
OP_QUERY
query document, format:
struct OP_QUERY {
MsgHeader header; // standard message header
int32 flags; // bit vector of query options.
cstring fullCollectionName ; // "dbname.collectionname"
int32 numberToSkip; // number of documents to skip，starting from the first document in the resulting dataset
int32 numberToReturn; // number of documents to return
// in the first OP_REPLY batch
document query; // query object.
[ document returnFieldsSelector; ] // Optional. Selector indicating the fields
// to return.
}
flags：
0：reserved，must 0
1：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：reserved，must 0
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).
OP_QUERY will generate an OP_REPLY response
OP_GET_MORE
used to query the database for documents in a collection，格式：
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
}
OP_GET_MORE will produce an OP_REPLY response
OP_DELETE
remove document, format:
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.
}
flags：
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：reserved，must 0
OP_KILL_CURSORS
used to close an active cursor in the database，格式：
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_QUERY or OP_GET_MORE returns zero for the cursor id), there is no need to kill the cursor.
OP_MSG
Deprecated is deprecated
OP_COMMAND
This is a cluster internal message
The above is all the request message
server response message
OP_REPLY
The OP_REPLY message is sent by the database in response to an OP_QUERY or OP_GET_MORE message，格式
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
}
responseFlags：
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：reserved，must 0
OP_COMMANDREPLY
集群内部消息
以上document类型的字段都是BSON类型的，参考http://bsonspec.org/spec.html