Docs Menu
Docs Home
/ /

ドキュメントの置換

このガイドでは、 Kotlinドライバー を使用してMongoDBコレクション内のドキュメントを置き換える方法を学習します。置換操作では、クエリフィルターを使用してコレクション内のドキュメントを照合し、そのドキュメントを新しいドキュメントに置き換えます。

replaceOne() replaceOne() メソッドは、一致するドキュメント内のすべての既存のフィールドと値( _idフィールドを除く)を削除し、置換ドキュメントからフィールドと値を挿入します。

次のように、 MongoCollectionインスタンスでreplaceOne()メソッドを呼び出すことができます。

collection.replaceOne(<query>, <replacementDocument>)

複数のドキュメントが replaceOne() メソッドで指定されたクエリフィルターに一致する場合、その操作は最初の結果を置き換えます。次のコードに示すように、ドライバーが置換操作を実行する前に、一致したドキュメントに順序を適用するために、ReplaceOptionsインスタンスで並べ替えを指定できます。

val opts = ReplaceOptions().sort(Sorts.ascending(PaintOrder::color.name))

置換操作でクエリフィルターに一致するドキュメントがない場合、replaceOne() はコレクション内のドキュメントに変更を加えません。一致するドキュメントがない場合に、ドキュメントを置き換える代わりに新しいドキュメントを挿入する方法については、Upsert ガイドを参照してください。

重要

replaceOne() メソッドは、コレクションのユニークインデックス制約 に違反するドキュメントを変更することはできません。ユニークインデックスの詳細については、MongoDB Serverマニュアルを参照してください。

replaceOne() メソッドは次のパラメーターを受け入れます:

Parameter
説明

filter

置き換えドキュメントを指定するクエリフィルター。クエリフィルターの詳細については、MongoDB Serverマニュアルを参照してください。

データ型: BSON

replacement

置換ドキュメント。新しいドキュメントに挿入するフィールドと値を指定します。コレクション内のドキュメントがKotlinクラスにマップされている場合、置換ドキュメントはこのクラスのインスタンスになることができます。

データ型: document: T

options

任意。置換操作の構成を指定する ReplaceOptionsクラスのインスタンス。 デフォルト値は null です。

データ型: ReplaceOptions

replaceOne() メソッドはオプションで、置換操作を構成するために使用できるオプションを表す ReplaceOptionsオブジェクトをパラメーターとして受け入れます。

ReplaceOptionsクラスには、次のプロパティが含まれています。

プロパティ
説明

bypassDocumentValidation

置換操作がドキュメントの検証をバイパスするかどうかを指定します。 これにより、スキーマ検証要件を満たさないドキュメントを存在する場合に置き換えることができます。 スキーマ検証の詳細については、 MongoDB Serverマニュアルを参照してください。

データ型: ブール値

collation

結果をソートするときに使用する言語照合の種類を指定します。

データ型: 照合

comment

操作のユーザー指定のコメントを取得または設定します。 詳細については、 MongoDB Server のマニュアルを参照してください。

データ型: String または BsonValue

hint

ドキュメントをスキャンするために使用するインデックスを取得または設定します。 詳細については、 MongoDB Server のマニュアルを参照してください。

データ型: Bson

hintString

ドキュメントをスキャンするために使用するインデックスを取得または設定します。 詳細については、 MongoDB Server のマニュアルを参照してください。

データ型: 文字列

upsert

クエリフィルターに一致するドキュメントがない場合に、置換操作でアップサート操作を実行するかどうかを指定します。 詳細については、 MongoDB Server のマニュアルを参照してください。

データ型: ブール値

sort

クエリで複数のドキュメントが選択された場合に、その操作で置き換えるドキュメントを決定します。これは、置き換え操作が指定されたソート順の最初のドキュメントを置き換えるためです。

データ型: Bson

let

letドキュメントを取得または設定して、操作の最上位変数を追加します。詳細については、 MongoDB Server のマニュアルを参照してください。

データ型: Bson

正常に実行されると、replaceOne() メソッドは UpdateResultインスタンスを返します。UpdateResultクラスには、次のプロパティが含まれています。

プロパティ
説明

wasAcknowledged

置き換え操作が MongoDB によって確認されたかどうかを示します。

データ型: boolean

getMatchedCount

置き換えられたかどうかにかかわらず、クエリフィルターに一致したドキュメントの数。

データ型: long

getModifiedCount

置換操作によって置き換えられたドキュメントの数。

データ型: long

getUpsertedId

ドライバーがアップサートを実行した場合、データベースでアップサートされたドキュメントのID。

データ型: BsonValue

置き換え操作に失敗した場合、ドライバーは例外を発生させます。

例、置換ドキュメントの _idフィールドの値が元のドキュメントの値と異なる場合、メソッドは次の MongoWriteException をスローします。

