ドキュメントの置換

Overview

このガイドでは、PyMongo を使用して MongoDB コレクション内のドキュメントに対して置換操作を実行する方法を学習します。置換操作は更新操作とは異なります。アップデート操作により、ターゲットドキュメント内の指定されたフィールドのみが変更されます。置換操作により、ターゲットドキュメント内のすべてのフィールドが削除され、新しいフィールドに置き換えられます。

アップデート操作の詳細については、ドキュメントのアップデートガイドを参照してください。

サンプルデータ

このガイドの例では、 Atlas サンプルデータセットのsample_restaurants.restaurantsコレクションを使用します。 MongoDB Atlas クラスターを無料で作成して、サンプルデータセットをロードする方法については、「 PyMongo を使い始める」チュートリアルを参照してください。

置換操作

MongoDB では、 replace_one()メソッドを使用して置換操作を実行できます。このメソッドは、検索条件に一致する最初のドキュメントから_idフィールドを除くすべてのフィールドを削除します。その後、指定したフィールドと値がドキュメントに挿入されます。

必要なパラメーター

replace_one() メソッドには次のパラメーターが必要です。

A query filter document, which determines which documents to replace. For more information about query filters, see the Query Filter Documents section in the MongoDB Server manual.
置換ドキュメント。新しいドキュメントに挿入するフィールドと値を指定します。

replaceOne

次の例では、 replace_one()メソッドを使用して、ドキュメントのフィールドと値をnameフィールド値"Pizza Town"に置き換えます。

restaurants = database["restaurants"]
query_filter = {"name" : "Pizza Town"}
replace_document = { "name" : "Mongo's Pizza",
                     "cuisine" : "Pizza",
                     "address" : {
                         "street" : "123 Pizza St",
                         "zipCode" : "10003"
                     },
                     "borough" : "Manhattan"
                   }
result = restaurants.replace_one(query_filter, replace_document)

重要

_idフィールドの値は不変です。置き換えドキュメントで_idフィールドに値が指定される場合は、既存のドキュメントの_id値と一致する必要があります。

置換操作をカスタマイズする

オプションで、 replace_one()メソッドは追加のパラメーターを受け入れます。これらのパラメーターは、置換操作を構成するために使用できるオプションを表します。追加のオプションを指定しない場合、ドライバーは置換操作をカスタマイズしません。

プロパティ	説明
`upsert`	Specifies whether the replace operation performs an upsert operation if no documents match the query filter. For more information, see the upsert statement in the MongoDB Server manual. Defaults to `False`
`bypass_document_validation`	Specifies whether the replace operation bypasses document validation. This lets you replace documents that don't meet the schema validation requirements, if any exist. For more information about schema validation, see Schema Validation in the MongoDB Server manual. Defaults to `False`.
`collation`	Specifies the kind of language collation to use when sorting results. For more information, see Collation in the MongoDB Server manual.
`hint`	Gets or sets the index to scan for documents. For more information, see the hint statement in the MongoDB Server manual.
`session`	`ClientSession`のインスタンス。
`let`	A Map of parameter names and values. Values must be constant or closed expressions that don't reference document fields. For more information, see the let statement in the MongoDB Server manual.
`comment`	A comment to attach to the operation. For more information, see the insert command fields guide in the MongoDB Server manual.

次のコードでは、 replace_one()メソッドを使用して、 nameフィールドの値が"Food Town"である最初のドキュメントを検索し、このドキュメントを"Food World"という名前の新しいドキュメントに置き換えます。 upsertオプションがTrueに設定されているため、クエリフィルターが既存のドキュメントと一致しない場合、ドライバーは新しいドキュメントを挿入します。

restaurants = database["restaurants"]
query_filter = {"name" : "Food Town"}
replace_document = { "name" : "Food World",
                     "cuisine" : "Mixed",
                     "address" : {
                         "street" : "123 Food St",
                         "zipCode" : "10003"
                     },
                     "borough" : "Manhattan"
                   }
result = restaurants.replace_one(query_filter, replace_document, upsert = True)

戻り値

replace_one()メソッドはUpdateResultオブジェクトを返します。 UpdateResult型には次のプロパティが含まれています。

プロパティ	説明
`matched_count`	アップデートされた数に関係なく、クエリフィルターに一致したドキュメントの数。
`modified_count`	更新操作によって変更されたドキュメントの数。更新されたドキュメントが元と同一の場合、このカウントには含まれません。
`raw_result`	サーバーによって返された未加工の結果ドキュメント。
`upserted_id`	ドライバーがアップサートを実行した場合、データベースでアップサートされたドキュメントのID。それ以外の場合は`None`です。