/ /

ドキュメントの挿入

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ドライバーを使用してドキュメントを挿入する方法を示す実行可能なコード例については、「ドキュメントの挿入」を参照してください。

API ドキュメント

このガイドで説明したメソッドや型の詳細については、次の API ドキュメントを参照してください。

戻る

データベースとコレクション

ドキュメントの検索