MongoDB 有线协议

在此页面上

简介

TCP/IP 套接字
消息类型和格式
标准消息头
客户端请求消息
数据库响应消息

MongoDB5.0 已于 10 月2024 结束生命周期。不再支持此版本的文档。要升级5.0 部署，请参阅 MongoDB6 。0 升级程序。

注意

本MongoDB传输协议规范根据 Creative Commons Attribution-NonCommercial-ShareAlike3.0 美国许可获得许可。您不得出于任何商业目的使用或改编本材料，例如创建商业数据库或数据库即服务产品。

简介

MongoDB 传输协议是一种基于套接字的简易请求-响应式协议。客户端可通过常规 TCP/IP 套接字与数据库服务器进行通信。

TCP/IP 套接字

客户端应使用常规 TCP/IP 套接字连接数据库。

端口

mongod和mongos 实例的默认端口号为 27017 。mongod 和 mongos 的端口号可配置，且可能不同。

字节排序

MongoDB 传输协议中的所有整数均采用小端字节顺序：即，最低有效字节在前。

消息类型和格式

MongoDB 将 OP_MSG 操作码同时用于客户端请求和数据库回复。旧版本的 MongoDB 采用多种消息格式，而这些格式现已弃用并替换为 OP_MSG。

注意

该页面使用类似 C 语言的 struct 来描述消息结构。
本文档中使用的类型（例如int32 和cstring ）与BSON规范中定义的类型相同。
为了表示重复，该文档使用 BSON 规范中的星号表示法。例如， int64*表示可以将一个或多个指定类型依次写入套接字。
标准消息头的类型为MsgHeader 。整数常量为大写（例如 ZERO表示0的整数值）。

标准消息头

一般来说，每条消息均包含一个标准消息头，并后跟特定于请求的数据。标准消息头的结构如下：

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 for details
}

字段	说明
`messageLength`	消息的总大小（以字节为单位）。该总数包括保存消息长度的 4 个字节。
`requestID`	客户端或数据库生成的标识符，用于唯一标识此消息。对于客户端生成的消息（例如 OP_QUERY 和 OP_GET_MORE ），它将在`responseTo` OP_REPLY 消息的字段中返回。客户端可以使用`requestID` 和`responseTo` 字段将查询响应与原始查询关联起来。
`responseTo`	对于来自数据库的消息，这将是从来自客户端的`requestID` OP_QUERY 或 OP_GET_MORE 消息中获取的。客户端可以使用`requestID` 和`responseTo` 字段将查询响应与原始查询关联起来。
`opCode`	消息类型。有关详细信息，请参阅请求操作码。

请求操作码

注意

从MongoDB 2.6和maxWireVersion 3开始， MongoDB驱动程序使用数据库命令 insert 、 update和delete而不是OP_INSERT 、 OP_UPDATE和OP_DELETE进行确认写入。大多数驱动程序继续使用操作码进行未确认的写入。
在版本 4.2 中，MongoDB 删除了已弃用的内部 OP_COMMAND 和 OP_COMMANDREPLY 协议。

在版本5.0中， MongoDB 弃用了以下操作码：

OP_REPLY
OP_UPDATE
OP_INSERT
OP_QUERY [1]
OP_GET_MORE
OP_DELETE
OP_KILL_CURSORS

请使用OP_MSG，而不是这些操作码。

[1]	MongoDB 5.0已弃用`OP_QUERY`查找操作和`OP_QUERY`命令。但有一例外： `OP_QUERY`仍支持在连接握手过程中运行`hello`和`isMaster`命令。

MongoDB 支持这些opCode值：

