Docs Menu

MongoDB ワイヤプロトコル

注意

この MongoDB ワイヤプロトコル仕様は、クリエイティブ・コモンズ 表示 - 非営利 - 継承 3.0 アメリカ合衆国ライセンスに基づいて使用許諾されます。この素材を商用データベースやサービスとしてのデータベースの作成など、いかなる商用目的でも使用または改変することはできません。

MongoDB ワイヤプロトコルは、シンプルなソケットベースのリクエスト/レスポンス形式のプロトコルです。クライアントは通常の TCP/IP ソケットを介してデータベース サーバーと通信します。

クライアントは通常の TCP/IP ソケットでデータベースに接続する必要があります。

mongod および mongos インスタンスのデフォルトのポート番号は 27017 です。mongodmongos のポート番号は設定可能であり、変更となる可能性があります。

MongoDB ワイヤプロトコルの整数はすべて、リトルエンディアンのバイト順を使用します。つまり、最下位バイトが先になります。

MongoDB は、クライアント リクエストとデータベース応答の両方にOP_MSG命令コードを使用します。 MongoDB の古いバージョンで使用されているメッセージ形式がいくつかあり、これらはOP_MSGによって非推奨になっています。

注意

  • このページでは、C のような struct を使用してメッセージ構造を記述します。

  • このドキュメントで使用されている型(int32cstring など)は、 BSON仕様 で定義されている型と同じです。

  • 繰り返しを示すために、ドキュメントは BSON 仕様 のアスタリスク表記を使用します 。たとえば、 int64*は、指定されたタイプの 1 つ以上を 1 つずつソケットに書込み可能であることを示します。

  • 標準のメッセージ ヘッダーのタイプは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 requestIDresponseToメッセージの フィールドに返されます。クライアントは フィールドと フィールドを使用して、クエリ応答を元のクエリに関連付けることができます。

responseTo

データベースからのメッセージの場合、これはクライアントからのrequestID OP_QUERY メッセージまたは OP_GET_MORErequestID responseToメッセージから取得された になります。クライアントは フィールドと フィールドを使用して、クエリ応答を元のクエリに関連付けることができます。

opCode

メッセージのタイプ。詳細については、「 リクエスト命令コード 」を参照してください。

注意

  • MongoDB2.6 およびmaxWireVersion3 以降、MongoDB insertドライバーは、確認済みの書込み(write)に、update 、 、delete の代わりにOP_INSERT 、 、OP_UPDATE の データベースコマンドをOP_DELETE 使用します。ほとんどのドライバーは、確認されていない書込みに命令コードを引き続き使用します。

  • MongoDB バージョン 4.2 では、非推奨の内部OP_COMMANDOP_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 {
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

4メッセージは CRC-32 C [2 ]チェックサム値値 を含む バイトで終わる。詳細については、「 チェックサム値 」を参照してください。

1

moreToCome

受信先から追加のアクションがなくても、このメッセージの後に別のメッセージが送信されます。送信がブロックされ、デッドロックが発生する可能性があるため、受信先は moreToCome が 0 に設定されたメッセージを受信するまで、別のメッセージを送信してはいけませんmoreToCome ビットがセットされたリクエストは、応答を受け取りません。応答では、exhaustAllowed ビットが設定されたリクエストに応答する場合にのみこれが設定されます。

16

exhaustAllowed

クライアントは、moreToComeビットを使用してこのリクエストに対する複数の応答を準備します。リクエストに moreToCome ビットが設定されていない限り、サーバーはこのビットが設定された応答を生成しません。

これにより、要求元のネットワークレイヤーが準備できた場合にのみ、複数の応答が送信されます。

重要

MongoDB 3.6はこのフラグを無視し、単一のメッセージで応答します。

OP_MSG メッセージには 1 つ以上のセクションが含まれます。各セクションは、そのタイプを示す kind バイトで始まります。kind バイト以降はすべてセクションのペイロードを構成するものです。

使用可能なセクションの種類は次のとおりです。

ボディ セクションは単一の BSON オブジェクトとしてエンコードされます。BSON オブジェクト内のサイズは、セクションのサイズとしても機能します。このセクションの種類は、標準のコマンド リクエストおよび応答のボディです。

すべてのトップレベル フィールドはユニークな名前を持つ必要があります

タイプ
説明

int32

セクションのサイズ(バイト単位)。

C String

ドキュメント シーケンス識別子。現在のすべてのコマンドでは、このフィールドはボディセクションから置き換えられるフィールド(ネストされている可能性あり)です。

このフィールドはボディ セクションにも存在してはいけません

0 個以上の BSON オブジェクト

  • オブジェクトはセパレーターなしで連続で配列されます。

  • 各オブジェクトは、サーバーの maxBSONObjectSize に制限されます。すべてのオブジェクトの組み合わせはmaxBSONObjSize に制限されません。

  • size バイトを使い果たすと、ドキュメント シーケンスは終了します。

  • パーサーは、言語レベルのオブジェクトに変換するときに、シーケンス識別子で指定されたパスにある配列としてこれらのオブジェクトをボディにマージすることを選択できます。

各メッセージは、チェックサム値自体を除く、メッセージ中のすべてのバイトをカバーする CRC-32C [2] チェックサムで終わる可能性があります。

MongoDB 4.2 以降:

  • mongodインスタンス、 mongosインスタンス、 mongo shell インスタンスは、TLS/SSL 接続を使用していない場合、チェックサム値付きのメッセージを交換します。

  • mongodインスタンス、 mongosインスタンス、 mongo shell インスタンスは、TLS/SSL 接続を使用している場合、チェックサム値をスキップします。

ドライバーや古いバイナリの場合、チェックサム値付きのメッセージが表示されても、チェックサム値を無視します。

チェックサム値の存在は、checksumPresent フラグ ビットによって示されます。

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はアップサートに対応します。 これが設定されている場合、一致するドキュメントが見つからない場合、データベースは指定されたオブジェクトを コレクションに挿入します。

  • 1は MultiUpdate に対応します。設定すると、データベースはコレクション内の一致するオブジェクトをすべて更新します。 それ以外の場合は、最初に一致するドキュメントのみが更新されます。

  • 2-31 は予約されています。 0 に設定する必要があります。

selector

更新するドキュメントの選択に対するクエリを指定する BSON ドキュメント。

update

実行される更新を指定する BSON ドキュメント。 更新の指定の詳細については、更新操作のドキュメントを参照してください。

OP_UPDATE メッセージには応答しません。

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
}
フィールド
説明

