MongoDB 有线协议

在本页面

介绍

MongoDB 有线协议是一种简单的 socket-based,request-response 样式协议。 Clients 通过常规 TCP/IP socket 与数据库服务器通信。

TCP/IP Socket

Clients 应该使用常规的 TCP/IP socket 连接到数据库。没有连接握手。

港口

mongodmongos实例的默认 port 编号为 27017. mongodmongos的 port 编号是可配置的,可能会有所不同。

字节订购

MongoDB 有线协议中的所有整数都使用 little-endian byte order:即 least-significant byte first。

消息类型和格式

有两种类型的消息:客户端请求和数据库响应。

注意

  • 此页面使用 C-like struct来描述消息结构。

  • 本文档中使用的类型(cstringint32,etc.)与BSON 规范中定义的类型相同。

  • 为了表示重复,文档使用BSON 规范中的星号表示法。对于 example,int64*表示可以将一个或多个指定类型一个接一个地写入 socket。

  • 标准邮件头的类型为MsgHeader。 Integer 常量是大写字母(e.g. ZERO表示 integer value 为 0)。

标准消息标题

通常,每条消息都包含一个标准消息头,后跟 request-specific 数据。标准邮件头的结构如下:

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唯一标识此消息的 client 或 database-generated 标识符。对于 client-generated 消息(e.g. OP_QUERYOP_GET_MORE)的情况,它将在OP_REPLY消息的responseTo字段中返回。 Clients 可以使用requestIDresponseTo字段将查询响应与原始查询相关联。
responseTo对于来自数据库的消息,这将是来自 client 的OP_QUERYOP_GET_MORE消息的requestID。 Clients 可以使用requestIDresponseTo字段将查询响应与原始查询相关联。
opCode消息类型。有关详细信息,请参阅请求操作码

请求操作码

注意 从 MongoDB 2.6 和maxWireVersion 3开始,MongoDB 驱动程序使用数据库命令 插入更新删除而不是OP_INSERTOP_UPDATEOP_DELETE进行已确认的写入。大多数驱动程序继续使用操作码进行未确认的写入。

警告 OP_COMMAND 和 OP_COMMANDREPLY 是 cluster 内部的,不应由 clients 或驱动程序实现。 更改 version 3.6:不推荐使用OP_COMMANDOP_COMMANDREPLY格式和协议,可能会在 MongoDB 的未来版本中删除。

以下是支持的opCode

操作码 Name评论
OP_REPLY1回复 client 请求。 responseTo已设置。
OP_UPDATE2001更新文件。
OP_INSERT2002插入新文件。
RESERVED2003以前用于 OP_GET_BY_OID。
OP_QUERY2004查询集合。
OP_GET_MORE2005从查询中获取更多数据。请参阅游标。
OP_DELETE2006删除文件。
OP_KILL_CURSORS2007通知数据库 client 已完成游标。
OP_COMMAND2010Cluster 表示命令请求的内部协议。
OP_COMMANDREPLY2011Cluster 内部协议表示对OP_COMMAND的回复。
OP_MSG2013使用 MongoDB 3.6 中引入的格式发送消息。

Client 请求消息

Clients 可以发送指定除OP_REPLY opCode 之外的所有请求的请求消息。 OP_REPLY保留供数据库使用。

只有OP_QUERYOP_GET_MORE消息才会产生数据库的响应。任何其他消息都不会发送任何响应。

您可以使用 getLastError 命令确定消息是否成功。

OP_UPDATE

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消息头,如标准消息标题中所述。
ZEROInteger value 为 0.保留供将来使用。
fullCollectionName完整集合 name; i.e。命名空间。完整集合 name 是数据库 name 与集合 name 的串联,使用.进行连接。对于 example,对于数据库foo和集合bar,完整集合 name 是foo.bar
flags用于指定操作标志的位向量。位值对应于以下内容:
0对应于 Upsert。如果设置,如果找不到匹配的文档,数据库将提供的 object 插入到集合中。
1对应于 MultiUpdate.If set,数据库将更新集合中所有匹配的 objects。否则只更新第一个匹配的文档。
2 - 31是保留的。必须设置为 0。
selectorBSON 文档,指定用于选择要更新的文档的查询。
updateBSON 文档,指定要执行的更新。有关指定更新的信息,请参阅 MongoDB 手册中的更新操作文档。

OP_UPDATE 消息没有响应。

OPINSERT

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

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)。这使得 bulk insert 的行为类似于一系列单个插入,除非在任何 insert 失败时设置 lastError,而不仅仅是最后一个。如果发生多个错误,则 getLastError 仅报告最新错误。 (1.9.1 中的新内容)
1 - 31是保留的。必须设置为 0。
fullCollectionName完整集合 name; i.e。命名空间。完整集合 name 是数据库 name 与集合 name 的串联,使用.进行连接。对于 example,对于数据库foo和集合bar,完整集合 name 是foo.bar
documents要插入集合的一个或多个文档。如果有多个,则依次将它们按顺序写入 socket。

OPINSERT 消息没有响应。