操作码名称	值	Comment
`OP_MSG`	2013	使用 MongoDB 3.6中引入的格式发送消息。
`OP_REPLY` Deprecated in MongoDB 5.0.	1	回复客户端请求。 `responseTo` 已设置。
`OP_UPDATE` Deprecated in MongoDB 5.0.	2001 年	Update document.
`OP_INSERT` Deprecated in MongoDB 5.0.	2002	插入新文档。
`RESERVED`	2003	之前曾供 OP_GET_BY_OID 使用。
`OP_QUERY` Deprecated in MongoDB 5.0.	2004 年	查询一个集合。
`OP_GET_MORE` Deprecated in MongoDB 5.0.	2005	从查询中获取更多数据。参见游标。
`OP_DELETE` Deprecated in MongoDB 5.0.	2006	删除文档。
`OP_KILL_CURSORS` Deprecated in MongoDB 5.0.	2007	通知数据库该客户端已完成游标操作。
`OP_COMPRESSED`	2012	使用压缩包装其他操作码

客户端请求消息

OP_MSG

OP_MSG 是一种可扩展消息格式，旨在包含其他操作码的功能。该操作码的格式如下：

OP_MSG {
    MsgHeader header;          // standard message header
    uint32 flagBits;           // message flags
    Sections[] sections;       // data sections
    optional<uint32> checksum; // optional CRC-32C checksum
}

字段	说明
`header`	标准消息头，如标准消息头中所述。
`flagBits`	包含消息标志的整数位掩码，如标志位中所述。
`sections`	消息正文部分，如部分中所述。
`checksum`	可选的 CRC-32 C校验和，如校验和中所述。

标记位

flagBits 整数是位掩码编码标志，用于修改 OP_MSG 的格式和行为。

前 16 位 (0-15) 必须进行设置；如果设置了未知位，解析器则必须报错。

最后 16 位 (16-31) 是可选的，解析器必须忽略任何未知的计算置位。代理和其他消息转发器必须在转发消息之前清除任何未知的可选位。

Bit	名称	请求	响应	说明
0	`checksumPresent`	✓	✓	该消息以包含4 CRC-32 C [2 ]校验和的字节结束。有关详细信息，请参阅校验和。
1	`moreToCome`	✓	✓	另一条消息将紧随其后，而接收者无需执行后续操作。接收者在收到 `moreToCome` 设为 0 的消息之前不得发送其他消息；因为发送操作可能会阻塞，从而导致死锁。已设置 `moreToCome` 位的请求不会收到回复。仅当响应已设置 `exhaustAllowed` 位的请求时，回复才会设置此位。
16	`exhaustAllowed`	✓		客户端已准备好使用 `moreToCome` 位对此请求进行多次回复。除非该请求已设置此位，否则服务器永不会生成已设置 `moreToCome` 位的回复。此举可仅当请求者的网络层已为多个回复做好准备时才发送多个回复。重要 MongoDB 3.6会忽略此标志，并用一条消息进行响应。

部分

一条 OP_MSG 消息包含一个或多个部分。每个部分都以指示其类型的 kind 字节开头。kind 字节之后的所有内容构成该部分的有效负载。

可用的部分类型如下。

类型 0：正文

正文部分会编码为单个 BSON 对象。BSON 对象中的此大小也会用作该部分的大小。此部分类型为标准命令请求和回复正文。

所有顶级字段均须具有唯一名称。

第 1 类：文档序列

类型	说明
int32	该部分的大小（以字节为单位）。
C 字符串	文档序列标识符。在所有当前命令中，该字段是它从正文部分替换的（可能是嵌套的）字段。此字段不得同时存在于正文部分。
零个或多个 BSON 对象	对象会连续进行排序，而不使用分隔符。每个对象仅限于服务器的 `maxBSONObjectSize`。所有对象的组合不限于`maxBSONObjSize`。文档序列在消耗完 `size` 字节后结束。当转换为语言级对象时，解析器可能会选择将这些对象作为数组合并到序列标识符所指定路径处的正文中。

校验和

每条消息均可能以 CRC-32C [2] 校验和结尾，而其中涵盖了消息中除校验和自身之外的所有字节。

从 MongoDB 4.2 开始：

如果未 使用 TLS/SSL 连接，实例、mongod mongos实例和实例将交换带校验和的消息。mongoshell
如果使用 TLS/SSL 连接， mongod实例、 mongos实例和mongo shell实例将跳过校验和。

