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

MongoDB\Collection::replaceOne()

項目一覧

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

定義

MongoDB\Collection::replaceOne()

フィルター条件に一致するドキュメントを最大で 1 つ置き換えます。 複数のドキュメントがフィルタ条件に一致する場合、 は最初に一致するドキュメントのみが置換されます。

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

パラメーター

$filter : array|object
置き換えるドキュメントを指定するフィルター条件。
$replacement : array|object
置換ドキュメントです。
$options : 配列

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

名前
タイプ
説明
bypassDocumentValidation
ブール値
trueの場合、書込み操作によってドキュメント レベルの検証を回避できます。 デフォルトはfalseです。
コーデック
MongoDB\Codec\DocumentCodec

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

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

バージョン 1.17 の新機能。

collation
array|object

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

照合が指定されていないが、コレクションにデフォルトの照合がある場合、操作はコレクションに指定された照合を使用します。 コレクションにも操作にも照合が指定されていない場合、MongoDB では以前のバージョンで使用されていた単純なバイナリ比較によって string が比較されます。

comment
混合

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

このオプションは MongoDB 4.4 以降で使用可能であり、古いサーバー バージョンで指定すると実行時に例外が発生します。

バージョン 1.13 の新機能。

hint
string|array|object

使用するインデックス。 インデックス名を string またはインデックス キー パターンをドキュメントとして指定します。 指定すると、クエリ システムはヒント指定したインデックスを使用するプランのみを考慮します。

このオプションは MongoDB 4.2 以降で使用可能であり、古いサーバー バージョンで指定すると実行時に例外が発生します。

バージョン 1.6 の新機能.

let
array|object

パラメーター名と値のマップ。 値は、ドキュメント フィールドを参照しない定数または閉じた式である必要があります。 その後、パラメーターには 集計式コンテキスト で変数としてアクセスできます（例: $$var ）。

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

バージョン 1.13 の新機能。

セッション

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

バージョン 1.3 で追加。

upsert
ブール値
trueに設定すると、クエリ条件に一致するドキュメントがない場合に新しいドキュメントが作成されます。 デフォルト値はfalseで、一致するものが見つからない場合は新しいドキュメントを挿入しません。
writeConcern

操作に使用する書込み保証 ( write concern )。 コレクションの書込み保証 (write concern) のデフォルトです。

トランザクションの一部である個々の操作に対して書込み保証 (write concern) を指定することはできません。 代わりに 、トランザクションを開始する ときにwriteConcern オプションを設定します。

Return Values

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

エラーと例外

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

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

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

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

動作

クエリ条件を評価する際、MongoDB は BSON types の独自の比較ルール に従って型と値を比較します。これは PHP の 比較と は異なります と 型の調整 ルール。特殊な BSON 型と一致する場合、クエリ条件はそれぞれの BSON クラス を使用する必要があります 拡張機能（例:MongoDB\BSON \ObjectId ObjectIdを使用 ）

MongoDB\Driver\Exception\BulkWriteException の場合 がスローされる場合は、 getWriteResult() を呼び出す必要があります。 返された MongoDB\Driver\WriteResult を検査します エラーの内容を決定するための オブジェクト。

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

例

次の例では、restaurant_id "40356068"データベースのrestaurants コレクション内にあるドキュメントを のtest に置き換えます。

<?php
$collection = (new MongoDB\Client)->test->restaurants;
$updateResult = $collection->replaceOne(
    [ 'restaurant_id' => '40356068' ],
    [
        'name' => 'New Restaurant',
        'restaurant_id' => '99988877',
        'borough' => 'Queens',
        'cuisine' => 'Cafe',
        'grades' => [],
    ]
);
printf("Matched %d document(s)\n", $updateResult->getMatchedCount());
printf("Modified %d document(s)\n", $updateResult->getModifiedCount());

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

Matched 1 document(s)
Modified 1 document(s)

その他の参照

戻る

rename()

次へ

updateMany()