Docs Menu
Docs Home
/
言語
/
PHP
/
PHP ライブラリ マニュアル
/
API ドキュメント
/
MongoDB\Collection

MongoDB\Collection::watch()

項目一覧

  • 定義
  • パラメーター
  • Return Values
  • エラーと例外
  • 例
  • その他の参照

バージョン 1.3 で追加。

定義

MongoDB\Collection::watch()

コレクションに対して変更ストリーム操作を実行します。 変更ストリームは、コレクション レベルの変更を監視できます。

function watch(
    array $pipeline = [],
    array $options = []
): MongoDB\ChangeStream

パラメーター

$pipeline : array|object
最初の$changeStreamステージに追加するステージのパイプライン。
$options : 配列

必要なオプションを指定する配列。

名前
タイプ
説明
batchSize
integer

カーソルのバッチ サイズを指定します。これは最初のaggregateコマンドと後続のgetMoreコマンドの両方に適用されます。 これにより、サーバーからの各応答で返される変更イベントの最大数が決まります。

batchSizeオプションに関係なく、変更ストリームの最初のaggregateコマンド応答には通常、開始点を設定するために別のオプションが使用されない限り、ドキュメントは含まれません（例: startAfter ）。

コーデック
MongoDB\Codec\DocumentCodec

ドキュメントのエンコードまたはデコードに使用するコーデック。 このオプションはtypeMapオプションと相互に排他的です。

デフォルトはコレクションのコーデック。 デフォルトのcodecオプションの継承は、 typeMapオプションの継承よりも優先されます。

バージョン 1.17 の新機能。

collation
array|object

照合順序を指定すると、大文字や小文字、アクセント記号など、string を比較するための言語独自のルールを指定できます。 照合を指定する場合、 localeフィールドは必須です。その他の照合フィールドはすべてオプションです。 フィールドの説明については、 「照合ドキュメント」 を参照してください。

MongoDB 4.2 以降では、 を省略する場合は単純なバイナリ比較がデフォルトになります。 以前のバージョンでは、単一のコレクションに対して変更ストリームが開かれると、そのコレクションのデフォルトの照合順序が継承されていました。

comment
混合

データベースプロファイラ、 currentOp出力、およびログから操作を追跡するのに役立つ任意のコメントを指定できるようにします。

MongoDB 4.4 以降では、有効な BSON タイプであればコメントに、任意の有効な BSON タイプ を使用できます。 以前のサーバー バージョンでは string 値のみがサポートされていました。

バージョン 1.13 の新機能。

fullDocument
string

アップデート操作のためにfullDocumentレスポンス フィールドに入力する方法を決定します。

デフォルトでは、変更ストリームは更新操作に対してフィールドのデルタのみを返します（ updateDescriptionフィールドを介して）。 fullDocumentは省略されます。 挿入操作と置換操作には常にfullDocumentフィールドが含まれます。 削除操作では、ドキュメントが存在しなくなるため フィールドが省略されます。

更新されたドキュメントの過半数がコミットした最新のバージョンを返すには、"updateLookup" を指定します。

MongoDB 6.0+ では、コレクションでchangeStreamPreAndPostImagesが有効になっている場合、変更されたドキュメントの変更後のイメージを返すことができます。 "whenAvalable" を指定すると、使用可能な場合は変更後のイメージが返され、使用できない場合は null 値が返されます。 変更後のイメージが使用可能な場合は「必須」を指定し、ない場合はエラーが発生します。

次の値がサポートされています。

  • MongoDB\Operation\Watch::FULL_DOCUMENT_UPDATE_LOOKUP

  • MongoDB\Operation\Watch::FULL_DOCUMENT_WHEN_AVAILABLE

  • MongoDB\Operation\Watch::FULL_DOCUMENT_REQUIRED

これは、 $changeStreamパイプライン ステージのオプションです。

fullDocumentBefore変更
string

fullDocumentBeforeChange応答フィールドに入力する方法を決定します。 デフォルトでは、 フィールドは省略されています。

MongoDB 6.0+ では、コレクションでchangeStreamPreAndPostImagesが有効になっている場合、変更されたドキュメントの変更前のイメージを返すことができます。 "whenAvalable" を指定すると、使用可能な場合は変更前のイメージが返され、使用できない場合は null 値が返されます。 変更前のイメージが使用可能な場合は「必須」を指定し、ない場合はエラーが発生します。

次の値がサポートされています。

  • MongoDB\Operation\Watch::FULL_DOCUMENT_BEFORE_CHANGE_WHEN_AVAILABLE

  • MongoDB\Operation\Watch::FULL_DOCUMENT_BEFORE_CHANGE_REQUIRED

これは、 $changeStreamパイプライン ステージのオプションです。

バージョン 1.13 の新機能。

maxAwaitTimeMS
integer

データが利用できない場合にサーバーが getMore 操作をブロックする時間の制限をミリ秒単位で示す正の整数。

ReadConcern

操作に使用する読み取り保証。 デフォルトはコレクションの読み取り保証 (read concern) です。

readPreference

操作に使用する読み取り設定。 コレクションの読み込み設定（read preference）がデフォルトで設定されます。