header

flags

操作のフラグを指定するビットベクトル。 ビット値は、次のものに対応します。

  • 0は ContinueOnError に対応します。 これが設定されている場合、データベースは一括挿入の処理を停止しません(例: 重複した ID による )。 これにより、一括挿入は一連の単一挿入と同様に動作しますが、最後の 1 つだけでなくいずれかの挿入が失敗した場合は lastError が設定されます。 複数のエラーが発生した場合、 getLastError によって最新のエラーのみが報告されます。

  • 1-31 は予約されています。 0 に設定する必要があります。

fullCollectionName

完全なコレクション名。 (名前空間)。 完全なコレクション名は、データベース名とコレクション名を連結したもので、連結に.を使用します。 たとえば、データベースfooとコレクションbarの場合、完全なコレクション名はfoo.barです。

documents

コレクションに挿入する 1 つ以上のドキュメント。 複数ある場合は、順番にソケットに書込まれます。

OP_INSERT メッセージには応答しません。

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は OplogReplace に対応します。 MongoDB 4.4 以降では、oplog の適格なクエリに対して最適化が自動的に実行されるため、このフラグを指定する必要はありません。 詳細については、 oplogReplaceを参照してください。

  • 4は NoCursorTimeout に対応します。 サーバーは通常、非アクティブ期間( 10分)の後にアイドル カーソルをタイムアウトして、過剰なメモリの使用を防ぎます。 それを防ぐには、このオプションを に設定します。

  • 5は AwaitData に対応します。 tailableCursor と併用します。 データの末尾にある場合は、データを返さずに、一時的にブロックします。 タイムアウト期間が経過すると、通常通りデータを返します。

  • 6は エクスポート に相当します。 クライアントがクエリされたすべてのデータを完全に読み取ることを前提として、複数の " more" パッケージでデータを完全にストリーミングします。 多くのデータを取得していて、すべてを削減する必要があることがわかっている場合は、より高速になります。 注: クライアントは接続を閉じない限り、すべてのデータを読み取れません。

  • 7は部分に対応します。 一部のシャードがダウンした場合(エラーがスローされる代わりに)、 mongos から部分的な結果が取得されます

  • 8-31 は予約されています。 0 に設定する必要があります。

fullCollectionName

完全なコレクション名。 (名前空間)。 完全なコレクション名は、データベース名とコレクション名を連結したもので、連結に.を使用します。 たとえば、データベースfooとコレクションbarの場合、完全なコレクション名はfoo.barです。

numberToSkip

クエリの結果を返すときに、省略するドキュメントの数を設定します - 結果データセットの最初のドキュメントから。