如果显示带有校验和的消息，驱动程序和较旧的二进制文件将忽略校验和。

校验和的存在由 checksumPresent 标记位指示。

OP_UPDATE

已在MongoDB 5.0中弃用。

OP_UPDATE 消息用于更新集合中的文档。OP_UPDATE 消息的格式如下：

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
}

字段	说明
`header`	消息头，如标准消息头中所述。
`ZERO`	整数值 0。保留供将来使用。
`fullCollectionName`	完整的集合名称；即命名空间。完整的集合名称是数据库名称与集合名称的串联，使用`.`表示串联。例如，对于数据库`foo`和集合`bar` ，完整的集合名称为`foo.bar` 。
`flags`	用于指定操作标志的位向量。位值对应如下内容： `0` 对应于 Upsert。设置此选项，则在未找到匹配的文档时，数据库会将提供的对象插入集合。 `1` 对应于 MultiUpdate。如果设置此选项，数据库将更新集合中的所有匹配对象。否则，仅更新第一个匹配的文档。 `2`-`31` 保留。必须设置为 0。
`selector`	BSON 文档，指定选择要更新的文档的查询。
`update`	BSON 文档，指定要执行的更新。有关指定更新的信息，请参阅更新操作文档。

对 OP_UPDATE 消息没有响应。

OP_INSERT

已在MongoDB 5.0中弃用。

OP_INSERT 消息用于将一个或多个文档插入到集合中。 OP_INSERT 消息的格式为

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
}

字段	说明
`header`	消息头，如标准消息头中所述。
`flags`	用于指定操作标志的位向量。位值对应如下内容： `0` 对应于 ContinueOnError。如果设立为，则即使批量插入失败（例如由于 ID 重复），数据库也不会停止处理批量插入。这使得批量插入的行为类似于一系列单次插入，只是任何插入失败而不仅仅是最后插入失败都会设立lastError。如果发生多个错误，getLastError 将只报告最新的错误。 `1`-`31` 保留。必须设置为 0。
`fullCollectionName`	完整的集合名称；即命名空间。完整的集合名称是数据库名称与集合名称的串联，使用`.`表示串联。例如，对于数据库`foo`和集合`bar` ，完整的集合名称为`foo.bar` 。
`documents`	要插入集合的一个或多个文档。如果有多个文档，则按顺序依次写入套接字。

对 OP_INSERT 消息没有响应。

OP_QUERY

已在MongoDB 5.0中弃用。

OP_QUERY 消息用于在数据库中查询集合中的文档。OP_QUERY 消息的格式为：

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.
}

字段

说明

header

消息头，如标准消息头中所述。

flags

用于指定操作标志的位向量。位值对应如下内容：

0 已保留。必须设置为 0。
1 对应于 TailableCursor。 Tailable 表示检索最后一个数据时游标未关闭。相反，游标标记的是最终对象的位置。如果接收到更多数据，您可以稍后从游标所在的位置恢复使用游标。与任何“潜在游标”一样，游标可能在某个时刻变得无效 (CursorNotFound)，例如，如果它引用的最终对象被删除。
2 对应于 SlaveOk。允许查询从属副本。通常，除了命名空间“local”之外，它们都会返回错误。
3 对应于 OplogReplay。从 MongoDB 4.4 开始，您无需指定此标志，因为 oplog 上符合条件的查询会自动进行优化。有关更多信息，请参阅 oplogReplay。
4 对应于 NoCursorTimeout。服务器通常会在不活动期（10 分钟）后使空闲游标超时，防止过度使用内存。设置此选项，可防止出现这种情况。
5 对应于 AwaitData。与 TailableCursor 一起使用。如果到达数据的末尾，请区块一段时间，而不是不返回数据。超时一段时间后，我们会正常返回。
6 对应于 Exhaust。假设客户端将完全读取所有查询的数据，则将以多个“更多”包的形式全速下传数据。当您拉取大量数据并知道要将其全部拉取时，速度会更快。注意：除非客户端关闭连接，否则不允许不读取所有数据。
7 对应于部分。如果某些分片不可用，则从 mongos 获取部分结果（而不是引发错误）
8-31 保留。必须设置为 0。