これは、最初の変更ストリームの集計と自動再開中のサーバー選択の両方に使用されます。

resumeAfter
array|object

新しい変更ストリームの論理的な開始点を指定します。 変更ストリームによって返されたドキュメントの_idフィールドはここで使用できます。

このオプションをstartAfterやstartAtOperationTimeと組み合わせて使用すると、サーバー エラーが発生します。 オプションは相互に排他的です。

これは、 $changeStreamパイプライン ステージのオプションです。

セッション

操作に関連付けるクライアント セッション。

showExpandedEvents
ブール値

true の場合、変更ストリームに追加の DDL イベントを含めるようにサーバーに指示します。 含まれる可能性のある追加のイベントは以下のとおりです。

  • createIndexes

  • dropIndexes

  • modify

  • create

  • shardCollection

  • reshardCollection （サーバー 6.1+）

  • refineCollectionShardKey （サーバー 6.1+）

これは 6.0 より前のサーバー バージョンではサポートされていないため、使用された場合は実行時に例外が発生します。

これは、 $changeStreamパイプライン ステージのオプションです。

バージョン 1.13 の新機能。

startAfter
array|object

新しい変更ストリームの論理的な開始点を指定します。 変更ストリームによって返されたドキュメントの_idフィールドはここで使用できます。 resumeAfterとは異なり、このオプションは「無効化」イベントの再開トークンで使用できます。

このオプションをresumeAfterやstartAtOperationTimeと組み合わせて使用すると、サーバー エラーが発生します。 オプションは相互に排他的です。

これは 4.2 より前のサーバー バージョンではサポートされていないため、使用された場合は実行時に例外が発生します。

これは、 $changeStreamパイプライン ステージのオプションです。

バージョン 1.5 の新機能。

startAtOperationTime

指定した場合、変更ストリームは、指定されたタイムスタンプの時点またはその後に発生した変更のみを提供します。 MongoDB 4.0 以降のサーバーからのコマンド応答には、ここで使用できるoperationTimeが含まれています。 デフォルトでは、最初のaggregateコマンドによって返されたoperationTimeが使用可能な場合は、

このオプションをresumeAfterやstartAfterと組み合わせて使用すると、サーバー エラーが発生します。 オプションは相互に排他的です。

これは 4.0 より前のサーバー バージョンではサポートされていないため、使用された場合は実行時に例外が発生します。

これは、 $changeStreamパイプライン ステージのオプションです。

typeMap
配列

型マップ カーソルに適用される 。これは、BSON ドキュメントが PHP 値に変換される方法を決定します。コレクションのタイプ マップがデフォルトになります。

Return Values

MongoDB\ChangeStreamオブジェクト（ イテレータ を介して変更ストリーム内のイベントを反復処理できる） インターフェースを使用します。

エラーと例外

MongoDB\Exception\UnexpectedValueException サーバーからのコマンド応答が不正な形式であった場合、。

MongoDB\Exception\UnsupportedExceptionオプションが使用され、選択したサーバーでサポートされていない場合（例: collation 、 readConcern 、 writeConcern ）。

MongoDB\Exception\InvalidArgumentException は、パラメータまたはオプションの解析に関連するエラーの場合は です。

MongoDB\Driver\Exception\RuntimeException 拡張レベルのその他のエラー（例:）。

例

この例では、変更ストリームを反復処理しながらイベントを報告します。

<?php
$uri = 'mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet';
$collection = (new MongoDB\Client($uri))->test->inventory;
$changeStream = $collection->watch();
for ($changeStream->rewind(); true; $changeStream->next()) {
    if ( ! $changeStream->valid()) {
        continue;
    }
    $event = $changeStream->current();
    if ($event['operationType'] === 'invalidate') {
        break;
    }
    $ns = sprintf('%s.%s', $event['ns']['db'], $event['ns']['coll']);
    $id = json_encode($event['documentKey']['_id']);
    switch ($event['operationType']) {
        case 'delete':
            printf("Deleted document in %s with _id: %s\n\n", $ns, $id);
            break;
        case 'insert':
            printf("Inserted new document in %s\n", $ns);
            echo json_encode($event['fullDocument']), "\n\n";
            break;
        case 'replace':
            printf("Replaced new document in %s with _id: %s\n", $ns, $id);
            echo json_encode($event['fullDocument']), "\n\n";
            break;
        case 'update':
            printf("Updated document in %s with _id: %s\n", $ns, $id);
            echo json_encode($event['updateDescription']), "\n\n";
            break;
    }
}

上記のスクリプトが変更ストリームを反復処理している間にドキュメントが挿入、更新、および削除されたと仮定すると、出力は次のようになります。

Inserted new document in test.user
{"_id":{"$oid":"5b329c4874083047cc05e60a"},"username":"bob"}
Inserted new document in test.products
{"_id":{"$oid":"5b329c4d74083047cc05e60b"},"name":"Widget","quantity":5}
Updated document in test.user with _id: {"$oid":"5b329a4f74083047cc05e603"}
{"updatedFields":{"username":"robert"},"removedFields":[]}

その他の参照

戻る

updateSearchIndex()

次へ

withOptions()