MongoDB\Collection::updateMany()

定義

MongoDB\Collection::updateMany()

フィルター条件に一致するすべてのドキュメントを更新します。

function updateMany(
    array|object $filter,
    array|object $update,
    array $options = []
): MongoDB\UpdateResult

パラメーター

$filter : array|object

更新するドキュメントを指定するフィルター条件。

$update : array|object

更新するフィールドと値の組み合わせと、関連する更新演算子を指定します。$update は MongoDB の更新演算子を使用します。このパラメーターとして集計パイプラインを渡すこともできます。

$options : 配列

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

名前	タイプ	説明
arrayFilters	配列	配列フィールドの更新操作でどの配列要素を変更するかを決定するフィルタードキュメントの配列。バージョン 1.3 で追加。
bypassDocumentValidation	ブール値	`true`の場合、書込み操作によってドキュメントレベルの検証を回避できます。デフォルトは`false`です。
collation	array\|object	照合順序を指定すると、大文字や小文字、アクセント記号など、string を比較するための言語独自のルールを指定できます。照合を指定する場合、 `locale`フィールドは必須です。その他の照合フィールドはすべてオプションです。フィールドの説明については、「照合ドキュメント」を参照してください。照合が指定されていないが、コレクションにデフォルトの照合がある場合、操作はコレクションに指定された照合を使用します。コレクションにも操作にも照合が指定されていない場合、MongoDB では以前のバージョンで使用されていた単純なバイナリ比較によって string が比較されます。
comment	混合	データベースプロファイラ、 currentOp出力、およびログから操作を追跡するのに役立つ任意のコメントを指定できるようにします。このオプションは MongoDB 4.4 以降で使用可能であり、古いサーバーバージョンで指定すると実行時に例外が発生します。バージョン 1.13 の新機能。
hint	string\|array\|object	使用するインデックス。インデックス名を string またはインデックスキーパターンをドキュメントとして指定します。指定すると、クエリシステムはヒント指定したインデックスを使用するプランのみを考慮します。このオプションは MongoDB 4.4 以降で使用可能であり、古いサーバーバージョンで指定すると実行時に例外が発生します。バージョン 1.6 の新機能.
let	array\|object	パラメーター名と値のマップ。値は、ドキュメントフィールドを参照しない定数または閉じた式である必要があります。その後、パラメーターには集計式コンテキストで変数としてアクセスできます（例: `$$var` ）。これは 5.0 より前のサーバーバージョンではサポートされていないため、使用された場合は実行時に例外が発生します。バージョン 1.13 の新機能。
セッション	MongoDB\Driver\Session	操作に関連付けるクライアントセッション。バージョン 1.3 で追加。
upsert	ブール値	`true`に設定すると、クエリ条件に一致するドキュメントがない場合に新しいドキュメントが作成されます。デフォルト値は`false`で、一致するものが見つからない場合は新しいドキュメントを挿入しません。
writeConcern	MongoDB\Driver\WriteConcern	操作に使用する書込み保証 ( write concern )。コレクションの書込み保証 (write concern) のデフォルトです。トランザクションの一部である個々の操作に対して書込み保証 (write concern)を指定することはできません。代わりに、トランザクションを開始するときに`writeConcern` オプションを設定します。

Return Values

MongoDB\UpdateResultMongoDB$Driver\WriteResultオブジェクトをカプセル化するオブジェクト。

エラーと例外

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

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

書込み (write)操作に関連するエラーについては、 MongoDB $Driver\Exception\BulkWriteException を参照してください。ユーザーは getWriteResult() によって返される値を調べて、エラーの内容を判断する必要があります。

拡張レベルのその他のエラー（例: 接続エラー）の場合は、 MongoDB\Driver\Exception\RuntimeException 。

動作

クエリ条件を評価する際、 MongoDB はBSON types の独自の比較ルールに従ってタイプと値を比較します。これは PHP の比較および型調整ルールとは異なります。特別なBSON type を照合する場合、クエリ条件は拡張機能内でそれぞれのBSONクラスを使用する必要があります（たとえば、 ObjectId と一致させるためにMongoDB\ BSON\ObjectId を使用するなど）。

MongoDB\Driver\Exception\BulkWriteException がスローされた場合、ユーザーは getWriteResult() を呼び出し、返されたMongoDB\Driver\WriteResultオブジェクトを調べて、エラーの内容を判断する必要があります。

例えば、書込み (write) 操作はプライマリサーバーに正常に適用されたが、書込み保証 (write concern) を満たすには失敗した場合（例: レプリケーションに時間がかかりすぎました）。あるいは、書込み (write) 操作が完全に失敗した可能性があります（例: 一意なキー違反）。

例

次の例では、 activeフィールドをtrueに設定して、 "Queens"のboroughを持つすべてのドキュメントを更新します。

<?php
$collection = (new MongoDB\Client)->test->restaurants;
$updateResult = $collection->updateMany(
    [ 'borough' => 'Queens' ],
    [ '$set' => [ 'active' => true ]]
);
printf("Matched %d document(s)\n", $updateResult->getMatchedCount());
printf("Modified %d document(s)\n", $updateResult->getModifiedCount());

出力は次のようになります。

Matched 5656 document(s)
Modified 5656 document(s)

その他の参照

戻る

replaceOne()

updateOne()