fullCollectionName

完整的集合名称；即命名空间。完整的集合名称是数据库名称与集合名称的串联，使用.表示串联。例如，对于数据库foo和集合bar ，完整的集合名称为foo.bar 。

numberToSkip

设置返回查询结果时要忽略的文档数量（从结果数据集的第一个文档开始）。

numberToReturn

限制查询的第一条 OP_REPLY 消息中的文档数量。但是，如果结果多于，数据库仍会建立游标并将cursorID numberToReturn返回给客户端。如果客户端驾驶员提供“限制”功能（如SQL LIMIT 关键字），则客户端驾驶员需要确保返回到调用应用程序的文档不超过指定数量。如果numberToReturn 为0 ，则数据库将使用默认返回大小。如果该数字为负数，则数据库将返回该数字并关闭游标。无法获取该查询的更多结果。如果numberToReturn 为1 ，服务器会将其视为-1 （自动关闭游标）。

query

表示查询的 BSON 文档。查询将包含一个或多个元素，所有这些元素都必须与要包含在结果集中的文档匹配。可能的元素包括$query 、 $orderby 、 $hint和$explain 。

returnFieldsSelector

可选。用于限制已返回文档中的字段的 BSON 文档。returnFieldsSelector 包含一个或多个元素，每个元素都是应返回的字段的名称以及整数值 1。在 JSON 表示法中，限制为字段 a、b 和 c 的 returnFieldsSelector 为：

{ a : 1, b : 1, c : 1}

数据库将使用 OP_QUERY 消息来响应 OP_REPLY 消息。

OP_GET_MORE

已在MongoDB 5.0中弃用。

OP_GET_MORE 消息用于在数据库中查询集合的文档。OP_GET_MORE 消息的格式为：

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
}

字段	说明
`header`	消息头，如标准消息头中所述。
`ZERO`	整数值 0。保留供将来使用。
`fullCollectionName`	完整的集合名称；即命名空间。完整的集合名称是数据库名称与集合名称的串联，使用`.`表示串联。例如，对于数据库`foo`和集合`bar` ，完整的集合名称为`foo.bar` 。
`numberToReturn`	限制查询的第一条 OP_REPLY 消息中的文档数量。但是，如果结果多于`cursorID` `numberToReturnnumberToReturn0`，数据库仍会建立游标并将返回给客户端。如果客户端驾驶员提供“限制”功能（如SQL LIMIT 关键字），则客户端驾驶员需要确保返回到调用应用程序的文档不超过指定数量。如果为，则数据库将使用默认返回大小。
`cursorID`	OP_REPLY 中的游标标识符。这必须是来自数据库的值。

数据库将使用 OP_REPLY 消息来响应 OP_GET_MORE 消息。

OP_DELETE

已在MongoDB 5.0中弃用。

OP_DELETE 消息用于从集合中删除一个或多个文档。OP_DELETE 消息的格式为：

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.
}

字段	说明
`header`	消息头，如标准消息头中所述。
`ZERO`	整数值 0。保留供将来使用。
`fullCollectionName`	完整的集合名称；即命名空间。完整的集合名称是数据库名称与集合名称的串联，使用`.`表示串联。例如，对于数据库`foo`和集合`bar` ，完整的集合名称为`foo.bar` 。
`flags`	用于指定操作标志的位向量。位值对应如下内容： `0` 对应于 SingleRemove。如果设置此选项，数据库将仅删除集合中第一个匹配的文档。否则，数据库将删除所有匹配的文档。 `1`-`31` 保留。必须设置为 0。
`selector`	BSON文档，表示用于选择要删除的文档的查询。选择器将包含一个或多个元素，所有这些元素都必须与要从集合中删除的文档匹配。

对 OP_DELETE 消息没有响应。

OP_KILL_CURSORS

已在MongoDB 5.0中弃用。

