/ /

ドキュメントの挿入

Overview

このガイドでは、 Kotlin Sync ドライバーを使用して挿入操作を実行し、MongoDB コレクションにドキュメントを追加する方法を学習できます。

挿入操作は、1 つ以上のドキュメントを MongoDB コレクションに挿入します。挿入操作は、メソッドとメソッドを使用して実行できます。insertOne()insertMany()

サンプルデータ

このガイドの例では、Atlas サンプルデータセットの sample_restaurants.restaurants コレクションを使用します。無料の MongoDB 配置を作成し、サンプルデータセットを読み込む方法については、MongoDB のスタートガイドを参照してください。

このコレクション内のドキュメントは、次の 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()`	`true` に設定すると、ドライバーはドキュメントレベルの検証を無視できます。デフォルトは `false` です。
`comment()`	操作に添付するコメントを設定します。詳細については、MongoDB Server マニュアルの「insert コマンドフィールド」のガイドを参照してください。

InsertManyOptionsインスタンスを構成することで、 insertMany()メソッドで上記の設定を設定できます。また、 ordered()メソッド setter メソッドを使用して、ドライバーが MongoDB にドキュメントを挿入する順序を指定することもできます。

方式	説明
`ordered()`	`true` に設定されている場合、ドライバーは指定された順序でドキュメントをサーバーに送信します。エラーが発生した場合、ドライバーは残りの挿入操作をすべてキャンセルします。デフォルトは `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 ドキュメントを参照してください。

戻る

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

ドキュメントの検索