db.watch()（mongoshメソッド）

定義

db.watch( pipeline, options )

レプリカセットとシャーディングされたクラスターのみ

データベースの変更ストリーム カーソルを開き、 system以外のすべてのコレクションについてレポートします。

Parameter	タイプ	説明
pipeline	配列	任意。次の集計ステージの1つ以上で構成される集計パイプライン: $addFields $match $project $replaceRoot $replaceWith $redact $set $unset 変更イベント出力をフィルタリング/修正するためのパイプラインを指定します。 MongoDB 4.2 以降では、変更ストリームの集計パイプラインでイベントの _id フィールドが変更される場合、変更ストリームで例外がスローされるようになります。
options	ドキュメント	任意。 db.watch()の動作を変更する追加オプション。

options ドキュメントには、次のフィールドと値を含めることができます。

フィールド	タイプ	説明
resumeAfter	ドキュメント	任意。 変更ストリームの論理的な開始点として再開トークンを指定します。 invalidateイベント後に変更ストリームを再開するために使用することはできません。 resumeAfter は、startAfter および startAtOperationTime と排他関係にあります。
startAfter	ドキュメント	任意。 変更ストリームの論理的な開始点として再開トークンを指定します。 resumeAfterとは異なり、 startAfterは新しい変更ストリームを作成することで、 invalidateイベント後に通知を再開できます。 startAfter は、resumeAfter および startAtOperationTime と排他関係にあります。
fullDocument	string	任意。 デフォルトでは 、アップデートされたドキュメント全体ではなく、db.watch() アップデート操作によって変更されたフィールドのデルタが返されます。 fullDocumentを"updateLookup" db.watch()に設定すると、更新されたドキュメントの過半数がコミットした最新のバージョンを参照するよう に指示します。db.watch()fullDocumentは、updateDescription デルタに加えて、ドキュメント検索を含む フィールドを返します。 MongoDB 6.0 以降では、fullDocument を次のように設定できます。 "whenAvailable" これは、ドキュメントの挿入、置換、または更新後に、利用可能な場合、ドキュメントの変更後のイメージを出力するためです。 "required" ドキュメントの挿入、置換、またはアップデート後に、ドキュメントの変更後のイメージを出力します。変更後のイメージが利用できない場合、エラーが発生します。
fullDocumentBeforeChange	string	任意。デフォルトは、"off" に設定されています。 MongoDB 6.0 以降では、新しい fullDocumentBeforeChange フィールドを使用して次のように設定できます。 "whenAvailable" ドキュメントの置換、アップデート、または削除前に、利用可能な場合、ドキュメントの変更前のイメージを出力します。 "required" これは、ドキュメントが置換、更新、削除される前に、ドキュメントの変更前のイメージを出力するためです。変更前のイメージが利用できない場合、エラーが発生します。 "off" 変更前のドキュメントのイメージを非表示にします。デフォルトは "off" です。
batchSize	整数	任意。MongoDB クラスターからのレスポンスの各バッチで返す変更イベントの最大数を指定します。 cursor.batchSize() と同じ機能を持ちます。
maxAwaitTimeMS	整数	任意。空のバッチを返す前に、新しいデータ変更が変更ストリーム カーソルに報告されるまでサーバーが待機する最大時間（ミリ秒）。 デフォルトは 1000 ミリ秒です。
collation	ドキュメント	任意。照合ドキュメントを渡し、変更ストリーム カーソルの照合順序を指定します。 省略した場合、デフォルトはsimpleバイナリ比較になります。
startAtOperationTime	タイムスタンプ	任意。変更ストリームの開始点。過去の開始点を指定する場合、oplog の時間範囲内である必要があります。oplog の時間範囲を確認するには、rs.printReplicationInfo() を参照してください。 startAtOperationTime は、resumeAfter および startAfter と排他関係にあります。

次の値を返します。	変更イベント ドキュメント上のカーソル。 変更イベント ドキュメントの例については、「変更イベント」を参照してください。

Tip

db.collection.watch() および Mongo.watch()

互換性

このメソッドは、次の環境でホストされている配置で使用できます。

• MongoDB Atlas はクラウドでの MongoDB 配置のためのフルマネージド サービスです

• MongoDB Enterprise: サブスクリプションベースの自己管理型 MongoDB バージョン

• MongoDB Community: ソースが利用可能で、無料で使用できる自己管理型の MongoDB のバージョン

可用性

動作

• admin 、 local 、またはconfigデータベースではdb.watch()を実行できません。

• db.watch() データを保持しているノードの大半に反映されたデータ変更についてのみ通知します。

• 変更ストリーム カーソルは、次のいずれかが発生するまで開いたままになります。

  • カーソルが明示的に閉じている。

  • 無効化イベントが発生している（コレクションの削除や名前の変更など）。

  • MongoDBデプロイへの接続が閉じているか、タイムアウトになっている。詳細については、「動作」を参照してください。

  • 配置がシャーディングされたクラスターの場合、シャードを削除すると、開いている変更ストリームのカーソルが閉じることがあります。閉じた変更ストリームのカーソルは完全に再開できない場合があります。

• 存在しないデータベースに対してdb.watch()を実行できます。 ただし、データベースが作成され、データベースを削除すると、変更ストリーム カーソルが閉じます。

アクセス制御

アクセス制御を使用して実行中の場合、ユーザーは データベースfind リソース に対してchangeStream および 特権アクションを持っている必要があります。つまり、ユーザーは、次の 特権 を付与する ロール を持っていなければなりません。

{ resource: { db: <dbname>, collection: "" }, actions: [ "find", "changeStream"] }

組み込みの read ロールにより、適切な権限が付与されます。

カーソルの反復

MongoDB には、カーソルを反復処理する方法が複数用意されています。

cursor.hasNext() メソッドの場合、ブロックして次のイベントを待機します。watchCursor カーソルを監視してイベントを反復処理するには、次のように hasNext() を使用します。

while (!watchCursor.isClosed()) {
   if (watchCursor.hasNext()) {
     firstChange = watchCursor.next();
     break;
   }
}

cursor.tryNext() メソッドはノンブロッキングです。watchCursor カーソルを監視してイベントを反復処理するには、次のように tryNext() を使用します。

while (!watchCursor.isClosed()) {
  let next = watchCursor.tryNext()
  while (next !== null) {
    printjson(next);
    next = watchCursor.tryNext()
  }
}

例

mongoshの次の操作は、 hrデータベース上で変更ストリーム カーソルを開きます。 返されたカーソルは、そのデータベース内のすべてのsystem以外のコレクションに対するデータ変更を報告します。

watchCursor = db.getSiblingDB("hr").watch()

カーソルを反復処理し、新しいイベントをチェックする。cursor.isClosed() メソッドを cursor.tryNext() メソッドと組み合わせて使用し、変更ストリーム カーソルが閉じられ、かつ最新のバッチにオブジェクトが残っていない場合にのみループが終了するようにします。

while (!watchCursor.isClosed()) {
  let next = watchCursor.tryNext()
  while (next !== null) {
    printjson(next);
    next = watchCursor.tryNext()
  }
}

変更ストリーム出力の詳細なドキュメントについては、 「変更イベント」を参照してください。