MongoDB Wire ProtocolMongoDB有线协议

On this page本页内容

Note注意

This MongoDB Wire Protocol Specification is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 United States License. 本MongoDB Wire协议规范根据知识共享署名非商业性ShareAlike 3.0美国许可证获得许可。You may not use or adapt this material for any commercial purpose, such as to create a commercial database or database-as-a-service offering.您不得将本材料用于任何商业目的，如创建商业数据库或数据库即服务产品。

Introduction介绍

The MongoDB Wire Protocol is a simple socket-based, request-response style protocol. MongoDB Wire协议是一个简单的基于套接字的请求-响应式协议。Clients communicate with the database server through a regular TCP/IP socket.客户端通过常规TCP/IP套接字与数据库服务器通信。

TCP/IP Socket套接字

Clients should connect to the database with a regular TCP/IP socket.客户端应使用常规TCP/IP套接字连接到数据库。

Port

The default port number for mongod and mongos instances is 27017. mongod和mongos实例的默认端口号为27017。The port number for mongod and mongos is configurable and may vary.mongod和mongos的端口号是可配置的，可能会有所不同。

Byte Ordering字节排序

All integers in the MongoDB wire protocol use little-endian byte order: that is, least-significant byte first.MongoDB wire协议中的所有整数都使用小端字节顺序：也就是说，最低有效字节优先。

Messages Types and Formats信息类型和格式

MongoDB uses the OP_MSG opcode for both client requests and database replies. MongoDB对客户端请求和数据库回复都使用OP_MSG操作码。There are several message formats used in older versions of MongoDB which have been deprecated in favor of OP_MSG.MongoDB的旧版本中使用了几种消息格式，这些格式已被弃用，取而代之的是OP_MSG。

Note注意

This page uses a C-like struct to describe the message structure.此页面使用类似C的结构来描述消息结构。

The types used in this document (for example, int32) are the same as those defined in the BSON specification.本文档中使用的类型（例如int32）与BSON规范中定义的类型相同。

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 the database)
    int32   opCode;
        // message type
}
Field字段Description描述
messageLengthThe total size of the message in bytes. 消息的总大小（字节）。This total includes the 4 bytes that holds the message length.这个总数包括保存消息长度的4个字节。
requestIDA client or database-generated identifier that uniquely identifies the message.客户端或数据库生成的唯一标识消息的标识符。
responseToThe requestID taken from the messages from the client.从客户端的消息中获取的requestID。
opCodeType of message. 消息类型。See Opcodes for details.有关详细信息，请参阅Opcodes。

Opcodes

MongoDB uses these opCode values:MongoDB使用以下opCode值：

Opcode Name名称Value值Comment议论
OP_COMPRESSED2012Wraps other opcodes using compression使用压缩包装其他操作码
OP_MSG2013Send a message using the standard format. 使用标准格式发送消息。Used for both client requests and database replies.用于客户端请求和数据库回复。
OP_REPLY
Deprecated in MongoDB 5.0. Removed in MongoDB 5.1.MongoDB 5.0中已弃用。在MongoDB 5.1中删除。		1Reply to a client request. responseTo is set.回复客户的请求。设置responseTo。
OP_UPDATE
Deprecated in MongoDB 5.0. Removed in MongoDB 5.1.MongoDB 5.0中已弃用。在MongoDB 5.1中删除。		2001Update document.更新文档。
OP_INSERT
Deprecated in MongoDB 5.0. Removed in MongoDB 5.1.MongoDB 5.0中已弃用。在MongoDB 5.1中删除。		2002Insert new document.插入新文档。
RESERVED2003Formerly used for OP_GET_BY_OID.以前用于OP_GET_BY_OID。
OP_QUERY
Deprecated in MongoDB 5.0. Removed in MongoDB 5.1.MongoDB 5.0中已弃用。在MongoDB 5.1中删除。		2004Query a collection.查询集合。
OP_GET_MORE
Deprecated in MongoDB 5.0. Removed in MongoDB 5.1.MongoDB 5.0中已弃用。在MongoDB 5.1中删除。		2005Get more data from a query. See Cursors.从查询中获取更多数据。请参阅游标。
OP_DELETE
Deprecated in MongoDB 5.0. Removed in MongoDB 5.1.MongoDB 5.0中已弃用。在MongoDB 5.1中删除。		2006Delete documents.删除文档。
OP_KILL_CURSORS
Deprecated in MongoDB 5.0. Removed in MongoDB 5.1.MongoDB 5.0中已弃用。在MongoDB 5.1中删除。		2007Notify database that the client has finished with the cursor.通知数据库客户端已完成游标。

