MongoDB ワイヤプロトコル
注意
この MongoDB ワイヤプロトコル仕様は、クリエイティブ・コモンズ 表示 - 非営利 - 継承 3.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仕様 で定義されている型と同じです。
標準メッセージ ヘッダー
一般的に、各メッセージは標準的なメッセージ ヘッダーと、それに続くリクエスト固有のデータから構成されます。標準のメッセージ ヘッダーは、次のように構成されています。
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 }
フィールド | 説明 |
|---|---|
messageLength | メッセージの合計サイズ（バイト単位）。この合計には、メッセージ長を保持する 4 バイトが含まれます。 |
requestID | メッセージを一意に識別するクライアントまたはデータベースが生成した識別子。 |
responseTo | クライアントからのメッセージから取得された requestID。 |
opCode | メッセージのタイプ。 詳細については、「命令コード」を参照してください。 |
命令コード
MongoDB は、次の opCode 値を使用します。
命令コード名 | 値 | Comment |
|---|---|---|
OP_COMPRESSED | 2012 | 圧縮を使用して他の命令コードをラップします。 |
OP_MSG | 2013 | 標準形式でメッセージを送信します。クライアント リクエストとデータベース応答の両方に使用されます。 |
OP_REPLYDeprecated in MongoDB 5.0. Removed in MongoDB 5.1. | 1 | クライアント リクエストに応答します。 responseTo が設定されています。 |
OP_UPDATEDeprecated in MongoDB 5.0. Removed in MongoDB 5.1. | 2001 | Update document. |
OP_INSERTDeprecated in MongoDB 5.0. Removed in MongoDB 5.1. | 2002 | 新しいドキュメントを挿入します。 |
RESERVED | 2003 | 以前は OP_GET_BY_OID に使用されていました。 |
OP_QUERYDeprecated in MongoDB 5.0. Removed in MongoDB 5.1. | 2004 | コレクションをクエリします。 |
OP_GET_MOREDeprecated in MongoDB 5.0. Removed in MongoDB 5.1. | 2005 | クエリからより多くのデータを取得します。「カーソル」を参照してください。 |
OP_DELETEDeprecated in MongoDB 5.0. Removed in MongoDB 5.1. | 2006 | ドキュメントを削除します。 |
OP_KILL_CURSORSDeprecated in MongoDB 5.0. Removed in MongoDB 5.1. | 2007 | クライアントがカーソルを終了したことをデータベースに通知します。 |
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_MSG
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）は任意であり、パーサーは不明なセットビットを無視する必要があります。プロキシやその他のメッセージフォワーダーは、メッセージを転送する前に不明な任意ビットをクリアする必要があります。
ビット | 名前 | リクエスト | 応答 | 説明 |
|---|---|---|---|---|
0 | checksumPresent | ✓ | ✓ | |
1 | moreToCome | ✓ | ✓ | 受信先から追加のアクションがなくても、このメッセージの後に別のメッセージが送信されます。送信がブロックされ、デッドロックが発生する可能性があるため、受信先は moreToCome が 0 に設定されたメッセージを受信するまで、別のメッセージを送信してはいけません。moreToCome ビットがセットされたリクエストは、応答を受け取りません。応答では、exhaustAllowed ビットが設定されたリクエストに応答する場合にのみこれが設定されます。 |
16 | exhaustAllowed | ✓ | クライアントは、 これにより、要求元のネットワークレイヤーが準備できた場合にのみ、複数の応答が送信されます。 |
セクション
OP_MSG メッセージには 1 つ以上のセクションが含まれます。各セクションは、そのタイプを示す kind バイトで始まります。kind バイト以降はすべてセクションのペイロードを構成するものです。
使用可能なセクションの種類は次のとおりです。
種類 0: ボディ
ボディ セクションは単一の BSON オブジェクトとしてエンコードされます。BSON オブジェクト内のサイズは、セクションのサイズとしても機能します。このセクションの種類は、標準のコマンド リクエストおよび応答のボディです。
すべてのトップレベル フィールドはユニークな名前を持つ必要があります。
種類 1: ドキュメント シーケンス
タイプ | 説明 |
|---|---|
int32 | セクションのサイズ（バイト単位）。 |
C String | ドキュメント シーケンス識別子。現在のすべてのコマンドでは、このフィールドはボディセクションから置き換えられるフィールド（ネストされている可能性あり）です。 このフィールドはボディ セクションにも存在してはいけません。 |
0 個以上の BSON オブジェクト |
|
Kind 2
このセクションは、内部目的で使用されます。
チェックサム値
各メッセージは、チェックサム値自体を除く、メッセージ中のすべてのバイトをカバーする CRC-32C [2] チェックサムで終わる可能性があります。
TLS/SSL 接続を使用しない場合、mongod インスタンスと mongos インスタンスはチェックサム値付きのメッセージを交換します。
TLS/SSL 接続を使用する場合、mongod インスタンスと mongos インスタンスはチェックサム値をスキップします。
ドライバーや古いバイナリの場合、チェックサム値付きのメッセージが表示されても、チェックサム値を無視します。
チェックサム値の存在は、checksumPresent フラグ ビットによって示されます。
レガシー命令コード
MongoDB 5.1 以降では、OP_MSG が優先されるため、次の命令コードは排除されています。
OP_DELETEOP_GET_MOREOP_INSERTOP_KILL_CURSORSOP_QUERY[1]OP_REPLYOP_UPDATE
古いバージョンの MongoDB を実行していて、以前の命令コードに関する詳細情報が必要な場合は、「レガシー命令コード」を参照してください。
脚注
| [1] | MongoDB 5.1 では、OP_QUERY 検索操作と OP_QUERY コマンドの両方のサポートが削除されました。例外として、OP_QUERY は、接続ハンドシェイクの一部として hello コマンドと isMaster コマンドの実行は引き続きサポートされます。 |
| [2] | （1、2） Castagnoli polynomial を使用して計算された 32 ビット CRC（https://tools.ietf.org/html/rfc4960 #page-140 参照）。 |