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形式について説明したものです。
名前 | 説明 |
|---|---|
拡張または標準 | A string format that avoids loss of BSON type information during data conversions. This format prioritizes type preservation at the loss of human-readability and
interoperability with older formats. To learn more about this format, see JsonMode.EXTENDED
in the API documentation. |
緩和 | A string format that describes BSON documents with some type information loss. This format prioritizes human-readability and interoperability at the loss of
certain type information. The Kotlin Sync driver uses Relaxed mode by default.
To learn more about this format, see JsonMode.RELAXED
in the API documentation. |
Shell | A string format that matches the syntax used in the MongoDB shell. This format prioritizes compatibility with the MongoDB shell, which often uses
JavaScript functions to represent types. To learn more about this format, see JsonMode.SHELL
in the API documentation. |
注意
Kotlin Syncドライバーは、$uuid 拡張JSON型を string からバイナリ サブタイプ 4 の BsonBinaryオブジェクトに解析します。$uuidフィールド解析の詳細については、拡張JSON仕様の$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 ドキュメントを参照してください。