Docs 主页 → 开发应用程序 → MongoDB Manual
MongoDB 有线协议
注意
本 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
。
标准消息头
一般来说,每条消息均包含一个标准消息头,并后跟特定于请求的数据。标准消息头的结构如下:
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 ),它将在OP_REPLY消息的 responseTo 字段中返回。客户端可以使用requestID 和responseTo 字段将查询响应与原始查询关联起来。 |
responseTo | 对于来自数据库的消息,这将是从来自客户端的OP_QUERY或OP_GET_MORE消息中获取的 requestID 。客户端可以使用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
[1] MongoDB 5 。 0弃用了 OP_QUERY
查找操作和OP_QUERY
命令。但有一例外:OP_QUERY
仍支持在连接握手过程中运行hello
和isMaster
命令。
MongoDB 支持这些opCode
值:
操作码名称 | 值 | 注释 |
---|---|---|
OP_MSG | 2013 | 使用 MongoDB 3中引入的格式发送消息。 6 。 |
OP_REPLY 已在 MongoDB 5中弃用。 0 。 | 1 | 回复客户端请求。 responseTo 已设置。 |
OP_UPDATE 已在 MongoDB 5中弃用。 0 。 | 2001 年 | 更新文档。 |
OP_INSERT 已在 MongoDB 5中弃用。 0 。 | 2002 | 插入新文档。 |
RESERVED | 2003 | 之前曾供 OP_GET_BY_OID 使用。 |
OP_QUERY 已在 MongoDB 5中弃用。 0 。 | 2004 年 | 查询一个集合。 |
OP_GET_MORE 已在 MongoDB 5中弃用。 0 。 | 2005 | 从查询中获取更多数据。参见游标。 |
OP_DELETE 已在 MongoDB 5中弃用。 0 。 | 2006 | 删除文档。 |
OP_KILL_CURSORS 已在 MongoDB 5中弃用。 0 。 | 2007 | 通知数据库该客户端已完成游标操作。 |
OP_COMPRESSED | 2012 | 使用压缩包装其他操作码 |
客户端请求消息
OP_MSG
MongoDB 版本中的新增功能: 3 。 6
OP_MSG
是一种可扩展消息格式,旨在包含其他操作码的功能。该操作码的格式如下:
OP_MSG { MsgHeader header; // standard message header uint32 flagBits; // message flags Sections[] sections; // data sections optional<uint32> checksum; // optional CRC-32C checksum }
标记位
flagBits
整数是位掩码编码标志,用于修改 OP_MSG
的格式和行为。
前 16 位 (0-15) 必须进行设置;如果设置了未知位,解析器则必须报错。
最后 16 位 (16-31) 是可选的,解析器必须忽略任何未知的计算置位。代理和其他消息转发器必须在转发消息之前清除任何未知的可选位。
Bit | 名称 | 请求 | 响应 | 说明 |
---|---|---|---|---|
0 | checksumPresent | ✓ | ✓ | |
1 | moreToCome | ✓ | ✓ | 另一条消息将紧随其后,而接收者无需执行后续操作。接收者在收到 moreToCome 设为 0 的消息之前不得发送其他消息;因为发送操作可能会阻塞,从而导致死锁。已设置 moreToCome 位的请求不会收到回复。仅当响应已设置 exhaustAllowed 位的请求时,回复才会设置此位。 |
16 | exhaustAllowed | ✓ | 客户端已准备好使用 此举可仅当请求者的网络层已为多个回复做好准备时才发送多个回复。 重要MongoDB 3 。 6会忽略此标志,并以一条消息进行响应。 |
部分
一条 OP_MSG
消息包含一个或多个部分。每个部分都以指示其类型的 kind
字节开头。kind
字节之后的所有内容构成该部分的有效负载。
可用的部分类型如下。
类型 0:正文
正文部分会编码为单个 BSON 对象。BSON 对象中的此大小也会用作该部分的大小。此部分类型为标准命令请求和回复正文。
所有顶级字段均须具有唯一名称。
第 1 类:文档序列
类型 | 说明 |
---|---|
int32 | 该部分的大小(以字节为单位)。 |
C 字符串 | 文档序列标识符。在所有当前命令中,该字段是它从正文部分替换的(可能是嵌套的)字段。 此字段不得同时存在于正文部分。 |
零个或多个 BSON 对象 |
|
校验和
每条消息均可能以 CRC-32C [2] 校验和结尾,而其中涵盖了消息中除校验和自身之外的所有字节。
从 MongoDB 4.2 开始:
如果显示带有校验和的消息,驱动程序和较旧的二进制文件将忽略校验和。
校验和的存在由 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 | 用于指定操作标志的位向量。位值对应如下内容:
|
selector | BSON 文档,指定选择要更新的文档的查询。 |
update | BSON 文档,指定要执行的更新。有关指定更新的信息,请参阅更新操作文档。 |
对 OP_UPDATE 消息没有响应。
OP_INSERT
已在 MongoDB 5中弃用。 0 。
OP_INSERT 消息用于将一个或多个文档插入到collection中。 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 | 用于指定操作标志的位向量。位值对应如下内容:
|
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 | 用于指定操作标志的位向量。位值对应如下内容:
| |
fullCollectionName | 完整的集合名称;即命名空间。完整的集合名称是数据库名称与集合名称的串联,使用 . 表示串联。例如,对于数据库foo 和集合bar ,完整的集合名称为foo.bar 。 | |
numberToSkip | 设置返回查询结果时要忽略的文档数量(从结果数据集的第一个文档开始)。 | |
numberToReturn | 限制查询的第一条 OP_REPLY消息中的文档数量。但是,如果结果多于 numberToReturn ,数据库仍会建立游标并将cursorID 返回给客户端。如果客户端驱动程序提供“限制”功能(如 SQL LIMIT 关键字),则客户端驱动程序需要确保返回到调用应用程序的文档不超过指定数量。如果numberToReturn 为0 ,则数据库将使用默认返回大小。如果数字为负数,数据库将返回该数字并关闭游标。无法获取该查询的更多结果。如果numberToReturn 为1 ,服务器会将其视为-1 (自动关闭游标)。 | |
query | 表示查询的 BSON 文档。查询将包含一个或多个元素,所有这些元素都必须与要包含在结果集中的文档匹配。可能的元素包括 $query 、 $orderby 、 $hint 和$explain 。 | |
returnFieldsSelector | 可选。用于限制已返回文档中的字段的 BSON 文档。
|
数据库将使用 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消息中的文档数量。但是,如果结果多于 numberToReturn ,数据库仍会建立游标并将cursorID 返回给客户端。如果客户端驱动程序提供“限制”功能(如 SQL LIMIT 关键字),则客户端驱动程序需要确保返回到调用应用程序的文档不超过指定数量。如果numberToReturn 为0 ,则数据库将使用默认返回大小。 |
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 | 用于指定操作标志的位向量。位值对应如下内容:
|
selector | BSON 文档,表示用于选择要删除的文档的查询。选择器将包含一个或多个元素,所有这些元素都必须与要从collection中删除的文档匹配。 |
对 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
MongoDB 版本更新:3.4
任何操作码都可以压缩并包装在 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 | 用于指定标志的位向量。位值对应如下内容:
|
cursorID | 此 OP_REPLY 是 cursorID 的一部分。如果查询的结果集适合一条 OP_REPLY 消息,则cursorID 将为0 。此cursorID 必须在用于获取更多数据的任何OP_GET_MORE消息中使用,并且还必须由客户端在不再需要时通过OP_KIL_CURSORS消息关闭。 |
startingFrom | 游标的起始位置。 |
numberReturned | 回复中的文档数量。 |
documents | 已返回文档。 |
脚注
[2] | (1 ,2 )32 位 CRC 使用 Castagnoli 多项式计算得出,如 https://tools.ietf.org/html/rfc4960 #page-140 中所述。 |