AI エージェント向け: ドキュメントインデックスは https://www.mongodb.com/ja-jp/docs/llms.txt で利用できます。すべてのページの markdown バージョンは、いずれかの URL パスに .md を追加することで利用できます。
Make the MongoDB docs better! We value your opinion. Share your feedback for a chance to win $100.
MongoDB Branding Shape
Click here >
Docs Menu
Docs Home
/ /
Data Formats
Docs Home
/ /
Kotlin Sync ドライバー
/
Data Formats
Docs Home
/
クライアント ライブラリ
/
Kotlin
/
Kotlin Sync ドライバー
/
Data Formats

拡張JSONデータとの連携

Overview

このガイドでは、 MongoDBドキュメントを操作するときに拡張JSONデータ形式を使用する方法を学習できます。

JSON は、オブジェクト、配列、数値、string、ブール値、null の値を表す人間が判読可能なデータ形式です。この形式は、 MongoDB がデータを保存するために使用する形式であるBSONデータ型のサブセットのみをサポートします。拡張JSON形式はより多くのBSONタイプをサポートしており、 BSONの各タイプに直接対応するフィールドタイプ情報を表すために "$" のプレフィックスが付いたキーの予約セットを定義します。

JSON、 BSON、 拡張JSONの詳細については、JSONとBSONリソースおよび拡張JSON MongoDB Server のマニュアル エントリを参照してください。

拡張 JSON 形式

MongoDB拡張JSON は、 BSONデータを表す string 形式を提供します。各形式はJSON RFCに準拠し、特定のユースケースを満たしています。

次の表は、各 拡張JSON形式について説明したものです。

名前
説明

拡張または標準

データ変換中にBSON type 情報が喪失しないようにする
string形式で、この形式では、人間が判読できず、古い形式との相互運用性が失われる場合に、型の保存が優先されます。 JsonMode.EXTENDED

緩和

何らかのタイプ情報を含むBSONドキュメントを記述する
string形式。この形式では、特定のタイプ情報を除いて、人間が判読できることと相互運用性を優先します。 JsonMode.RELAXED

Shell

MongoDB シェルで使用される構文に一致する string形式。この形式は、型を表すためにJavaScript関数を多く使用するMongoDB
シェルとの互換性を優先します。 JsonMode.SHALL

$uuid フィールドを解析するための特別なルール

拡張 JSON の例

次の例は、それぞれの拡張 JSON 形式で表される ObjectId、date、long 数値フィールドを含むドキュメントを示しています。 表示する例の形式に対応するタブをクリックします。

{
  "_id": { "$oid": "573a1391f29313caabcd9637" },
  "createdAt": { "$date": { "$numberLong": "1601499609" }},
  "numViews": { "$numberLong": "36520312" }
}
{
  "_id": { "$oid": "573a1391f29313caabcd9637" },
  "createdAt": { "$date": "2020-09-30T18:22:51.648Z" },
  "numViews": 36520312
}
{
  "_id": ObjectId("573a1391f29313caabcd9637"),
  "createdAt": ISODate("2020-09-30T18:22:51.648Z"),
  "numViews": NumberLong("36520312")
}

拡張 JSON の読み取り

このセクションでは、拡張JSON値を次の方法でKotlinオブジェクトに読み込む方法を示します。

ドキュメント クラスの使用

拡張JSON string をKotlinドキュメントオブジェクトに読み込むには、Document クラスまたは BsonDocumentクラスから parse() 静的メソッドを呼び出します。このメソッドは、拡張JSON string を解析し、そのデータを指定されたドキュメントクラスのインスタンスに保存します。

次の例では、parse() メソッドを使用して、拡張JSON string を Documentオブジェクトに読み取ります。

val ejsonStr = """
    {
        "_id": { "$${"oid"}": "507f1f77bcf86cd799439011" },
        "myNumber": { "$${"numberLong"}": "4794261" }
    }
""".trimIndent()
val doc = Document.parse(ejsonStr)
println(doc)
Document{{_id=507f1f77bcf86cd799439011, myNumber=4794261}}

JsonReader クラスの使用

Kotlin Syncドライバーのドキュメントクラスを使用せずに、拡張JSON string をKotlinオブジェクトに読み込むには、 BSONライブラリの JsonReaderクラスを使用します。このクラスには、拡張JSON string のフィールドと値を順番に解析し、 Kotlinオブジェクトとして返すメソッドが含まれています。ドライバーのドキュメントクラスは、 拡張JSONを解析するためにもこのクラスを使用します。

次のコードでは、JsonReaderクラスが提供するメソッドを使用して、拡張JSON string をKotlinオブジェクトに変換します。