OP_QUERY

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 表示在检索到最后一个数据时,游标未关闭。相反,光标标记最终 object 的位置。如果收到更多数据,您可以稍后从它所在的位置继续使用光标。与任何“潜在游标”一样,游标可能在某些时候变为无效(CursorNotFound) - 对于 example,如果最终 object 它 references 被删除。
2对应于副本从属的 SlaveOk.Allow 查询。通常这些_return 错误除了名称空间“local”。
3对应 OplogReplay。仅限内部复制使用 - 不应设置驱动程序。
4对应于 NoCursorTimeout。在不活动期(10 分钟)之后,服务器通常会超时 idle 游标,以防止过多的 memory 使用。设置此选项以防止这种情况。
5对应 AwaitData。与 TailableCursor 一起使用。如果我们在数据的末尾,阻塞一段时间而不是返回没有数据。超时后,我们正常 return。
6对应排气。假设 client 将完全读取所有查询的数据,在多个“更多”包中流式传输数据。当你提取大量数据并且知道你想把它全部拉下来时更快。注意:除非关闭连接,否则不允许 client 读取所有数据。
7对应 Partial。如果某些分片关闭(而不是抛出错误),则从 mongos 获取部分结果。保留
8 - 31。必须设置为 0。
fullCollectionName完整集合 name; i.e。命名空间。完整集合 name 是数据库 name 与集合 name 的串联,使用.进行连接。对于 example,对于数据库foo和集合bar,完整集合 name 是foo.bar
numberToSkip在返回查询结果时,设置要忽略的文档数 - 从结果数据集中的第一个文档开始。
numberToReturn将第一个OP_REPLY消息中的文档数限制为查询。但是,如果结果多于numberToReturn,数据库仍将建立游标并返回_cl_。如果 client 驱动程序提供“限制”功能(如 SQL LIMIT 关键字),则由 client 驱动程序确保将不超过指定数量的文档返回给调用 application。如果numberToReturn0,则 db 将使用默认的 return 大小。如果数字为负数,则数据库将_return 该数字并关闭光标。无法获取该查询的其他结果。如果numberToReturn1,服务器会将其视为-1(自动关闭光标)。
query代表查询的 BSON 文档。该查询将包含一个或多个元素,所有这些元素必须_匹配文档才能包含在结果集中。可能的元素包括$query$orderby$hint$explain
returnFieldsSelector可选的。限制返回文档中字段的 BSON 文档。 returnFieldsSelector包含一个或多个元素,每个元素都是应返回的字段的 name,以及 integer value 1。在 JSON 表示法中,returnFieldsSelector限制字段abc将是:
{ a : 1, b : 1, c : 1}

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

OP_GET_MORE

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消息头,如标准消息标题中所述。
ZEROInteger value 为 0.保留供将来使用。
fullCollectionName完整集合 name; i.e。命名空间。完整集合 name 是数据库 name 与集合 name 的串联,使用.进行连接。对于 example,对于数据库foo和集合bar,完整集合 name 是foo.bar
numberToReturn将第一个OP_REPLY消息中的文档数限制为查询。但是,如果结果多于numberToReturn,数据库仍将建立游标并返回_cl_。如果 client 驱动程序提供“限制”功能(如 SQL LIMIT 关键字),则由 client 驱动程序确保将不超过指定数量的文档返回给调用 application。如果numberToReturn0,则 db 将使用默认的 return 大小。
cursorIDOP_REPLY中的游标标识符。这必须是来自数据库的 value。

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

OP_DELETE

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消息头,如标准消息标题中所述。
ZEROInteger value 为 0.保留供将来使用。
fullCollectionName完整集合 name; i.e。命名空间。完整集合 name 是数据库 name 与集合 name 的串联,使用.进行连接。对于 example,对于数据库foo和集合bar,完整集合 name 是foo.bar
flags用于指定操作标志的位向量。位值对应于以下内容:
0对应于 SingleRemove。如果设置,则数据库将仅删除集合中的第一个匹配文档。否则将删除所有匹配的文档。
1 - 31是保留的。必须设置为 0。
selectorBSON 文档,表示用于选择要删除的文档的查询。选择器将包含一个或多个元素,所有元素必须 match 才能从集合中删除文档。

OP_DELETE 消息没有响应。

OP_KILL_CURSORS

OP_KILL_CURSORS 消息用于关闭数据库中的 active 游标。这对于确保在查询结束时回收数据库资源是必要的。 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消息头,如标准消息标题中所述。
ZEROInteger value 为 0.保留供将来使用。
numberOfCursorIDs消息中的游标 ID 数。
cursorIDs要关闭游标 ID 的“Array”。如果有多个,则依次将它们按顺序写入 socket。

如果读取光标直到耗尽(读取直到OP_QUERYOP_GET_MORE为光标 id 返回零),则无需终止光标。

OP_COMMAND

更改 version 3.6:不推荐使用OP_COMMAND格式和协议,可能会在 MongoDB 的未来版本中删除。

警告 OP_COMMAND是 cluster internal,不应由 clients 或 drivers 实现。

OP_COMMAND是内部用于一个 MongoDB 服务器向另一个 MongoDB 服务器发出的 intra-cluster 数据库命令请求的有线协议消息。接收数据库发送回OP_COMMANDREPLY作为对OP_COMMAND的响应。

