Docs 菜单
Docs 主页
/
MongoDB Manual
/ /

MongoDB 扩展 JSON (v2)

在此页面上

  • MongoDB 扩展 JSON v2 用法
  • BSON 数据类型和相关表示形式
  • 示例

重要

消歧

以下页面讨论 MongoDB 扩展 JSON v2。有关旧版 MongoDB 扩展 JSON v1 的讨论,请参阅 MongoDB 扩展 JSON (v1)

有关 mongosh 中支持的数据类型,请参阅 mongosh 数据类型

JSON 只能直接表示 BSON 所支持类型的一个子集。为了保留类型信息,MongoDB 在 JSON 格式中添加了以下扩展。

  • 规范模式
    一种凸显类型保存的字符串格式,但牺牲了可读性和互操作性。 也就是说,从规范模式到 BSON 的转换 通常会保留类型信息,某些特定情况下除外。
  • 宽松模式
    一种字符串格式,强调可读性和互操作性,但牺牲了类型保护。也就是说,从宽松格式转换为 BSON 可能会丢失类型信息。

两种格式均符合 JSON RFC,可以被各种 MongoDB 驱动程序和工具解析。

以下驱动程序使用扩展 JSON v2.0

  • C

  • C++

  • Go

  • Java

  • Node

  • Perl

  • PHPC

  • Python

  • Scala

对于使用旧版 MongoDB 扩展 JSON v1 的 C# 和 Ruby,请参阅 MongoDB 扩展 JSON (v1)。

MongoDB 为扩展 JSON 提供了以下方法:

方法
说明
serialize

序列化 BSON 对象并以扩展 JSON 格式返回数据。

EJSON.serialize( db.<collection>.findOne() )
deserialize

将序列化文档转换为字段和值对。这些值具有 BSON 类型

EJSON.deserialize( <serialized object> )
stringify

将反序列化对象中的元素和类型对转换为字符串。

EJSON.stringify( <deserialized object> )
parse

将字符串转换为元素和类型对。

EJSON.parse( <string> )

有关用法示例,请参阅下文扩展 JSON 对象转换

有关更多详细信息,请参阅以下程序的文档:

从 4.2 版本开始:

二进制文件
更改
使用扩展 JSON v2.0(规范模式)格式。

使用扩展 JSON v 2.0 (规范模式)元数据的格式。 需要支持扩展 JSON v 2.0的mongorestore版本4.2或更高版本 (规范模式或宽松模式)格式。

通常,使用相应版本的mongodumpmongorestore 。要恢复使用特定版本的mongodump创建的数据文件,请使用相应版本的mongorestore

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.

一般来说, mongoexportmongoimport的版本应该匹配。要导入从mongoexport创建的数据,应使用相应版本的mongoimport

下文介绍某些常见 BSON 数据类型,以及在规范宽松模式下的相关表示形式。

完整列表在此。

Array

规范
宽松
[ <elements> ]
<Same as Canonical>

其中数组元素如下:

  • <elements>

    • 数组元素使用扩展 JSON。

    • 要指定空数组,请省略内容 [ ]

Binary

规范
宽松
{ "$binary":
{
"base64": "<payload>",
"subType": "<t>"
}
}
<Same as Canonical>

其中的值如下所示:

  • "<payload>"

    • Base64 编码(填充为 "=")有效负载字符串。

  • "<t>"

    • 对应于 BSON 二进制子类型的一个字符或两个字符的十六进制字符串。有关可用的子类型,请参阅扩展版 bson 文档 http://bsonspec.org/spec.html

Date

对于 1970 年至 9999 年之间的日期(含)

规范
宽松
{"$date": {"$numberLong": "<millis>"}}
{"$date": "<ISO-8601 Date/Time Format>"}

对于 1970 年之前或 9999 年之后的日期

规范
宽松
{"$date": {"$numberLong": "<millis>"}}
<Same as Canonical>

其中的值如下所示:

  • "<millis>"

    • 作为字符串的 64 位有符号整数。该值表示相对于纪元的毫秒数。

  • "<ISO-8601 Date/Time Format>"

    • ISO-8601 互联网日期/时间格式为字符串的日期。

    • 日期/时间的最大时间精度为毫秒:

      • 如果小数部分为非零,则小数形式的秒数实际有 3 个小数位。

      • 否则,如果秒的小数部分为零,则应省略。