OP_COMPRESSED

New in version MongoDB 3.4MongoDB 3.4中的新增

Any opcode can be compressed and wrapped in an OP_COMPRESSED header. 任何操作码都可以被压缩并包装在OP_COMPRESSED头中。The OP_COMPRESSED message contains the original compressed opcode message alongside the metadata necessary to process and decompress it.OP_COMPRESSED消息包含原始的压缩操作码消息，以及处理和解压缩它所需的元数据。

The format of the OP_COMPRESSED message is:OP_COMPRESSED消息的格式为：

struct {
    MsgHeader header;
            // standard message header
    int32  originalOpcode;
       // value of wrapped opcode
    int32  uncompressedSize;
     // size of deflated compressedMessage, excluding MsgHeader
    uint8  compressorId;
         // ID of compressor that compressed message
    char
    *compressedMessage;  // opcode itself, excluding MsgHeader
}
Field字段Description描述
MsgHeaderMessage header, as described in Standard Message Header.消息头，如标准消息头中所述。
originalOpcodeContains the value of the wrapped opcode.包含包装的操作码的值。
uncompressedSizeThe size of the deflated compressedMessage, which excludes the MsgHeader.压平的compressedMessage的大小，不包括MsgHeader。
compressorIdThe ID of the compressor that compressed the message. 压缩消息的压缩程序的ID。A list of compressorId values is provided below.下面提供了compressorId值列表。
compressedMessageThe opcode itself, excluding the MsgHeader.操作码本身，不包括MsgHeader。

Each compressor is assigned a predefined compressor ID as follows:为每个压缩机分配一个预定义的压缩机ID，如下所示：

compressorIdHandshake Value握手值Description描述
0noopThe content of the message is uncompressed. 消息的内容是未压缩的。This is used for testing.这是用来测试的。
1snappyThe content of the message is compressed using snappy.消息内容使用snappy压缩。
2zlibThe content of the message is compressed using zlib.消息的内容使用zlib压缩。
3zstdThe content of the message is compressed using zstd.消息的内容使用zstd压缩。
4-255reservedReserved for future use.留作将来使用。

OP_MSG

OP_MSG is an extensible message format used to encode both client requests and server replies on the wire.是一种可扩展的消息格式，用于在线对客户端请求和服务器回复进行编码。

OP_MSG 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
}
Field字段Description描述
headerStandard message header, as described in Standard Message Header.标准消息头，如标准消息头中所述。
flagBitsAn integer bitmask containing message flags, as described in Flag Bits.包含消息标志的整数位掩码，如标志位所述。
sectionsMessage body sections, as described in Sections.消息正文部分，如Sections所述。
checksumAn optional CRC-32C checksum, as described in Checksum.可选的CRC-32C校验和，如校验和中所述。

Flag Bits

The flagBits integer is a bitmask encoding flags that modify the format and behavior of OP_MSG.flagBits整型数是位掩码编码标志，用于修改OP_MSG的格式和行为。

The first 16 bits (0-15) are required and parsers MUSTerror if an unknown bit is set.前16位（0-15）是必需的，如果设置了未知位，解析器必须出错。

The last 16 bits (16-31) are optional, and parsers MUSTignore any unknown set bits. 最后16位（16-31）是可选的，解析器必须忽略任何未知的设置位。Proxies and other message forwarders MUST clear any unknown optional bits before forwarding messages.在转发消息之前，代理和其他消息转发器必须清除任何未知的可选位。

Bit位Name名称Request请求Response响应Description描述
0checksumPresent

✓

✓

The message ends with 4 bytes containing a CRC-32C [2] checksum. 消息以包含CRC-32C[2]校验和的4个字节结束。See Checksum for details.有关详细信息，请参阅校验和。
1moreToCome

✓

✓

Another message will follow this one without further action from the receiver. 此消息之后将出现另一条消息，接收者不会采取进一步行动。The receiver MUST NOT send another message until receiving one with moreToCome set to 0 as sends may block, causing deadlock. 在接收到moreToCome设置为0的消息之前，接收方不得发送另一条消息，因为发送可能会阻塞，从而导致死锁。Requests with the moreToCome bit set will not receive a reply. 设置了moreToCome位的请求将不会收到回复。Replies will only have this set in response to requests with the exhaustAllowed bit set.回复将仅在响应设置了exhaustAllowed位的请求时设置此设置。
16exhaustAllowed

✓