After applying the update, the (immutable) field '_id' was found to have been altered to _id: ObjectId('...)

置き換えドキュメントにユニークインデックスのルールに違反する変更が含まれている場合、メソッドは次のようなエラーメッセージを含む MongoWriteException をスローします。

E11000 duplicate key error collection: ...

特定の条件で発生する例外の種類の詳細については、このページの下部にリンクしているreplaceOne()の API ドキュメントを参照してください。

塗料店では 5 色の塗料を販売しています。次のコレクション内のドキュメントは、店舗の在庫内の塗料の色を表しています。

{ "_id": 1, "color": "red", "qty": 5 }
{ "_id": 2, "color": "purple", "qty": 8 }
{ "_id": 3, "color": "yellow", "qty": 0 }
{ "_id": 4, "color": "green", "qty": 6 }
{ "_id": 5, "color": "pink", "qty": 20 }

次のKotlinデータクラスは、このデータをモデル化します。

data class PaintOrder(
@BsonId val id: Int,
val color: String,
val qty: Int
)

塗料店では、在庫を更新して、オレンジ色の塗料 20 缶をオレンジ色の塗料 25 缶に置き換える必要があります。

在庫を更新するには、replaceOne() メソッドを呼び出します。

val filter = Filters.eq(PaintOrder::color.name, "pink")
val update = PaintOrder(5, "orange", 25)
val result = collection.replaceOne(filter, update)
println("Matched document count: $result.matchedCount")
println("Modified document count: $result.modifiedCount")
Matched document count: 1
Modified document count: 1

上記の置換操作では、次のドキュメントが作成されます。

{ "_id": 5, "color": "orange", "qty": 25 }

次の例では、replaceOne() メソッドは、Atlas sample_mflix.movies データセットmoviesコレクション内のクエリフィルターの最初の一致を置換ドキュメントに置き換えます。この操作、元のドキュメントから _id を除くすべてのフィールドが削除され、置換ドキュメントからフィールドが挿入されます。次の Movie データクラスは、このコレクション内のドキュメントをKotlinドライバーで使用するようにモデル化します。

data class Movie(
val title: String,
val year: Int,
val genres: List<String>,
val rated: String,
val plot: String,
val runtime: Int,
val imdb: IMDB,
val fullplot: String? = "No full plot",
){
data class IMDB(
val rating: Double
)
}

Tip

ビルダ メソッドとデータ クラスのプロパティ

任意のKotlinドライバー拡張の依存関係をアプリケーションに追加することで、ビルダ クラスのメソッドをデータクラスプロパティで直接使用できます。 詳細と例については、「 データ クラスを使用したビルダの使用 」ガイドを参照してください。

replaceOne()操作が実行される前に、元のドキュメントには映画を説明する複数のフィールドが含まれています。 操作の実行後、結果のドキュメントには、置換ドキュメントによって指定されたフィールド( titlefullplot )と_idフィールドのみが含まれます。

次の例では、次のオブジェクトとメソッドを使用します。

  • replaceOne() メソッドに渡されるクエリフィルターeq フィルターは、タイトルが "Music of the Heart" テキストと完全に一致する映画のみに一致します。

  • 置換ドキュメント 一致するドキュメントを置き換えるドキュメント(存在する場合)を含む。

  • オプションが に設定されている ReplaceOptionsオブジェクト。upserttrueこのオプションは、クエリフィルターがどのドキュメントにも一致しない場合に、メソッドが置換ドキュメントに含まれるデータを挿入することを指定します。

注意

この例では、接続 URI を使用してMongoDBのインスタンスに接続します。MongoDBインスタンスへの接続の詳細については、接続ガイドを参照してください。

import com.mongodb.MongoException
import com.mongodb.client.model.Filters
import com.mongodb.client.model.ReplaceOptions
import com.mongodb.kotlin.client.coroutine.MongoClient
import kotlinx.coroutines.runBlocking
data class Movie(val title: String, val fullplot: String)
fun main() = runBlocking {
// Replace the uri string with your MongoDB deployment's connection string
val uri = "<connection string uri>"
val mongoClient = MongoClient.create(uri)
val database = mongoClient.getDatabase("sample_mflix")
val collection = database.getCollection<Movie>("movies")
try {
val query = Filters.eq("title", "Music of the Heart")
val replaceDocument = Movie( "50 Violins", " A dramatization of the true story of Roberta Guaspari who co-founded the Opus 118 Harlem School of Music")
val options = ReplaceOptions().upsert(true)
val result = collection.replaceOne(query, replaceDocument, options)
println("Modified document count: " + result.modifiedCount)
println("Upserted id: " + result.upsertedId) // only contains a non-null value when an upsert is performed
} catch (e: MongoException) {
System.err.println("Unable to replace due to an error: $e")
}
mongoClient.close()
}

上記の例では、次の出力が返されます。

Modified document count: 1
Upserted id: null

上記の例ではアップサートが発生した場合、コードは次の出力を返します。

Modified document count: 0
Upserted id: BsonObjectId{value=...}

置換されたドキュメントをクエリすると、クエリは次の出力を返します。

Movie(title=50 Violins, fullplot= A dramatization of the true story of Roberta Guaspari
who co-founded the Opus 118 Harlem School of Music)

このページで使用されているメソッドとクラスの詳細については、次のAPIドキュメントを参照してください。

戻る

ドキュメントをアップサートする

項目一覧