MongoDB ワイヤプロトコル
注意
この MongoDB ワイヤプロトコル仕様は、クリエイティブ・コモンズ 表示 - 非営利 - 継承 3.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 }
フィールド | 説明 |
---|---|
| メッセージの合計サイズ(バイト単位)。この合計には、メッセージ長を保持する 4 バイトが含まれます。 |
| このメッセージを一意に識別するクライアントまたはデータベースが生成した識別子。クライアントが生成したメッセージ( OP_QUERY や OP_GET_MORE |
| データベースからのメッセージの場合、これはクライアントからの |
| メッセージのタイプ。詳細については、「 リクエスト命令コード 」を参照してください。 |
リクエスト命令コード
注意
MongoDB2.6 および
maxWireVersion
3
以降、MongoDBinsert
ドライバーは、確認済みの書込み(write)に、update
、 、delete
の代わりにOP_INSERT
、 、OP_UPDATE
の データベースコマンドをOP_DELETE
使用します。ほとんどのドライバーは、確認されていない書込みに命令コードを引き続き使用します。MongoDB バージョン 4.2 では、非推奨の内部
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 |
---|---|---|
| 2013 | MongoDB 3.6で導入されている形式を使用してメッセージを送信します。 |
OP_REPLY Deprecated in MongoDB 5.0. | 1 | クライアント リクエストに応答します。 |
OP_UPDATE Deprecated in MongoDB 5.0. | 2001 | Update document. |
OP_INSERT Deprecated in MongoDB 5.0. | 2002 | 新しいドキュメントを挿入します。 |
| 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 | クライアントがカーソルを終了したことをデータベースに通知します。 |
| 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 }
フィールド | 説明 |
---|---|
| 標準メッセージ ヘッダー(「 標準メッセージ ヘッダー 」で説明)。 |
| メッセージ フラグを含む整数ビットマスク(「 フラグ ビット 」で説明)。 |
| メッセージ本文セクション(「 セクション 」で説明)。 |
| 任意の CRC-32 Cチェックサム値値 (「 チェックサム値 」で説明)。 |
フラグ ビット
flagBits
整数は、 OP_MSG
の形式と動作を変更するビットマスク エンコード フラグです。
最初の 16 ビット(0 ~ 15)が必須で、不明なビットが設定されている場合、パーサーはエラーにする必要があります。
最後の 16 ビット(16~31)は任意であり、パーサーは不明なセットビットを無視する必要があります。プロキシやその他のメッセージフォワーダーは、メッセージを転送する前に不明な任意ビットをクリアする必要があります。
ビット | 名前 | リクエスト | 応答 | 説明 |
---|---|---|---|---|
0 |
| ✓ | ✓ | 4メッセージは CRC-32 C [2 ]チェックサム値値 を含む バイトで終わる。詳細については、「 チェックサム値 」を参照してください。 |
1 |
| ✓ | ✓ | 受信先から追加のアクションがなくても、このメッセージの後に別のメッセージが送信されます。送信がブロックされ、デッドロックが発生する可能性があるため、受信先は |
16 |
| ✓ | クライアントは、 これにより、要求元のネットワークレイヤーが準備できた場合にのみ、複数の応答が送信されます。 重要MongoDB 3.6はこのフラグを無視し、単一のメッセージで応答します。 |
セクション
OP_MSG
メッセージには 1 つ以上のセクションが含まれます。各セクションは、そのタイプを示す kind
バイトで始まります。kind
バイト以降はすべてセクションのペイロードを構成するものです。
使用可能なセクションの種類は次のとおりです。
種類 0: ボディ
ボディ セクションは単一の BSON オブジェクトとしてエンコードされます。BSON オブジェクト内のサイズは、セクションのサイズとしても機能します。このセクションの種類は、標準のコマンド リクエストおよび応答のボディです。
すべてのトップレベル フィールドはユニークな名前を持つ必要があります。
種類 1: ドキュメント シーケンス
タイプ | 説明 |
---|---|
int32 | セクションのサイズ(バイト単位)。 |
C String | ドキュメント シーケンス識別子。現在のすべてのコマンドでは、このフィールドはボディセクションから置き換えられるフィールド(ネストされている可能性あり)です。 このフィールドはボディ セクションにも存在してはいけません。 |
0 個以上の BSON オブジェクト |
|
チェックサム値
各メッセージは、チェックサム値自体を除く、メッセージ中のすべてのバイトをカバーする CRC-32C [2] チェックサムで終わる可能性があります。
MongoDB 4.2 以降:
mongod
インスタンス、mongos
インスタンス、mongo
shell インスタンスは、TLS/SSL 接続を使用していない場合、チェックサム値付きのメッセージを交換します。mongod
インスタンス、mongos
インスタンス、mongo
shell インスタンスは、TLS/SSL 接続を使用している場合、チェックサム値をスキップします。
ドライバーや古いバイナリの場合、チェックサム値付きのメッセージが表示されても、チェックサム値を無視します。
チェックサム値の存在は、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 }
フィールド | 説明 |
---|---|
| メッセージ ヘッダー(「 標準メッセージ ヘッダー 」で説明)。 |
| 0 の整数値です。将来の使用のために予約されています。 |
| 完全なコレクション名。 (名前空間)。 完全なコレクション名は、データベース名とコレクション名を連結したもので、連結に |
| 操作のフラグを指定するビットベクトル。 ビット値は、次のものに対応します。
|
| 更新するドキュメントの選択に対するクエリを指定する BSON ドキュメント。 |
| 実行される更新を指定する BSON ドキュメント。 更新の指定の詳細については、更新操作のドキュメントを参照してください。 |
OP_UPDATE メッセージには応答しません。
OP_INSERT
MongoDB 5.0では非推奨 。
OP_INSERT メッセージは、1 つ以上のドキュメントをコレクションに挿入するために使用されます。 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 }
フィールド | 説明 |
---|---|
| メッセージ ヘッダー(「 標準メッセージ ヘッダー 」で説明)。 |
| 操作のフラグを指定するビットベクトル。 ビット値は、次のものに対応します。
|
| 完全なコレクション名。 (名前空間)。 完全なコレクション名は、データベース名とコレクション名を連結したもので、連結に |
| コレクションに挿入する 1 つ以上のドキュメント。 複数ある場合は、順番にソケットに書込まれます。 |
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. }
フィールド | 説明 | |
---|---|---|
| メッセージ ヘッダー(「 標準メッセージ ヘッダー 」で説明)。 | |
| 操作のフラグを指定するビットベクトル。 ビット値は、次のものに対応します。
| |
| 完全なコレクション名。 (名前空間)。 完全なコレクション名は、データベース名とコレクション名を連結したもので、連結に | |
| クエリの結果を返すときに、省略するドキュメントの数を設定します - 結果データセットの最初のドキュメントから。 | |
| クエリへの最初の OP_REPly メッセージのドキュメント数を制限します。ただし、 を超える結果がある場合は、データベースによりカーソルが確立され、 | |
| クエリを表す BSON ドキュメント。 クエリには 1 つ以上の要素が含まれます。結果セットに含めるドキュメントは、すべて一致する必要があります。 指定可能な要素には、 | |
| 任意。 返されるドキュメントのフィールドを制限する BSON ドキュメント。
|
データベースは、OP_REPly メッセージを含むOP_QUERYメッセージに応答します。
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 }
フィールド | 説明 |
---|---|
| メッセージ ヘッダー(「 標準メッセージ ヘッダー 」で説明)。 |
| 0 の整数値です。将来の使用のために予約されています。 |
| 完全なコレクション名。 (名前空間)。 完全なコレクション名は、データベース名とコレクション名を連結したもので、連結に |
| クエリへの最初の OP_REPly メッセージのドキュメント数を制限します。ただし、 を超える結果がある場合は、データベースによりカーソルが確立され、 |
| OP_REPly で取得されたカーソル識別子です。これは、データベースから取得された値である必要があります。 |
データベースは、OP_REPly メッセージとともにOP_GET_MOREメッセージに応答します。
OP_DELETE
MongoDB 5.0では非推奨 。
OP_DELETE メッセージは、コレクションから 1 つ以上のドキュメントを削除するために使用されます。 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. }
フィールド | 説明 |
---|---|
| メッセージ ヘッダー(「 標準メッセージ ヘッダー 」で説明)。 |
| 0 の整数値です。将来の使用のために予約されています。 |
| 完全なコレクション名。 (名前空間)。 完全なコレクション名は、データベース名とコレクション名を連結したもので、連結に |
| 操作のフラグを指定するビットベクトル。 ビット値は、次のものに対応します。
|
| 削除するドキュメントを選択するために使用されたクエリを表す BSON document セレクターには 1 つ以上の要素が含まれます。これらはすべて、コレクションから削除されるドキュメントと一致する必要があります。 |
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 }
フィールド | 説明 |
---|---|
| メッセージ ヘッダー(「 標準メッセージ ヘッダー 」で説明)。 |
| 0 の整数値です。将来の使用のために予約されています。 |
| メッセージにあるカーソル ID の数。 |
| 閉じるカーソル ID の「配列」。 複数ある場合は、順番にソケットに書込まれます。 |
カーソルが使い果たされるまで読み取られる( OP_QUERYまたはOP_GET_MOREがカーソル ID に対して 0 を返すまで読み取る)場合、カーソルを強制終了する必要はありません。
OP_COMPRESSED
どんな命令コードでも圧縮して OP_COMPRESSED ヘッダーにラップすることができます。 OP_COMPRESSED メッセージには、元の圧縮された opcode メッセージと、その処理および解凍に必要なメタデータが含まれています。
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 }
フィールド | 説明 |
---|---|
| メッセージ ヘッダー(「 標準メッセージ ヘッダー 」で説明)。 |
| ラップされた命令コードの値を格納します。 |
| 収縮した |
| メッセージを圧縮した圧縮プログラムの ID。 |
|
|
各コンプレッサーには、以下の通り、あらかじめ定義されたコンプレッサー ID が割り当てられます。
compressorId | ハンドシェイク値 | 説明 |
---|---|---|
| noop | メッセージの内容は非圧縮です。これはテストに使用されます。 |
| Snappy | メッセージの内容は snappy を使用して圧縮されています。 |
| zlib | メッセージの内容は zlib を使用して圧縮されています。 |
| zstd | メッセージの内容は zstd を使用して圧縮されています。 |
| 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 }
フィールド | 説明 |
---|---|
| メッセージ ヘッダー(「 標準メッセージ ヘッダー 」で説明)。 |
| フラグを指定するためのビットベクトル。 ビット値は、次のものに対応します。
|
|
|
| カーソル内の開始位置。 |
| 応答内のドキュメントの数。 |
| 返されたドキュメント。 |
脚注
[2] | (1 、2 )32 ビット CRC は、 Castagnoli polynomial を使用して計算されたもので、 https://tools.ietf.org/html/rfc4960 #page-140 で説明されています。 |