MongoDB 扩展 JSON (v2)
重要
消歧
以下页面讨论 MongoDB 扩展 JSON v2。有关旧版 MongoDB 扩展 JSON v1 的讨论,请参阅 MongoDB 扩展 JSON (v1)。
有关 mongosh
中支持的数据类型,请参阅 mongosh 数据类型。
JSON 只能直接表示 BSON 所支持类型的一个子集。为了保留类型信息,MongoDB 在 JSON 格式中添加了以下扩展。
- 规范模式
- 一种凸显类型保存的字符串格式,但牺牲了可读性和互操作性。 也就是说,从规范模式到 BSON 的转换 通常会保留类型信息,某些特定情况下除外。
- 宽松模式
- 一种字符串格式,强调可读性和互操作性,但牺牲了类型保护。也就是说,从宽松格式转换为 BSON 可能会丢失类型信息。
两种格式均符合 JSON RFC,可以被各种 MongoDB 驱动程序和工具解析。
MongoDB 扩展 JSON v2 用法
驱动程序
以下驱动程序使用扩展 JSON v2.0
|
|
|
对于使用旧版 MongoDB 扩展 JSON v1 的 C# 和 Ruby,请参阅 MongoDB 扩展 JSON (v1)。
扩展 JSON 方法
MongoDB 为扩展 JSON 提供了以下方法:
方法 | 说明 | |
serialize | 序列化 BSON 对象并以扩展 JSON 格式返回数据。
| |
deserialize | 将序列化文档转换为字段和值对。这些值具有 BSON 类型。
| |
stringify | 将反序列化对象中的元素和类型对转换为字符串。
| |
parse | 将字符串转换为元素和类型对。
|
有关用法示例,请参阅下文扩展 JSON 对象转换。
有关更多详细信息,请参阅以下程序的文档:
MongoDB 数据库工具
从 4.2 版本开始:
二进制文件 | 更改 |
---|---|
使用扩展 JSON v2.0(规范模式)格式。 | |
使用扩展 JSON v 2.0 (规范模式)元数据的格式。 需要支持扩展 JSON v 2.0的 一般情况下,使用相应版本的 | |
Creates output data in Extended JSON v2.0 (Relaxed mode) by
default. Creates output data in Extended JSON v2.0 (Canonical mode) if
used with --jsonFormat . | |
Expects import data to be in Extended JSON v2.0 (either
Relaxed or Canonical mode) by default. Can recognize data that is in Extended JSON v1.0 format if the option
--legacy is specified.一般来说, |
BSON 数据类型和相关表示形式
下文介绍某些常见 BSON 数据类型,以及在规范和宽松模式下的相关表示形式。
完整列表在此。
规范 | 宽松 | ||
---|---|---|---|
|
|
其中数组元素如下:
<elements>
数组元素使用扩展 JSON。
要指定空数组,请省略内容
[ ]
。
规范 | 宽松 | |||||||
---|---|---|---|---|---|---|---|---|
|
|
其中的值如下所示:
"<payload>"
Base64 编码(填充为 "=")有效负载字符串。
"<t>"
对应于 BSON 二进制子类型的一个字符或两个字符的十六进制字符串。有关可用的子类型,请参阅扩展版 bson 文档 http://bsonspec.org/spec.html。
对于 1970 年至 9999 年之间的日期(含):
规范 | 宽松 | ||
---|---|---|---|
|
|
对于 1970 年之前或 9999 年之后的日期:
规范 | 宽松 | ||
---|---|---|---|
|
|
其中的值如下所示:
"<millis>"
作为字符串的 64 位有符号整数。该值表示相对于纪元的毫秒数。
"<ISO-8601 Date/Time Format>"
以 ISO-8601 互联网日期/时间格式为字符串的日期。
日期/时间的最大时间精度为毫秒:
如果小数部分为非零,则小数形式的秒数实际有 3 个小数位。
否则,如果秒的小数部分为零,则应省略。
规范 | 宽松 | ||
---|---|---|---|
|
|
其中的值如下所示:
"<number>"
高精度小数作为字符串。
规范 | 宽松 | ||
---|---|---|---|
|
|
其中文档内容如下所示:
<content>
使用扩展 JSON 的“名称:值”对。
要指定空文档,请省略内容
{ }
。
对于有限数:
规范 | 宽松 | ||
---|---|---|---|
|
|
对于无限数或 NAN:
规范 | 宽松 | ||
---|---|---|---|
|
|
其中的值如下所示:
"<decimal string>"
作为字符串的 64 位带符号浮点数。
<non-integer number>
非整数。整数数字将解析为整数而不是 double。
规范 | 宽松 | ||
---|---|---|---|
|
|
其中的值如下所示:
"<number>"
作为字符串的 64 位有符号整数。
<integer>
64 位有符号整数。
规范 | 宽松 | ||
---|---|---|---|
|
|
其中的值如下所示:
"<number>"
作为字符串的 32 位有符号整数。
<integer>
一个 32 位有符号整数。
规范 | 宽松 | ||
---|---|---|---|
|
|
MaxKey BSON 数据类型的比较高于所有其他类型。请参阅比较/排序顺序以了解有关 BSON 类型的比较顺序的更多信息。
规范 | 宽松 | ||
---|---|---|---|
|
|
MinKey BSON 数据类型的比较值低于所有其他类型。数据类型有关 BSON 类型的比较顺序的更多信息,请参阅比较/排序顺序。
规范 | 宽松 | ||
---|---|---|---|
|
|
其中的值如下所示:
"<ObjectId bytes>"
一个 24 个字符大端十六进制字符串,表示对象标识符字节。
规范 | 宽松 | |||||||
---|---|---|---|---|---|---|---|---|
|
|
其中的值如下所示:
"<regexPattern>"
与正则表达式模式相对应的字符串。字符串可以包含有效的 JSON 字符和非转义双引号 (
"
) 字符,但不能包含未转义的正斜杠 (/
) 字符。
"<options>"
指定 BSON 正则表达式选项的字符串。必须按字母顺序指定选项。有关受支持选项的信息,请参阅
$options
。
规范 | 宽松 | ||
---|---|---|---|
|
|
其中的值如下所示:
<t>
自纪元以来的秒数的正整数。
<i>
增量的正整数。
示例
以下示例说明了扩展 JSON 的用法。
类型表示形式
字段名称示例 | 规范格式 | 宽松格式 |
---|---|---|
"_id:" | {"$oid":"5d505646cf6d4fe581014ab2"} | {"$oid":"5d505646cf6d4fe581014ab2"} |
"arrayField": | ["hello",{"$numberInt":"10"}] | ["hello",10] |
“dateField”: | {"$date":{"$numberLong":"1565546054692"}} | {"$date":"2019-08-11T17:54:14.692Z"} |
"dateBefore1970": | {"$date":{"$numberLong":"-1577923200000"}} | {"$date":{"$numberLong":"-1577923200000"}} |
"decimal128Field": | {"$numberDecimal":"10.99"} | {"$numberDecimal":"10.99"} |
"documentField": | {"a":"hello"} | {"a":"hello"} |
"doubleField": | {"$numberDouble":"10.5"} | 10.5 |
"infiniteNumber" | {"$numberDouble":"Infinity"} | {"$numberDouble":"Infinity"} |
"int32field": | {"$numberInt":"10"} | 10 |
"int64Field": | {"$numberLong":"50"} | 50 |
"minKeyField": | {"$minKey":1} | {"$minKey":1} |
"maxKeyField": | {"$maxKey":1} | {"$maxKey":1} |
"regexField": | {"$regularExpression":{"pattern":"^H","options":"i"}} | {"$regularExpression":{"pattern":"^H","options":"i"}} |
“timestampField”: | {"$timestamp":{"t":1565545664,"i":1}} | {"$timestamp":{"t":1565545664,"i":1}} |
"uuid": | {"$uuid":"3b241101-e2bb-4255-8caf-4136c566a962"} | {"$uuid":"3b241101-e2bb-4255-8caf-4136c566a962"} |
扩展 JSON 对象转换
以下简短示例创建一个文档对象,然后使用扩展 JSON 对象转换方法将该对象转换为不同的形式。
设置
在 conversions
集合中创建文档:
db.conversions.insertOne( { insertDate: new Date() } )
mongosh
返回一个文档对象:
{ acknowledged: true, insertedId: ObjectId("61fbaf25671c45f3f5f4074a") }
EJSON.serialize
对存储在 MongoDB 文档对象中的数据进行序列化:
serialized = EJSON.serialize( db.conversions.findOne() )
mongosh
解析了 JavaScript 对象,并使用 "$"
前缀类型来返回值:
{ _id: { '$oid': '61fbaf25671c45f3f5f4074a' }, insertDate: { '$date': '2022-02-03T10:32:05.230Z' } }
EJSON.deserialize
对已序列化的对象进行反序列化:
EJSON.deserialize( serialized )
mongosh
解析 JavaScript 对象,并使用默认 mongosh
类型形式返回值:
{ _id: new ObjectId( "61fbaf25671c45f3f5f4074a" ), insertDate: ISODate( "2022-02-03T10:32:05.230Z" ) }
EJSON.stringify
将对象转换为字符串:
stringified = EJSON.stringify( db.conversions.findOne() )
mongosh
将转换后的对象的元素作为字符串输出:
{ "_id": {"$oid":"61fbaf25671c45f3f5f4074a"}, "insertDate":{"$date":"2022-02-03T10:32:05.230Z"} }
EJSON.parse
解析字符串以创建对象:
EJSON.parse( stringified )
mongosh
将转换后的字符串作为文档返回:
{ _id: new ObjectId("61fbaf25671c45f3f5f4074a"), insertDate: ISODate("2022-02-03T10:32:05.230Z") }