Decimal128

规范
宽松
{ "$numberDecimal": "<number>" }
<Same as Canonical>

其中的值如下所示:

Document

规范
宽松
{ <content> }
<Same as Canonical>

其中文档内容如下所示:

  • <content>

    • 使用扩展 JSON 的“名称:值”对。

    • 要指定空文档,请省略内容 { }

Double

对于有限数

规范
宽松
{"$numberDouble": "<decimal string>" }
<non-integer number>

对于无限数或 NAN

规范
宽松
{"$numberDouble": <"Infinity"|"-Infinity"|"NaN"> }
<Same as Canonical>

其中的值如下所示:

  • "<decimal string>"

    • 作为字符串的 64 位带符号浮点数。

  • <non-integer number>

    • 非整数。整数数字将解析为整数而不是 double。

Int64

规范
宽松
{ "$numberLong": "<number>" }
<integer>

其中的值如下所示:

  • "<number>"

    • 作为字符串的 64 位有符号整数。

  • <integer>

    • 64 位有符号整数。

Int32

规范
宽松
{ "$numberInt": "<number>" }
<integer>

其中的值如下所示:

  • "<number>"

    • 作为字符串的 32 位有符号整数。

  • <integer>

    • 一个 32 位有符号整数。

MaxKey

规范
宽松
{ "$maxKey": 1 }
<Same as Canonical>

MaxKey BSON 数据类型的比较高于所有其他类型。请参阅比较/排序顺序以了解有关 BSON 类型的比较顺序的更多信息。

MinKey

规范
宽松
{ "$minKey": 1 }
<Same as Canonical>

MinKey BSON 数据类型的比较值低于所有其他类型。数据类型有关 BSON 类型的比较顺序的更多信息,请参阅比较/排序顺序

ObjectId

规范
宽松
{ "$oid": "<ObjectId bytes>" }
<Same as Canonical>

其中的值如下所示:

  • "<ObjectId bytes>"

    • 一个 24 个字符大端十六进制字符串,表示对象标识符字节。

Regular Expression

规范
宽松
{ "$regularExpression":
{
"pattern": "<regexPattern>",
"options": "<options>"
}
}
<Same as Canonical>

其中的值如下所示:

  • "<regexPattern>"

    • 与正则表达式模式相对应的字符串。字符串可以包含有效的 JSON 字符和非转义双引号 (") 字符,但不能包含未转义的正斜杠 (/) 字符。

  • "<options>"

    • 指定 BSON 正则表达式选项的字符串。必须按字母顺序指定选项。有关受支持选项的信息,请参阅 $options

Timestamp

规范
宽松
{"$timestamp": {"t": <t>, "i": <i>}}
<Same as Canonical>

其中的值如下所示:

  • <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 对象转换方法将该对象转换为不同的形式。

conversions 集合中创建文档:

db.conversions.insertOne( { insertDate: new Date() } )

mongosh 返回一个文档对象:

{
acknowledged: true,
insertedId: ObjectId("61fbaf25671c45f3f5f4074a")
}

对存储在 MongoDB 文档对象中的数据进行序列化:

serialized = EJSON.serialize( db.conversions.findOne() )

mongosh 解析了 JavaScript 对象,并使用 "$" 前缀类型来返回值:

{
_id: { '$oid': '61fbaf25671c45f3f5f4074a' },
insertDate: { '$date': '2022-02-03T10:32:05.230Z' }
}

对已序列化的对象进行反序列化:

EJSON.deserialize( serialized )

mongosh 解析 JavaScript 对象,并使用默认 mongosh 类型形式返回值:

{
_id: new ObjectId( "61fbaf25671c45f3f5f4074a" ),
insertDate: ISODate( "2022-02-03T10:32:05.230Z" )
}

将对象转换为字符串:

stringified = EJSON.stringify( db.conversions.findOne() )

mongosh 将转换后的对象的元素作为字符串输出:

{
"_id": {"$oid":"61fbaf25671c45f3f5f4074a"},
"insertDate":{"$date":"2022-02-03T10:32:05.230Z"}
}

解析字符串以创建对象:

EJSON.parse( stringified )

mongosh 将转换后的字符串作为文档返回:

{
_id: new ObjectId("61fbaf25671c45f3f5f4074a"),
insertDate: ISODate("2022-02-03T10:32:05.230Z")
}

后退

比较和排序顺序