The client is prepared for multiple replies to this request using the moreToCome bit. 客户端已准备好使用moreToCome位对该请求进行多次回复。The server will never produce replies with the moreToCome bit set unless the request has this bit set.除非请求设置了moreToCome位，否则服务器永远不会生成带有该位的回复。

This ensures that multiple replies are only sent when the network layer of the requester is prepared for them.这确保了只有当请求者的网络层为多个回复做好准备时，才会发送多个回复。

Sections

An OP_MSG message contains one or more sections. OP_MSG消息包含一个或多个部分。Each section starts with a kind byte indicating its type. 每个部分都以一个表示其kind的字节开始。Everything after the kind byte constitutes the section's payload.kind字节之后的所有内容都构成了该部分的有效载荷。

The available kinds of sections follow.下面是可用的部分类型。

Kind 0: Body

A body section is encoded as a single BSON object. 主体部分编码为单个BSON对象。The size in the BSON object also serves as the size of the section. BSON对象中的大小也用作截面的大小。This section kind is the standard command request and reply body.这种类型是标准的命令请求和回复体。

All top-level fields MUST have a unique name.所有顶级字段必须具有唯一的名称。

Kind 1: Document Sequence文档序列

Type类型Description描述
int32Size of the section in bytes.节的大小（字节）。
C String

Document sequence identifier. In all current commands this field is the (possibly nested) field that it is replacing from the body section.文档序列标识符。在所有当前命令中，该字段是它从主体部分替换的（可能是嵌套的）字段。

This field MUST NOT also exist in the body section.正文部分中不得存在此字段。

Zero or more BSON objects零个或多个BSON对象
  • Objects are sequenced back to back with no separators.对象是连续排列的，没有分隔符。
  • Each object is limited to the maxBSONObjectSize of the server. 每个对象的服务器maxBSONObjectSize都是有限的。The combination of all objects is not limited to maxBSONObjSize.所有对象的组合不限于maxBSONObjSize。
  • The document sequence ends once size bytes have been consumed.一旦使用了size字节，文档序列就会结束。
  • Parsers MAY choose to merge these objects into the body as an array at the path specified by the sequence identifier when converting to language-level objects.在转换为语言级别的对象时，解析器可以选择将这些对象作为数组，按照序列标识符指定的路径合并到主体中。

Kind 2

This section is used for internal purposes.本节用于内部目的。

Checksum校验和

Each message MAY end with a CRC-32C [2] checksum that covers all bytes in the message except for the checksum itself.每条消息可能以CRC-32C[2]校验和结束，该校验和覆盖消息中除校验和本身之外的所有字节。

Starting in MongoDB 4.2:从MongoDB 4.2开始：

  • mongod instances, mongos instances, and mongo shell instances will exchange messages with checksums if not using TLS/SSL connection.如果不使用TLS/SSL连接，mongod实例、mongos实例和mongoShell实例将使用校验和交换消息。
  • mongod instances, mongos instances, and mongo shell instances will skip the checksum if using TLS/SSL connection.如果使用TLS/SSL连接，mongod实例、mongos实例和mongoShell实例将跳过校验和。

Drivers and older binaries will ignore the checksum if presented with messages with checksum.如果出现带有校验和的消息，驱动程序和旧的二进制文件将忽略校验和。

The presence of a checksum is indicated by the checksumPresent flag bit.校验和的存在由checksumPresent标志位指示。

Legacy Opcodes旧操作码

Starting in MongoDB 5.1, these opcodes are removed in favor of OP_MSG:从MongoDB 5.1开始，删除这些操作码以支持OP_MSG：

  • OP_DELETE
  • OP_GET_MORE
  • OP_INSERT
  • OP_KILL_CURSORS
  • OP_QUERY [1]
  • OP_REPLY
  • OP_UPDATE

If you are running an older version of MongoDB and need detailed information on the previous opcodes, see Legacy Opcodes.如果您正在运行较旧版本的MongoDB，并且需要有关以前操作码的详细信息，请参阅旧操作码。

Opcode Considerations操作码注意事项

In version 4.2, MongoDB removes the deprecated internal OP_COMMAND and OP_COMMANDREPLY protocol.在4.2版中，MongoDB删除了不推荐使用的OP_COMMAND和OP_COMMANDREPLY协议。

Footnotes

[1] MongoDB 5.1 removes support for both OP_QUERY find operations and OP_QUERY commands. As an exception, OP_QUERY is still supported for running the hello and isMaster commands as part of the connection handshake.
[2](1, 2) 32-bit CRC computed with the Castagnoli polynomial as described by https://tools.ietf.org/html/rfc4960#page-140.
←  Collation Locales and Default ParametersLegacy Opcodes →