MongoDB Extended JSONMongoDB扩展的JSON (v2)

On this page本页内容

Disambiguation消歧

The following page discusses MongoDB Extended JSON v2.下一页讨论MongoDB扩展的JSON v2。For discussion on the Legacy MongoDB Extended JSON v1, see MongoDB Extended JSON (v1).有关遗留MongoDB Extended JSON v1的讨论，请参阅MongoDB Extended JSON（v1）。

For mongo shell wrapper methods for types, see Data Types in the mongo Shell.有关类型的mongo shell包装方法，请参阅mongo shell中的数据类型。

JSON can only directly represent a subset of the types supported by BSON.JSON只能直接表示BSON支持的类型的子集。To preserve type information, MongoDB adds the following extensions to the JSON format.为了保留类型信息，MongoDB向JSON格式添加了以下扩展。

Both formats conform to the JSON RFC and can be parsed by the various MongoDB drivers and tools.这两种格式都符合JSON RFC，可以由各种MongoDB驱动程序和工具进行解析。

MongoDB Extended JSON v2 UsageMongoDB扩展的JSON v2用法

Drivers驱动程序

The following drivers use the Extended JSON v2.0以下驱动程序使用扩展的JSON v2.0

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

For C# and Ruby that use Legacy MongoDB Extended JSON v1, refer to MongoDB Extended JSON (v1).对于使用传统MongoDB Extended JSON v1的C#和Ruby，请参阅MongoDB Extended JSON（v1）。

MongoDB Command-Line ToolsMongoDB命令行工具

Starting in version 4.2:

bsondump Uses Extended JSON v2.0 (Canonical mode) format.使用扩展JSON v2.0（规范模式）格式。
mongodump

Use Extended JSON v2.0 (Canonical mode) format for the metadata.使用针对元数据的扩展的JSON v2.0（规范模式）格式。Requires mongorestore version 4.2+ that supports Extended JSON v2.0 (Canonical mode or Relaxed) format.需要支持扩展JSON v2.0（规范模式或宽松）格式的mongorestore 4.2+版。

Tip

In general, use corresponding versions of mongodump and mongorestore. That is, to restore data files created with a specific version of mongodump, use the corresponding version of mongorestore.

mongoexport
Creates output data in Extended JSON v2.0 (Relaxed mode) by default.默认情况下，以扩展JSON v2.0（宽松模式）创建输出数据。
Creates output data in Extended JSON v2.0 (Canonical mode) if used with --jsonFormat.
mongoimport
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.

Tip

In general, the versions of mongoexport and mongoimport should match. That is, to import data created from mongoexport, you should use the corresponding version of mongoimport.

BSON Data Types and Associated Representations

The following presents some common BSON data types and the associated representations in Canonical and Relaxed.

For a complete list, see https://github.com/mongodb/specifications/blob/master/source/extended-json.rst#conversion-table.

Array
CanonicalRelaxed
 
[ <elements> ]
 
<Same as Canonical>
Where the array elements are as follows:
  • <elements>
    Array elements use Extended JSON. To specify an empty array, omit the content [ ].
Binary
CanonicalRelaxed
 
{ "$binary":
   {
      "base64": "<payload>",
      "subType": "<t>"
   }
}
 
<Same as Canonical>
Where the values are as follows:
  • "<payload>"
    Base64 encoded (with padding as “=”) payload string.
  • "<t>"
    A one- or two-character hex string that corresponds to a BSON binary subtype. See the extended bson documentation http://bsonspec.org/spec.html for subtypes available.
Date

For dates between years 1970 and 9999, inclusive:

CanonicalRelaxed
 
{"$date": {"$numberLong": "<millis>"}}
 
{"$date": "<ISO-8601 Date/Time Format>"}

For dates before year 1970 or after year 9999:

CanonicalRelaxed
 
{"$date": {"$numberLong": "<millis>"}}
 
<Same as Canonical>
Where the values are as follows:
  • "<millis>"
    A 64-bit signed integer as string. The value represents milliseconds relative to the epoch.
  • "<ISO-8601 Date/Time Format>"
    A date in ISO-8601 Internet Date/Time Format as string. The date/time has a maximum time precision of milliseconds:
    • Fractional seconds have exactly 3 decimal places if the fractional part is non-zero.
    • Otherwise, fractional seconds SHOULD be omitted if zero.
Decimal128

New in version 3.4.版本3.4中的新功能。

CanonicalRelaxed
 
{ "$numberDecimal": "<number>" }
 
<Same as Canonical>
Where the values are as follows:
Document
CanonicalRelaxed
 
{ <content> }
 
<Same as Canonical>
Where the document contents are as follows:
  • <content>
    Name:value pairs that use Extended JSON. To specify an empty document, omit the content { }.
Double

For finite numbers:

CanonicalRelaxed
 
{"$numberDouble": "<decimal string>" }
 
<non-integer number>

For infinite numbers or NAN:

CanonicalRelaxed
 
{"$numberDouble": <"Infinity"|"-Infinity"|"NaN"> }
 
<Same as Canonical>
Where the values are as follows:
  • "<decimal string>"
    A 64-bit signed floating point as a string.
  • <non-integer number>
    A non-integer number. Integer numbers are parsed as integer instead of double.
Int64
CanonicalRelaxed
 
{ "$numberLong": "<number>" }
 
<integer>
Where the values are as follows:
  • "<number>"
    A 64-bit signed integer as string.
  • <integer>
    A 64-bit signed integer.
Int32
CanonicalRelaxed
 
{ "$numberInt": "<number>" }
 
<integer>
Where the values are as follows:
  • "<number>"
    A 32-bit signed integer as string.
  • <integer>
    A 32-bit signed integer.
MaxKey
CanonicalRelaxed
 
{ "$maxKey": 1 }
 
<Same as Canonical>

The MaxKey BSON data type compares higher than all other types. See Comparison/Sort Order for more information on comparison order for BSON types.

MinKey
CanonicalRelaxed
 
{ "$minKey": 1 }
 
<Same as Canonical>

The MinKey BSON data type compares lower than all other types. See Comparison/Sort Order for more information on comparison order for BSON types.

ObjectId
CanonicalRelaxed
 
{ "$oid": "<ObjectId bytes>" }
 
<Same as Canonical>
Where the values are as follows:
  • "<ObjectId bytes>"
    A 24-character, big-endian hexadecimal string that represents the ObjectId bytes.
Regular Expression
CanonicalRelaxed
 
{ "$regularExpression":
   {
      "pattern": "<regexPattern>",
      "options": "<options>"
  }
}
 
<Same as Canonical>
Where the values are as follows:
  • "<regexPattern>"

    A string that corresponds to the regular expression pattern. The string can contain valid JSON characters and unescaped double quote (") characters, but may not contain unescaped forward slash (/) characters.

  • "<options>"

    A string that specifies BSON regular expression options (‘g’, ‘i’, ‘m’ and ‘s’) or an empty string "".

    Options other than (‘g’, ‘i’, ‘m’ and ‘s’) will be dropped when converting to this representation.

    Important

    The options MUST be in alphabetical order.

Timestamp
CanonicalRelaxed
 
{"$timestamp": {"t": <t>, "i": <i>}}
 
<Same as Canonical>
Where the values are as follows:
  • <t>
    A positive integer for the seconds since epoch.
  • <i>
    A positive integer for the increment.

Example示例

Example Field NameCanonical FormatRelaxed Format
“_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}}