ドキュメントの置換
Overview
このガイドでは、 Kotlin Sync ドライバー を使用して MongoDB コレクション内のドキュメントに対して置換操作を実行する方法を学習します。 置換操作を実行すると、指定されたドキュメントから _idフィールドを除くすべてのフィールドと値が削除され、指定した新しいフィールドと値が追加されます。 この操作は、1 つ以上のドキュメントの指定されたフィールドのみを変更する更新操作とは異なります。
更新操作について詳しくは、 ドキュメントの更新のガイドを参照してください。
サンプル データ
このガイドの例では、 Atlas サンプル データセットのsample_restaurants.restaurantsコレクションを使用します。 MongoDB Atlas クラスターを無料で作成して、サンプル データセットをロードする方法については、 「 Atlas を使い始める 」ガイドを参照してください。
このコレクション内のドキュメントは、次の Kotlin データ クラスによってモデル化されます。
data class Restaurant( val name: String, val borough: String, val cuisine: String, val owner: String?, )
置換操作
MongoDB では、 replaceOne()メソッドを使用して置換操作を実行できます。 このメソッドは、クエリフィルターに一致する最初のドキュメントから_idフィールドを除くすべてのフィールドを削除します。 次に、指定したフィールドと値を空のドキュメントに追加します。
必要なパラメーター
次のパラメータをreplaceOne()メソッドに渡す必要があります。
クエリフィルター。アップデートするドキュメントに一致する。 クエリフィルターの詳細については、「クエリの指定」ガイドを参照してください。
置換ドキュメント。既存のフィールドと値を置き換えるフィールドと値を指定します。
1 つのドキュメントの置換
次の例では、 replaceOne()メソッドを使用して、 nameフィールドの値が"Primola Restaurant"であるドキュメントのフィールドと値を置き換えます。
val filter = Filters.eq(Restaurant::name.name, "Primola Restaurant") val replacement = Restaurant( "Frutti Di Mare", "Queens", "Seafood", owner = "Sal Thomas" ) val result = collection.replaceOne(filter, replacement)
重要
_idフィールドの値は不変です。 置き換えドキュメントで_idフィールドの値を指定する場合、既存のドキュメントの_id値と同じである必要があります。そうでない場合、ドライバーはWriteErrorを発生させます。
置換操作をカスタマイズする
replaceOne()メソッドはオプションで、置換操作を構成するための オプションを設定する パラメーターを受け入れます。 オプションを指定しない場合、ドライバーはデフォルト設定で置換操作を実行します。
次の表では、 ReplaceOptionsインスタンスを構成するために使用できる setter メソッドについて説明します。
プロパティ | 説明 |
|---|---|
upsert() | Specifies whether the replace operation performs an upsert operation if no
documents match the query filter. For more information, see upsert
behavior
in the MongoDB Server manual. Defaults to false |
bypassDocumentValidation() | Specifies whether the update operation bypasses document validation. This lets you
update 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() | Sets the index to use when matching documents.
For more information, see the hint statement
in the MongoDB Server manual. |
let() | Provides a map of parameter names and values to set top-level
variables for the operation. Values must be constant or closed
expressions that don't reference document fields. |
comment() | Sets a comment to attach to the operation. |
次のコードでは、 upsertオプションをtrueに設定します。これは、クエリフィルターが既存のドキュメントと一致しない場合に、置換ドキュメントで指定されたフィールドと値を持つ新しいドキュメントを挿入するようにドライバーに指示します。
val opts = ReplaceOptions().upsert(true) val result = collection.replaceOne(filter, replacement, opts)
戻り値
replaceOne()メソッドはUpdateResultオブジェクトを返します。 UpdateResultインスタンスからの情報にアクセスするには、次のメソッドを使用できます。
プロパティ | 説明 |
|---|---|
getMatchedCount() | Returns the number of documents that matched the query filter, regardless of
how many updates were performed. |
getModifiedCount() | Returns the number of documents modified by the update operation. If an updated
document is identical to the original, it is not included in this
count. |
wasAcknowledged() | Returns true if the server acknowledged the result. |
getUpsertedId() | Returns the _id value of the document that was upserted
in the database, if the driver performed an upsert. |
詳細情報
ドキュメントを置き換える方法を示す実行可能なコード例については、「 MongoDB へのデータの書込み 」を参照してください。
API ドキュメント
このガイドで説明したメソッドや型の詳細については、次の API ドキュメントを参照してください。