struct {
   MsgHeader header;     // standard message header
   cstring database;     // the name of the database to run the command on
   cstring commandName;  // the name of the command
   document metadata;    // a BSON document containing any metadata
   document commandArgs; // a BSON document containing the command arguments
   inputDocs;            // a set of zero or more documents
}
领域描述
header标准邮件头,如标准消息标题中所述。
database要运行命令的数据库的 name。
commandName命令的 name。有关数据库命令的列表,请参见数据库命令
metadata可供系统将任何元数据附加到内部命令,这些内部命令不是 client 驱动程序提供的命令参数的一部分
commandArgs包含命令 arguments 的 BSON 文档。
有关其 arguments 的信息,请参阅指定commandName的文档
inputDocs零个或多个文档充当命令的输入。对于需要从 client 发送大量数据的命令很有用,例如批处理 insert。

OP_MSG

version 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
}
领域描述
header标准邮件头,如标准消息标题中所述。
flagBits包含消息标志的 integer 位掩码,如Flag Bits中所述。
sections消息正文部分,如中所述。
checksum一个可选的 CRC-32C 校验和,如校验中所述。

Flag Bits

flagBits integer 是一个位掩码编码标志,用于修改OP_MSG的格式和行为。

如果设置了未知位,则前 16 位(0-15)是必需的,解析器必须错误。

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

名称请求响应描述
0checksumPresent消息 ends 包含 4 个字节,包含 CRC-32C [1]校验和。有关详细信息,请参阅校验
1moreToCome另一条消息将遵循此消息而无需接收方的进一步操作。接收方**绝不能发送另一条消息,直到收到一条moreToCome设置为 0,因为发送可能会阻塞,导致死锁。设置了moreToCome位的请求将不会收到回复。回复只会设置此设置以响应设置了exhaustAllowed位的请求。
16exhaustAllowed client 准备使用moreToCome位对此请求进行多次回复。除非请求设置了此位,否则服务器将永远不会生成moreToCome位设置的回复。
这确保仅在请求者的网络层为它们做好准备时才发送多个回复。
重要
重要
MongoDB 3.6 忽略此 flag,并将回复一条消息。

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

可用的部分类型如下。

种类 0:身体

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

所有 top-level 字段必须具有唯一的 name。

种类 1:文件序列
类型描述
INT32节的大小(以字节为单位)。
C String文档序列标识符。在所有当前命令中,该字段是它正在从主体部分替换的(可能是嵌套的)字段。
此字段不得也存在于正文部分中。
零个或多个 BSON objectsObjects 背靠背排序,没有分隔符。
每个 object 仅限于服务器的maxBSONObjectSize。所有 objects 的组合不仅限于maxBSONObjSize
文档序列 ends 消耗了size个字节。
Parsers MAY选择在转换为 language-level objects 时将这些 objects 合并到序列标识符指定的路径中的 array 中。

校验

注意 MongoDB 3.6 不支持验证消息校验和,但如果存在则会正确跳过它。

每个消息MAY以 CRC-32C [1]校验和结束,该校验和覆盖消息中除校验和本身之外的所有字节。校验和的存在由checksumPresent flag 位指示。

数据库响应消息

OP_REPLY

数据库发送OP_REPLY消息以响应OP_QUERYOP_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 Query 选项时设置。如果没有,client 应该在 Tailable 游标的 getMore 之间稍微睡一会儿。 Mongod version 1.6 支持 AwaitData,因此总是 sets AwaitCapable。
4 - 31是保留的。忽视。
cursorID这个 OP_REPLY 是cursorID的一部分。在 event 中,查询的结果集适合一条 OP_REPLY 消息,cursorID将为 0.此cursorID必须用于任何用于获取更多数据的OP_GET_MORE消息中,并且必须由 client 在不再需要时通过OP_KILL_CURSORS消息。
startingFrom光标中的起始位置。
numberReturned回复中的文件数量。
documents退回的文件。

OP_COMMANDREPLY

更改 version 3.6:不推荐使用OP_COMMANDREPLY格式和协议,可能会在 MongoDB 的未来版本中删除。

警告 OP_COMMANDREPLY是 cluster internal,不应由 clients 或 drivers 实现。

OP_COMMANDREPLY是内部使用的有线协议消息,用于回复一个 MongoDB 服务器向另一个 MongoDB 服务器发出的 intra-cluster OP_COMMAND个请求。

OP_COMMANDREPLY的格式是:

struct {
   MsgHeader header;       // A standard wire protocol header
   document metadata;      // A BSON document containing any required metadata
   document commandReply;  // A BSON document containing the command reply
   document outputDocs;    // A variable number of BSON documents
}
领域描述
header标准邮件头,如标准消息标题中所述。
metadata可供系统将任何元数据附加到内部命令,这些内部命令不是 client 驱动程序提供的命令参数的一部分。
commandReply包含命令回复的 BSON 文档。
outputDocs对于可以_return 大量数据的命令很有用,例如查找或聚合。
此字段当前未使用。

脚注

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