numberToReturn

クエリへの最初の OP_REPly メッセージのドキュメント数を制限します。ただし、 を超える結果がある場合は、データベースによりカーソルが確立され、cursorID numberToReturnがクライアントに返されます。クライアントドライバーが「制限」機能( SQLの LIT キーワードなど)を提供する場合、指定された数以上のドキュメントが呼び出し元のアプリケーションに返されないようにするかは、クライアントドライバーの判断になります。 がnumberToReturn 0の場合、db はデフォルトの戻りサイズを使用します。数値が負の場合、データベースはその数値を返し、カーソルを閉じます。そのクエリのそれ以上の結果は取得できません。 がnumberToReturn 1の場合、サーバーはそれを-1 として扱います(カーソルを自動的に閉じます)。

query

クエリを表す BSON ドキュメント。 クエリには 1 つ以上の要素が含まれます。結果セットに含めるドキュメントは、すべて一致する必要があります。 指定可能な要素には、 $query$orderby$hint$explainなどがあります。

returnFieldsSelector

任意。 返されるドキュメントのフィールドを制限する BSON ドキュメント。 returnFieldsSelectorには 1 つ以上の要素が含まれています。各要素は返されるフィールドの名前と、整数値1です。 JSON 表記では、 abcのフィールドに制限するreturnFieldsSelectorは次のようになります。

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

データベースは、OP_REPly メッセージを含むOP_QUERYメッセージに応答します。

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 numberToReturnがクライアントに返されます。クライアントドライバーが「制限」機能( SQLの LIT キーワードなど)を提供する場合、指定された数以上のドキュメントが呼び出し元のアプリケーションに返されないようにするかは、クライアントドライバーの判断になります。 がnumberToReturn 0の場合、db はデフォルトの戻りサイズを使用します。

cursorID

OP_REPly で取得されたカーソル識別子です。これは、データベースから取得された値である必要があります。

データベースは、OP_REPly メッセージとともにOP_GET_MOREメッセージに応答します。

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.
}
フィールド
説明

header

ZERO

0 の整数値です。将来の使用のために予約されています。

fullCollectionName

完全なコレクション名。 (名前空間)。 完全なコレクション名は、データベース名とコレクション名を連結したもので、連結に.を使用します。 たとえば、データベースfooとコレクションbarの場合、完全なコレクション名はfoo.barです。

flags

操作のフラグを指定するビットベクトル。 ビット値は、次のものに対応します。

  • 0は SingleRemove に対応します。 これが設定されている場合、データベースはコレクション内の最初に一致するドキュメントのみを削除します。 そうでない場合、一致するすべてのドキュメントが削除されます。

  • 1-31 は予約されています。 0 に設定する必要があります。

selector

削除するドキュメントを選択するために使用されたクエリを表す BSON document セレクターには 1 つ以上の要素が含まれます。これらはすべて、コレクションから削除されるドキュメントと一致する必要があります。

OP_DELETE メッセージには応答しません。

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 に対して 0 を返すまで読み取る)場合、カーソルを強制終了する必要はありません。

どんな命令コードでも圧縮して 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
}
フィールド
説明

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

将来の使用のために予約されています。

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はクエリ失敗に対応します。 クエリが失敗した場合に設定されます。 結果は、失敗を説明する "$err" フィールドを含む 1 つのドキュメントで構成されます。

  • 2は ShardConfigStale に対応します。 ドライバーはこれを無視する必要があります。 このセットはmongosのみに表示されます。その場合、サーバーから構成を更新する必要があります。

  • 3は AwaitCapable に対応します。 サーバーが AwaitData Query オプションをサポートしている場合に設定されます。 そうでない場合、クライアントは 追尾可能 (tailable) カーソルの getMore と の間でわずかに休止する必要があります。 mongodバージョン 1.6 は AwaitData をサポートしており、常に AwaitCapable を設定します。

  • 4-31 は予約されています。 無視します。

cursorID

cursorIDこの OP_REPLY が構成要素である 。クエリの結果セットが 1 つのイベントメッセージに収まる場合、cursorID は0 になります。このcursorID は、より多くのデータを取得するために使用される OP_GET_MORE メッセージで使用する必要があります。また、OP_KILL_CURSORS メッセージが不要になった場合は、クライアントによって閉じられる必要があります。

startingFrom

カーソル内の開始位置。

numberReturned

応答内のドキュメントの数。

documents

返されたドキュメント。

脚注

[2]1232 ビット CRC は、 Castagnoli polynomial を使用して計算されたもので、 https://tools.ietf.org/html/rfc4960 #page-140 で説明されています。