Docs HomeMongoDB Manual

MongoDB Wire ProtocolMongoDB有线协议

Note

This MongoDB Wire Protocol Specification is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 United States License. 本MongoDB Wire协议规范是根据知识共享归因非商业性股票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. Clients communicate with the database server through a regular TCP/IP socket.MongoDB Wire协议是一个简单的基于套接字的请求-响应风格的协议。客户端通过常规TCP/IP套接字与数据库服务器通信。

TCP/IP SocketTCP/IP套接字

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. mongodmongos实例的默认端口号是27017。The port number for mongod and mongos is configurable and may vary.mongodmongos的端口号是可配置的,可能会有所不同。

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的struct来描述消息结构。

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机器码

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

Opcode Name操作码名称ValueComment议论
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.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,如下所示:

compressorId压缩机IDHandshake 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.包含消息标志的整数位掩码,如Flag Bits中所述。
sectionsMessage body sections, as described in 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 MUST error if an unknown bit is set.前16位(0-15)是必需的,如果设置了未知位,则解析器必须出错。

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

BitName名称RequestResponseDescription描述
0checksumPresentThe message ends with 4 bytes containing a CRC-32C [2] checksum. 该消息以包含CRC-32C[2]校验和的4个字节结束。See Checksum for details.有关详细信息,请参阅校验和
1moreToComeAnother 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位的请求时才会有此设置。
16exhaustAllowedThe 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类型1:文档序列

Type类型Description描述
int32Size of the section in bytes.节的大小(以字节为单位)。
C StringDocument 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. 每个对象都被限制为服务器的maxBSONObjectSizeThe 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 and mongos instances will exchange messages with checksums if not using TLS/SSL connection.如果不使用TLS/SSL连接,mongod实例和mongos实例将使用校验和交换消息。
  • mongod instances and mongos instances will skip the checksum if using TLS/SSL connection.如果使用TLS/SSL连接,mongod实例和mongos实例将跳过校验和。

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_COMMANDOP_COMMANDREPLY协议。

Footnotes脚注

[1] MongoDB 5.1 removes support for both OP_QUERY find operations and OP_QUERY commands. MongoDB 5.1删除了对OP_QUERY查找操作和OP_QUERY命令的支持。As an exception, OP_QUERY is still supported for running the hello and isMaster commands as part of the connection handshake.作为例外,OP_QUERY仍然支持作为连接握手的一部分运行helloisMaster命令。
[2](1, 2) 32-bit CRC computed with the Castagnoli polynomial as described by https://tools.ietf.org/html/rfc4960#page-140.使用Castagnoli多项式计算的32位CRC,如hhttps://tools.ietf.org/html/rfc4960#page-140.所述。