扩展JSON（V2）

进入MongoDB中文手册（4.2版本）目录

消除歧义
下一页讨论了MongoDB Extended JSON v2。有关旧版MongoDB扩展JSON v1的讨论，请参阅 扩展JSON（v1）。
有关mongo Shell的类型的包装器方法，请参阅 mongo Shell中的数据类型。

JSON只能直接表达 BSON支持的类型的子集。为了保留类型信息，MongoDB对JSON格式进行了以下扩展：

• 规范模式（Canonical Mode）
  一种字符串格式，该格式强调类型保留，但会牺牲可读性和互操作性。也就是说，除非在某些特定情况下，从规范到BSON的转换通常会保留类型信息。
• 宽松模式（Relaxed Mode）
  一种字符串格式，它以保留类型为代价，强调可读性和互操作性。即，从宽松格式转换为BSON可能会丢失类型信息。

两种格式都符合JSON RFC，并且可以由各种MongoDB驱动程序和工具进行解析。

1 扩展JSON V2的用法

1.1 驱动程序

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

• C
• C++
• Go
• Java
• Node
• Perl
• PHPC
• Python
• Scala

C＃和Ruby使用旧版MongoDB扩展JSON v1，请参阅 扩展JSON（v1）。

1.2 MongoDB命令行工具

从4.2版开始：

命令	描述
bsondump	使用扩展JSON v2.0（规范模式）格式。
mongodump	对元数据使用扩展的JSON v2.0（规范模式）格式。需要mongorestore支持扩展JSON v2.0（规范模式或宽松模式）格式的4.2+版本。 提示：在一般情况下，mongodump和mongorestore使用版本要一致 。也就是说，要还原使用特定版本创建的数据文件mongodump，请使用的相应版本mongorestore。
mongoexport	默认情况下，以扩展JSON v2.0（轻松模式）创建输出数据（output data）。 如果与–jsonFormat canonical一起使用，则以扩展JSON v2.0（规范模式）创建输出数据（output data）。
mongoimport	预期导入数据默认版本为扩展JSON v2.0（轻松模式或规范模式）。如果指定了选项–legacy，则可以识别扩展JSON v1.0格式的数据。 提示：在一般情况下，mongoexport和 mongoimport的版本应该匹配。也就是说，要导入从mongoexport创建的数据，mongoimport应该使用的相应版本。

2 BSON数据类型和关联的表达形式

下面介绍了一些常见的BSON数据类型以及规范（Canonical）模式和宽松（Relaxed）模式中的相关表示形式。

• Array
• Binary
• Date
• Decimal128
• Document
• Double
• Int32
• Int64
• MaxKey
• MinKey
• ObjectId
• Regular Expression
• Timestamp

有关完整列表，请参见 https://github.com/mongodb/specifications/blob/master/source/extended-json.rst#conversion-table

数组（Array）

规范模式	宽松模式
[ <elements>]	<和规范模式一样>

其中数组元素如下：

• <elements>
  数组元素使用扩展JSON。要指定一个空数组，请省略[ ]。

二进制（Binary）

规范模式	宽松模式
{"$binary":                   {                    “base64”: “<payload>”,    “subType”: “<t>”    }            }	<和规范模式一样>

值如下：

• “<payload>”
  Base64编码（填充为“ =”）负载字符串（Base64 encoded (with padding as “=”) payload string）。
• <t>
  一个或两个字符的十六进制字符串对应一个BSON二进制子类型(BSON binary subtype)。有关可用的子类型，请参阅扩展bson文档http://bsonspec.org/spec.html。

日期（Date）
对于1970年和9999年之间的日期，包括：

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

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

规范模式	宽松模式
{"$date": {"$numberLong": “<millis>”}}	<和规范模式一样>

值如下：

• “<millis>”
  一个64位带符号整数作为字符串。该值表示相对于纪元的毫秒数。
• “<ISO-8601 Date/Time Format>”
  是一个ISO-8601网络日期/时间格式（ ISO-8601 Internet Date/Time Format）的字符串。日期/时间的最大时间精度为毫秒：
   * 如果小数部分不为零，则小数秒将精确到小数点后三位。
   * 否则，如果为零，则应忽略小数秒。

Decimal128
3.4版的新功能。

规范模式	宽松模式
{ “$numberDecimal”: “” }	<和规范模式一样>

值如下：

• “<number>”
  一个高精度小数(high-precision decimal)的字符串。

Decimal128

规范模式	宽松模式
{ <content< }	<和规范模式一样>

其中文件内容如下：

• <content>
  使用扩展JSON的键值对。要指定一个空文档，请省略{ }。

Double
对于有限数：

规范模式	宽松模式
{"$numberDouble": “” }	<非整数(non-integer number)>

对于无限数或NAN：

规范模式	宽松模式
{"$numberDouble": <“Infinity”|"-Infinity"|“NaN”> }	<和规范模式一样>

值如下：

• “<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 }	<和规范模式一样>

MaxKey对应的BSON数据类型比所有其他类型都高。有关BSON类型的比较顺序的更多信息，请参见 比较和排序。

MinKey

规范模式	宽松模式
{ “$minKey”: 1 }	<和规范模式一样>

MinKey 对应的BSON数据类型比所有其他类型都低。有关BSON类型的比较顺序的更多信息，请参见 比较和排序。

ObjectId

规范模式	宽松模式
{ “$oid”: “<ObjectId bytes>” }	<和规范模式一样>

值如下：

• “<ObjectId bytes>”
  一个24字符的大端十六进制字符串，来表示ObjectId字节。

Regular Expression

规范模式	宽松模式
{“ $ regularExpression”： {                        “ pattern”：“ <regexPattern>”，      “ options”：“ <选项>”   }               }	<和规范模式一样>

值如下：

• “<regexPattern>”
  正则表达式模式的字符串。该字符串可以包含有效的JSON字符和未转义的双引号（"）字符，但不能包含未转义的正斜杠（/）字符。
• “<options>”
  指定BSON正则表达式选项的字符串（“ g”，“ i”，“ m”和“ s”）或空字符串""。
  转换为该表示形式时，除（‘g’，‘i’，‘m’和’s’）以外的其他选项将被删除。

重要提示
选项必须按字母顺序排列。

Timestamp

规范模式	宽松模式
{“ $ timestamp”：{“ t”：<t>，“ i”：<i>}}	<和规范模式一样>

值如下：

• <t>
  从纪元以来的秒数的正整数。
• <i>
  增量的正整数。

2.1 例子

示例字段名称	规范模式	宽松模式
“_id:”	{“$oid”:”5d505646cf6d4fe581014ab2”}	{“$oid”:”5d505646cf6d4fe581014ab2”}
“arrayField”:	[“hello”,{“$numberInt”:”10”}]	[“hello”,10]
“dateField”:	{“KaTeX parse error: Expected '}', got 'EOF' at end of input: date”:{“numberLong”:”1565546054692”}}	{“$date”:”2019-08-11T17:54:14.692Z”}
“dateBefore1970”:	{“KaTeX parse error: Expected '}', got 'EOF' at end of input: date”:{“numberLong”:”-1577923200000”}}	{“KaTeX parse error: Expected '}', got 'EOF' at end of input: 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}}

进入MongoDB中文手册（4.2版本）目录