val string = """
    {
        "_id": { "$${"oid"}": "507f1f77bcf86cd799439011" },
        "myNumber": { "$${"numberLong"}": "4794261" }
    }
""".trimIndent()
val jsonReader = JsonReader(string)
jsonReader.readStartDocument()
// Reads the "_id" field value
jsonReader.readName("_id")
val id = jsonReader.readObjectId()
// Reads the "myNumber" field value 
jsonReader.readName("myNumber")
val myNumber = jsonReader.readInt64()
jsonReader.readEndDocument()
println("$id is type: ${id::class.qualifiedName}")
println("$myNumber is type: ${myNumber::class.qualifiedName}")
jsonReader.close()
507f1f77bcf86cd799439011 is type: org.bson.types.ObjectId
4794261 is type: kotlin.Long

拡張 JSON の書込み (write)

このセクションでは、次の方法でKotlinオブジェクトから拡張JSON値を書き込む方法を示します。

ドキュメント クラスの使用

Document または BsonDocumentオブジェクトから拡張JSON string を書き込むには、toJson() メソッドを呼び出します。このメソッドに JsonWriterSettingsオブジェクトパラメータを渡して、拡張JSON形式を指定できます。

次の例では、Document データを 緩和モード拡張JSONとして書込みます。

val doc = Document()
    .append("_id", ObjectId("507f1f77bcf86cd799439012"))
    .append("createdAt", Date.from(Instant.ofEpochMilli(1601499609000L)))
    .append("myNumber", 4794261)
val settings = JsonWriterSettings.builder()
    .outputMode(JsonMode.RELAXED)
    .build()
println(doc.toJson(settings))
{"_id": {"$oid": "507f1f77bcf86cd799439012"}, "createdAt": {"$date": "2020-09-30T21:00:09Z"}, "myNumber": 4794261}

JsonWriter クラスの使用

Kotlinオブジェクトに保存されているデータから拡張JSON string を出力するには、 BSONライブラリの JsonWriterクラスを使用できます。JsonWriterオブジェクトを構築するには、 Java Writer のサブクラスを渡して、拡張JSONの出力方法を指定します。オプションで、JsonWriterSettingsインスタンスを渡して、 拡張JSON形式などのオプションを指定できます。デフォルトでは 、JsonWriter は 緩和モード形式を使用します。Kotlin Syncドライバーのドキュメントクラスは、 BSON を拡張JSONに変換する目的でもこのクラスを使用します。

次の例では、JsonWriterオブジェクトを使用して標準モードの拡張JSON string 値を作成し、System.out に出力します。

 val settings = JsonWriterSettings.builder()
    .outputMode(JsonMode.EXTENDED)
    .build()
JsonWriter(BufferedWriter(OutputStreamWriter(System.out)), settings).use { jsonWriter ->
    jsonWriter.writeStartDocument()
    jsonWriter.writeName("_id")
    jsonWriter.writeObjectId(ObjectId("507f1f77bcf86cd799439012"))
    jsonWriter.writeName("myNumber")
    jsonWriter.writeInt64(11223344L)
    jsonWriter.writeEndDocument()
    jsonWriter.flush()
}
{"_id": {"$oid": "507f1f77bcf86cd799439012"}, "myNumber": {"$numberLong": "11223344"}}

カスタム BSON 型変換

拡張JSON出力形式を指定するだけでなく、JsonWriterSettingsオブジェクトに 変換 を追加して出力をさらにカスタマイズできます。これらの変換メソッドは、変換プロセス中にさまざまなデータ型を処理するためのロジックを指定します。

次の例では、 ドキュメント クラスの使用の例と同じドキュメントを変換しています。ただし、この例では、緩和モードの拡張JSON出力を簡素化するために、JsonWriterSettingsオブジェクトで objectIdConverter() と dateTimeConverter() の変換メソッドを定義しています。

val settings = JsonWriterSettings.builder()
    .outputMode(JsonMode.RELAXED)
    .objectIdConverter { value, writer ->
        writer.writeString(value.toHexString())
    }
    .dateTimeConverter { value, writer ->
        val zonedDateTime = Instant.ofEpochMilli(value).atZone(ZoneOffset.UTC)
        writer.writeString(DateTimeFormatter.ISO_DATE_TIME.format(zonedDateTime))
    }
    .build()
val doc = Document()
    .append("_id", ObjectId("507f1f77bcf86cd799439012"))
    .append("createdAt", Date.from(Instant.ofEpochMilli(1601499609000L)))
    .append("myNumber", 4794261)
println(doc.toJson(settings))
{"_id": "507f1f77bcf86cd799439012", "createdAt": "2020-09-30T21:00:09Z", "myNumber": 4794261}

API ドキュメント

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

戻る

時系列

次へ

Indexes

項目一覧