OP_KILL_CURSORS 消息用于关闭数据库中的活动游标。这是必要的操作，用于确保在查询结束时回收数据库资源。OP_KILL_CURSORS 消息的格式为：

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
}

字段	说明
`header`	消息头，如标准消息头中所述。
`ZERO`	整数值 0。保留供将来使用。
`numberOfCursorIDs`	消息中的游标 ID 的数量。
`cursorIDs`	要关闭的游标 ID 的“数组”。如果有多个操作码，则按顺序依次写入套接字。

如果读取游标直至耗尽（读取直至 OP_QUERY 或 OP_GET_MORE 返回游标 ID 为零），则无需终止游标。

OP_COMPRESSED

任何操作码都可以压缩并包装在 OP_COMPRESSED 标头中。 OP_COMPRESSED 消息包含原始压缩操作码消息以及处理和解压缩该消息所需的元数据。

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
}

字段	说明
`MsgHeader`	消息头，如标准消息头中所述。
`originalOpcode`	包含封装操作码的值。
`uncompressedSize`	缩小后的 `compressedMessage` 的大小，其中不含 `MsgHeader`。
`compressorId`	压缩此消息的压缩器的 ID。`compressorId` 值的列表如下所示。
`compressedMessage`	操作码本身，不包括 `MsgHeader`。

为每个压缩器均分配了一个预定义的压缩器 ID，如下所示：

compressorId	握手值	说明
`0`	noop	此消息的内容未压缩。此举意在用于测试。
`1`	snappy	此消息的内容使用 snappy 进行压缩。
`2`	zlib	此消息的内容使用 zlib 进行压缩。
`3`	zstd	此消息的内容使用 zstd 进行压缩。
`4-255`	reserved	保留以供将来使用。

数据库响应消息

OP_REPLY

已在MongoDB 5.0中弃用。

OP_REPLY消息由数据库发送，以响应 OP_QUERY 或 OP_GET_MORE 消息。OP_REPLY 消息的格式为：

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
}

字段	说明
`header`	消息头，如标准消息头中所述。
`responseFlags`	用于指定标志的位向量。位值对应如下内容： `0` 对应于 cursorNotFound。当调用了 `getMore` 但游标 ID 在服务器上无效时设置。返回结果为零。 `1` 对应于 QueryFailure。在查询失败时设置。结果由一个包含描述失败的“$err”字段的文档组成。 `2` 对应于 ShardConfigStale。驱动程序应忽略这一点。只有 `mongos` 会看到此集合，在这种情况下，它需要从服务器更新配置。 `3` 对应于 AwaitCapable。当服务器支持 AwaitData 查询选项时设立。如果没有，客户端应该在可追加游标的 getMore 之间休息一下。 mongod版本 1.6 支持 AwaitData，因此始终设置 AwaitCapable。 `4`-`31` 保留。忽略。
`cursorID`	`cursorID`此 OP_REPLY 是的一部分。事件查询的结果设立适合一条 OP_REPLY 消息，则`cursorID` 将为0 。此`cursorID` 必须在用于获取更多数据的任何 OP_GET_MORE 消息中使用，并且还必须由客户端在不再需要时通过 OP_KIL_CURSORS 消息关闭。
`startingFrom`	游标的起始位置。
`numberReturned`	回复中的文档数量。
`documents`	已返回文档。

脚注

[2]	使用 Castagnoli 多项式计算出的 (1，2)32 位 CRC ，如 https://tools.ietf.org/html/rfc4960#page-140所述。

后退

限制和阈值

来年

mongosh 方法

注意

简介

TCP/IP 套接字

端口

字节排序

消息类型和格式

注意

标准消息头

请求操作码

注意

客户端请求消息

OP_MSG

标记位

重要

部分

类型 0：正文

第 1 类：文档序列

校验和

OP_UPDATE

OP_INSERT

OP_QUERY

OP_GET_MORE

OP_DELETE

OP_KILL_CURSORS

OP_COMPRESSED

数据库响应消息

OP_REPLY