ドキュメントの挿入
Overview
このガイドでは、 Kotlin Sync ドライバーを使用して挿入操作を実行し、MongoDB コレクションにドキュメントを追加する方法を学習できます。
挿入操作は、1 つ以上のドキュメントを MongoDB コレクションに挿入します。 挿入操作は、 insertOne()とinsertMany()メソッドを使用して実行できます。
サンプル データ
このガイドの例では、 Atlas サンプル データセットのsample_restaurants.restaurantsコレクションを使用します。 MongoDB Atlas クラスターを無料で作成して、サンプル データセットをロードする方法については、 「 Atlas を使い始める 」ガイドを参照してください。
このコレクション内のドキュメントは、次の Kotlin データ クラスによってモデル化されます。
data class Restaurant(val name: String, val borough: String)
_id フィールド
MongoDB コレクションでは、各ドキュメントに一意の値を持つ_idフィールドが含まれている必要があります。
MongoDB では、このフィールドは次の 2 つの方法で管理できます。
このフィールドは各ドキュメントに自分で設定することができ、各
_idフィールド値が一意であることを確認します。ドライバーを使用して、各ドキュメント
_idに対して一意のObjectId値を自動的に生成できます。 ドキュメントの_id値を手動で設定しない場合、ドライバーは フィールドにObjectIdを入力します。
一意性を保証できない限り、ドライバーに_id値を自動的に生成させることをお勧めします。
注意
重複した_id エラー
コレクションに重複する_id値を設定すると、一意のインデックス制約に違反するため、ドライバーはinsertOne()メソッドからWriteErrorを、またはinsertMany()メソッドからBulkWriteErrorを返します。
_idフィールドの詳細については、 マニュアルの 「 一意なインデックス 」MongoDB Server のガイドを参照してください。
ドキュメント構造とルールの詳細については、MongoDB Server マニュアルのドキュメントガイド を参照してください。
1つのドキュメントの挿入
MongoDB コレクションに単一のドキュメントを追加するには、 insertOne()メソッドを呼び出して、追加するドキュメントを渡します。
次の例では、 restaurantsコレクションにドキュメントを挿入します。
val doc = Restaurant("Sea Shell Bar", "Queens") val result = collection.insertOne(doc)
複数のドキュメントの挿入
MongoDB コレクションに複数のドキュメントを追加するには、 insertMany()メソッドを使用して、追加するドキュメントのリストを渡します。
次の例では、ドキュメントのリストをrestaurantsコレクションに挿入します。
val docs = listOf( Restaurant("Full Moon Grill", "Queens"), Restaurant("King's Cup", "Manhattan"), ) val result = collection.insertMany(docs)
挿入動作の変更
insertOne()メソッドはオプションで、挿入操作を構成するためのオプションを設定するInsertOneOptionsパラメーターを受け入れます。 オプションを指定しない場合、ドライバーはデフォルト設定で挿入操作を実行します。 最後のパラメータとしてオプションをinsertOne()メソッドに渡します。
次の表では、 InsertOneOptionsインスタンスを構成するために使用できる setter メソッドについて説明します。
方式 | 説明 |
|---|---|
bypassDocumentValidation() | If set to true, allows the driver to ignore
document-level validation.Defaults to false. |
comment() | Sets a comment to attach to the operation. For more information, see the insert command
fields guide in the
MongoDB Server manual for more information. |
InsertManyOptionsインスタンスを構成することで、 insertMany()メソッドで上記の設定を設定できます。 また、 ordered()メソッド setter メソッドを使用して、ドライバーが MongoDB にドキュメントを挿入する順序を指定することもできます。
方式 | 説明 |
|---|---|
ordered() | If set to true, the driver sends documents to the
server in the order provided. If an error occurs, the driver
cancels all remaining insert operations.Defaults to true. |
最後のパラメータとしてオプションをinsertMany()メソッドに渡します。
挿入例の変更
次のコードでは、 bypassDocumentValidation()メソッドを使用して オプションを設定し、ドキュメント検証ルールを無視します。 次に、この例ではinsertMany()メソッドを使用してrestaurantsコレクションに新しいドキュメントを追加します。
val opts = InsertManyOptions().bypassDocumentValidation(true) val docs = listOf( Restaurant("Full Moon Grill", "Queens"), Restaurant("King's Cup", "Manhattan"), ) val result = collection.insertMany(docs, opts)
戻り値
insertOne()メソッドはInsertOneResultインスタンスを返し、 insertMany()メソッドはInsertManyResultインスタンスを返します。
次のメソッドを使用して、 InsertOneResultインスタンスから情報を取得できます。
方式 | 説明 |
|---|---|
getInsertedId() | 挿入されたドキュメントの _id値を示します。 |
wasAcknowledged() | サーバーが結果を確認した場合は trueを返します。 |
次のメソッドを使用して、 InsertOneResultインスタンスから情報を取得できます。
方式 | 説明 |
|---|---|
getInsertedIds() | 挿入されたドキュメントの _id値を示します。 |
wasAcknowledged() | サーバーが結果を確認した場合は trueを返します。 |
注意
wasAcknowledged()メソッドがfalseを返す場合、 _id値にアクセスしようとするとInvalidOperation例外が発生します。 サーバーが書込み (write) 操作を確認しない場合、ドライバーはこれらの値を決定できません。
詳細情報
Kotlin Sync ドライバーを使用してドキュメントを挿入する方法を示す実行可能なコード例については、「 MongoDBへのデータの書込み 」を参照してください。
API ドキュメント
このガイドで説明したメソッドや型の詳細については、次の API ドキュメントを参照してください。