- 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:
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¶
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.
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. |
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:
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
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:
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 |
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:
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:
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:
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.
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:
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. |