/ /

$convert（表达式操作符）

定义

$convert: 将数值转换为指定类型。

兼容性

可以使用 $convert 查找托管在以下环境中的部署：

MongoDB Atlas：用于云中 MongoDB 部署的完全托管服务

MongoDB Enterprise：基于订阅、自我管理的 MongoDB 版本
MongoDB Community：源代码可用、免费使用且可自行管理的 MongoDB 版本

语法

在版本8.3中进行了更改。

{
   $convert:
      {
         input: <expression>,
         to: <type expression> || {
            type: <type expression>,
            subtype: <int>
         },
         base: <expression>,       // new in 8.3
         format: <string>,
         onError: <expression>,
         onNull: <expression>
      }
}

$convert 接受包含以下字段的文档：

字段

必要性

说明

input

必需

参数可以是任何有效的表达式。有关表达式的更多信息，请参阅表达式。

从MongoDB 8.1 开始，如果将 input字段设立为以下类型之一，则可以将 to字段设立为 binData：

int
long
double

从MongoDB8.3 tobinData开始，如果input 字段是数值的，您还可以将字段设立为array 。有关示例，请参阅将数值数组转换为 binData。

将值转换为 binData 时， MongoDB还支持这些数字类型作为输入。

to

必需

指定将 input 表达式转换为的类型。您可以将 to 设置为以下值之一：

目标类型的字符串或数字标识符。请参阅 to.type。
包含字段 to.type 和 to.subtype 的对象。使用此格式转换为 binData 并指定 binData 子类型。

to.type

如果将 to 指定为对象，则为必填项

参数可以是任何有效表达式，并能解析为下列数字或字符串标识符之一：

字符串标识符	数字标识符	注意
"double"	1	有关转换为双精度值的更多信息，请参阅转换为双精度值。
"string"	2	有关转换为字符串的更多信息，请参阅转换为字符串。
"object"	3	有关转换为对象的更多信息，请参阅转换为对象。
"array"	4	有关转换为大量的更多信息，请参阅转换为数组。
"binData"	5	有关转换为 binData 的更多信息，请参阅转换为 BinData。
"objectId"	7	有关转换为 ObjectId 的更多信息，请参阅转换为 ObjectId。
"bool"	8	有关转换为布尔值的更多信息，请参阅转换为布尔值。
"date"	9	有关转换为日期的更多信息，请参阅转换为日期。
"int"	16	有关转换为整数的更多信息，请参阅转换为整数。
"long"	18	有关转换为长整型的更多信息，请参阅转换为长整型。
"decimal"	19	有关转换为十进制的更多信息，请参阅转换为十进制。

to.subtype

Optional

如果 to.type 为 binData，则 to.subtype 会指定要转换到的 binData 子类型。您可以为 to.subtype 指定以下值之一：

数值	说明
0	通用二进制子类型
1	函数数据
2	二进制（旧版）
3	UUID（旧）
4	UUID
5	MD5
6	加密的 BSON 值
7	压缩时间序列数据 5.2 版本中的新增功能。
8	敏感数据，例如密钥或密码。 MongoDB 不会记录子类型为 8 的二进制数据的字面值。相反，MongoDB 会记录占位符值`###` 。
9	向量数据是由相同类型的数字组成的密集数组。
128	自定义数据

默认值： 0（通用二进制子类型）

byteOrder

Optional

为 binData 和数字类型之间的转换指定大端字节序或小端字节序。如果未指定，默认为小端字节顺序。

base

Optional

用于在字符串和数字类型之间转换的整数基数。

如果为null ，$convert 的行为就像省略了基数一样。
如果指定，则在字符串与数字类型 int、long、double 和 decimal 之间进行转换时， MongoDB会以所选基数解释该值。对于其他转换， MongoDB会验证 base 的值，但在其他情况下将其忽略。
基数必须为 2、8、10 或 16。

8.3版本新增。

format

与 binData 和字符串相互转换时必需

指定 binData 和字符串之间的转换格式

base64
base64url
utf8
hex
uuid

如果 format 是 uuid，to.subtype 必须是 4。

onError

Optional

转换期间出现错误时返回的值，其中包括不支持的类型转换。参数可以是任何有效表达式。

如果未指定，此操作则会在出现错误时引发错误并停止。

onNull

Optional

当 input 为 null 或缺失时要返回的值。参数可以是任何有效的表达式。

$convert如果未指定，则当input 为 null 或缺失时，会返回 null。

除 $convert 外，当默认 "onError" 和 "onNull" 行为可以接受时，MongoDB 还提供以下聚合操作符作为速记：

行为

以下部分介绍如何将值转换为不同类型。

转换为 BinData

从MongoDB 8.1 开始，如果将 input字段设立为以下类型之一，则可以将 to字段设立为 binData：

int
long
double

从MongoDB 8.1 开始，尝试在不同 binData 子类型之间进行转换时，$convert 会返回错误。在MongoDB 8.0 中，$convert 返回原始值和原始子类型：不执行转换。8.0 之前的MongoDB版本没有 binData 转换。

从数字类型转换为 `binData`:

将数字类型转换为 binData 时：

int 成为 4 字节的 binData。
long 成为 8 字节的 binData。
double 成为 8 字节的 binData。

数值输出的 byteOrder 默认为“little”，即最低有效字节在前。相反，“big”会将最高有效字节放在第一位。

将 long 转换为 binData：

输入：

db.t.insertOne( { a: Long(42) } )

db.t.aggregate([
  {
    $project: {
      _id: 0,
      convertedBD: {
        $convert: {
           input: "$a",
           to: "binData",
      }
    },
  }
}
])

输出：

[
  {
    convertedBD: Binary.createFromBase64('KgAAAAAAAAA=', 0)
  }
]

使用大端字节序将 long 转换为 binData：

输入：

db.t.insertOne( { a: Long(42) } )

db.t.aggregate([
  {
    $project: {
      _id: 0,
      convertedBD: {
        $convert: {
           input: "$a",
           to: "binData",
           byteOrder: "big",
        }
      },
    }
  }
])

输出：

[
  {
    convertedBD: Binary.createFromBase64('AAAAAAAAACo=', 0),
  }
]

将 double 转换为 binData：

输入：

db.t.insertOne( { a: Double(42.0) } )

db.t.aggregate([
  {
    $project: {
      _id: 0,
      convertedBD: {
        $convert: {
           input: "$a",
           to: "binData",
        }
      },
    }
  }
])

输出：

[
  {
    convertedBD: Binary.createFromBase64('AAAAAAAARUA=', 0)
  }
]

将 int 转换为 binData：

输入：

db.t.insertOne( { a: 42 } )

db.t.aggregate([
  {
    $project: {
      _id: 0,
      convertedBD: {
        $convert: {
           input: "$a",
           to: "binData",
        }
      },
    }
  }
])

输出：

[
  {
    convertedBD: Binary.createFromBase64('KgAAAA==', 0)
  }
]

将数值大量转换为 binData：

此示例展示了 $convert 如何将包含不同类型数值的数组转换为 binData。

输入：

db.t.insertMany([
    // Empty array
    { a: [ ] },
    // Bool array
    { a: [
            false, true,  true,  true,
            true,  true,  true,  true,
            false, false, false, false,
            false, true,  true,  true
         ]
    },
    // Int array 
    { a: [NumberInt(0), NumberInt(1), NumberInt(0), NumberInt(10)] },
    
    // Double array 
    { a: [ Double(0.0), Double(1.0), Double(0.0), Double(1.0), Double(3.14) ] },
])

db.t.aggregate([
    {
      $project: {
        _id: 0,
        original: "$a",
        convertedVector: {
          $convert: {
            input: "$a",
            to: { type: "binData" } 
          }
        }
      }
    }
])

输出：

[
  {
    original: [],
    convertedVector: Binary.fromPackedBits(new Uint8Array([]))
  },
  {
    original: [
      false, true,  true,  true,
      true,  true,  true,  true,
      false, false, false, false,
      false, true,  true,  true
    ],
    convertedVector: Binary.fromPackedBits(new Uint8Array([ 127, 7 ]))
  },
  {
    original: [ 0, 1, 0, 10 ],
    convertedVector: Binary.fromInt8Array(new Int8Array([ 0, 1, 0, 10 ]))
  },
  {
    original: [ 0, 1, 0, 1, 3.14 ],
    convertedVector: Binary.fromFloat32Array(new Float32Array([ 0, 1, 0, 1, 3.140000104904175 ]))
  }
]

从字符串转换为 BinData

MongoDB还支持 binData 和字符串之间的转换。

以下示例演示如何将字符串转换为 binData。

例子

结果

{
   input: "hn3uUsMxSE6S0cVkebjmfg==",
   to: {
      type: "binData",
      subtype: 0
   },
   format: "base64"
}

Binary.createFromBase64('hn3uUsMxSE6S0cVkebjmfg==', 0)

{
   input: "hn3uUsMxSE6S0cVkebjmfg==",
   to: "binData",
   format: "base64"
}

Binary.createFromBase64('hn3uUsMxSE6S0cVkebjmfg==', 0)

{
   input: "867dee52-c331-484e-92d1-c56479b8e67e",
   to: {
      type: "binData",
      subtype: 0
   },
   format: "base64"
}

Failed to parse BinData '867dee52-c331-484e-92d1-c56479b8e67e'
in $convert with no onError value: Input is not a valid base64
string.

{
   input: "hn3uUsMxSE6S0cVkebjmfg==",
   to: {
      type: "binData",
      subtype: 4
   },
   format: "base64"
}

Failed to parse BinData 'hn3uUsMxSE6S0cVkebjmfg==' in $convert
with no onError value: Input is not a valid base64 string.

{
   input: "867dee52-c331-484e-92d1-c56479b8e67e",
   to: {
      type: "binData",
      subtype: 4
   },
   format: "uuid"
}

UUID('867dee52-c331-484e-92d1-c56479b8e67e')

{
   input: "äöäöä",
   to: {
      type: "binData",
      subtype: 4
   },
   format: "uuid"
}

Failed to parse BinData 'äöäöä' in $convert with no onError
value: Input is not a valid UUID string.

{
   input: "867dee52-c331-484e-92d1-c56479b8e67e",
   to: { type: "binData" },
   format: "uuid"
}

Failed to parse BinData '867dee52-c331-484e-92d1-c56479b8e67e'
in $convert with no onError value: Only the UUID subtype (4)
is allowed with the 'uuid' format.

注意

转换为数组

8.3版本新增。

下表列出了可转换为大量的输入类型：

输入类型	行为
BinData	返回数值大量。大量元素的数字类型取决于 binData 格式。
字符串	返回与字符串内容相对应的大量。该字符串必须包含表示有效JSON大量的字符。
空值或缺失	返回 null。

下表列出了字符串到大量转换的部分示例：

例子

结果

{ input: "[1, 2, 3]", to: "array" }

[ 1, 2, 3 ]

{ input: '["a", "b", "c"]', to: "array" }

[ 'a', 'b', 'c' ]

{ input: "[]", to: "array" }

[ ]

{ input: "{}", to: "array" }

错误：输入与预期类型“大量”不匹配

{ input: 123, to: "array" }

错误：在 $convert 中不支持在没有 onError 值的情况下从 int 到大量的转换

{ input: "123", to: "array" }

错误：输入不代表有效的JSON：意外的独立运行值

{ input: "[{\"$oid\": \"507f1f77bcf86cd799439011\"}]", to:
"array" }

[ { '$oid': '507f1f77bcf86cd799439011' } ]

{ input: "[1, 2, 3]", to: "array", format: "base64url" }

[ 1, 2, 3 ]

注意

format 选项将被忽略。

{ input: "asdf", to: "array", onError: "on error!" }

'on error!'

{ input: null, to: "array", onNull: "on null!" }

'on null!'

将 binData 转换为数组

此示例展示了 $convert 如何将不同格式的 binData 转换为包含各自类型值的数组：

输入：

db.t.insertMany([
  // Empty PACKED_BIT vector converts to empty array
  { v: BinData(9, "EAA=") },
  // PACKED_BIT vector converts to bool array
  { v: BinData(9, "EAB/Bw==") },
  // INT8 vector converts to int array
  { v: BinData(9, "AwAAAQ==") },
  // FLOAT32 vector converts to double array
  { v: BinData(9, "JwCamZk+") },
  // FLOAT32 vector with special values converts to [-Infinity, 0, Infinity]
  { v: BinData(9, "JwAAAID/AAAAAAAAgH8=") }
])

db.t.aggregate([
  {
    $project: {
      _id: 0,
      original: "$v",
      asArray: {
        $convert: {
          input: "$v",
          to: { type: "array" }
        }
      }
    }
  }
])

输出：

[
  { original: Binary.fromPackedBits(new Uint8Array([])), asArray: [] },
  {
    original: Binary.fromPackedBits(new Uint8Array([ 127, 7 ])),
    asArray: [
      false, true,  true,  true,
      true,  true,  true,  true,
      false, false, false, false,
      false, true,  true,  true
    ]
  },
  {
    original: Binary.fromInt8Array(new Int8Array([ 0, 1 ])),
    asArray: [ 0, 1 ]
  },
  {
    original: Binary.fromFloat32Array(new Float32Array([ 0.30000001192092896 ])),
    asArray: [ 0.30000001192092896 ]
  },
  {
    original: Binary.fromFloat32Array(new Float32Array([ -Infinity, 0, Infinity ])),
    asArray: [ -Infinity, 0, Infinity ]
  }
]

转换为对象

8.3版本新增。

下表列出了可转换为对象的输入类型：

输入类型	行为
字符串	返回与字符串中的内容相对应的文档。该字符串必须包含表示有效JSON对象的字符。
空值或缺失	返回 null。

下表列出了转换为对象的部分示例：

例子

结果

{ input: "{\"a\": 1, \"b\": 2}", to: "object" }

{ a: 1, b: 2 }

{ input: "{}", to: "object" }

{ }

{ input: "[]", to: "object" }

错误：输入与预期类型“对象”不匹配

{ input: "123", to: "object" }

错误：输入不代表有效的JSON：意外的独立运行值

{ input: "{\"nam\\u0000e\": \"foo\"}", to: "object" }

错误：输入不代表有效的JSON：非法嵌入空字节

{ input: "{\"name\": \"fo\\u0000o\"}", to: "object" }

{ name: 'fox00o' }

{ input: "{\"a\": 1, \"b\": 2, \"a\": 3}", to: "object" }

{ a: 3, b: 2 }

{ input: "{\"foo\": null}", to: "object" }

{ foo: null }

{ input: "{\"foo\": false}", to: "object" }

{ foo: false }

{ input: "{\"__proto__\": {\"foo\": null}}", to: "object" }

{ ['__proto__']: { foo: null } }

{ input: "{\"foo\": \"NaN\"}", to: "object" }

{ foo: 'NaN' }

{ input: "{\"foo\": 123}", to: "object" }

{ foo: 123 }

{ input: "{\"foo\": 4294967296}", to: "object" }

{ foo: Long('4294967296') }

{ input: "{\"foo\": 1.123123}", to: "object" }

{ foo: 1.123123 }

{ input: "{\"foo\": 1.2e+3}", to: "object" }

{ foo: 1200 }

{ input: "{\"largePos\": 18446744073709551615}", to: "object" }

{ largePos: 18446744073709552000 }

{ input: "{\"largeNeg\": -18446744073709551615}", to: "object" }

{ largeNeg: -18446744073709552000 }

{ input: null, to: "object" }

null

{
   input: "{\"objectId\": \"507f1f77bcf86cd799439011\",
   \"uuid\": \"3b241101-e2bb-4255-8caf-4136c566a962\",
   \"date\": \"2018-03-27T16:58:51.538Z\", \"regex\":
   \"/^ABC/i\", \"js\": \"function (s) {return s +
   \\\"foo\\\";}\", \"timestamp\": \"Timestamp(1565545664,
   1)\", \"arr\": [1, 2, 3]}", to: "object"
}

{

objectId: '507f1f77bcf86cd799439011',
uuid: '3b241101-e2bb-4255-8caf-4136c566a962',
date: '2018-03-27T16:58:51.538Z',
regex: '/^ABC/i',
js: 'function (s) {return s + "foo";}',
timestamp: 'Timestamp(1565545664, 1)',
arr: [ 1, 2, 3 ]

}

转换为布尔值

下表列出了可转换为布尔值的输入类型：

输入类型	行为
阵列	返回 true
二进制数据	返回 true
布尔	不操作。返回布尔值。
代码	返回 true
Date	返回 true
Decimal 数据类型	Returns true if not zero Return false if zero
double	Returns true if not zero Return false if zero
整型	Returns true if not zero Return false if zero
JavaScript	返回 true
Long	Returns true if not zero Return false if zero
Max key	返回 true
最小键值	返回 true
null	返回为 `onNull` 选项指定的值。默认情况下，返回 null。
对象	返回 true
ObjectId	返回 true
正则表达式	返回 true
字符串	返回 true
时间戳	返回 true

要详细了解 MongoDB 中的数据类型，请参阅 BSON 类型。

下表列出了一些转换为布尔值的示例：

例子

结果

{ input: true, to: "bool" }

true

{ input: false, to: "bool" }

false

{ input: 1.99999, to: "bool" }

true

{ input: Decimal128( "5" ), to: "bool" }

true

{ input: Decimal128( "0" ), to: "bool" }

false

{ input: 100, to: "bool" }

true

{
   input: ISODate( "2018-03-26T04:38:28.044Z" ),
   to: "bool"
}

true

{ input: "hello", to: "bool" }

true

{ input: "false", to: "bool" }

true

{ input: "", to: "bool" }

true

{ input: null, to: "bool" }

null

转换为整数

下表列出了可转换为整数的输入类型：

输入类型	行为
布尔	Returns `0` for `false`. Returns `1` for `true`.
BinData	以整数形式返回 `binData` 值。`binData` 被解释为二进制的有符号补码有符号整数。 `binData` 值中的字节数必须为 `1`、`2` 或 `4`。如果 `input` 的长度超出预期，则会产生错误。您可以通过配置 `$convert.onError` 来控制此行为。
double	返回截断后的值。截断后的 double 值必须介于整数的最小值与最大值之间。如果 double 值的截断值小于最小整数值或大于最大整数值，则无法转换该 double 值。
Decimal 数据类型	返回截断后的值。截断后的十进制值必须介于整数的最小值与最大值之间。如果十进制数值的截断值小于最小整数值或大于最大整数值，则无法转换该十进制数值。
整型	不操作。返回整数值。
Long	以整数形式返回该长整型值。该长整型值必须介于整数的最小值与最大值范围之间。不能转换小于最小整数值或大于最大整数值的长整数值。
字符串	以整数形式返回字符串的数值。如果省略`base` 或设立为`null` ，则字符串值必须是有效的₁₀ 基整数，并且介于整数的最小值和最大值之间。如果指定 `base`，则字符串必须仅包含以该基数表示的有效数字。不允许使用 `"0x"` 等前缀。生成的整数必须在整数的最小值和最大值之间。

下表列出了转换为整数的部分示例：

例子

结果

{ input: true, to: "int" }

{ input: false, to: "int" }

{ input: 1.99999, to: "int" }

{ input: Decimal128( "5.5000" ), to: "int" }

{
   input: Decimal128( "9223372036000.000" ),
   to: "int"
}

错误

{ input: Long( "5000" ), to: "int" }

5000

{ input: Long( "922337203600" ), to: "int" }

错误

{ input: "-2", to: "int" }

-2

{ input: "2.5", to: "int" }

错误

{ input: null, to: "int" }

null

{
   input: Binary(Buffer.from("00100000", "hex"), 0),
   to: "int",
   byteOrder: "big",
}

1048576

{
   input: Binary(Buffer.from("FFFFE796", "hex"), 0),
   to: "int",
}

-1763180545

{
   input: Binary(Buffer.from("001000000000000", "hex"), 0),
   to: "int",
   byteOrder: "big",
}

错误：由于长度 7 无效，无法转换 BinData

转换为十进制数

下表列出了可转换为十进制值的输入类型：

输入类型	行为
布尔	Returns `Decimal128( "0" )` for `false`. Returns `Decimal128( "1" )` for `true`.
double	以十进制形式返回 double 值。
Decimal 数据类型	不操作。返回该十进制数。
整型	以十进制形式返回该整型值。
Long	以十进制形式返回该长值。
字符串	以十进制形式返回该字符串的数值。如果省略`base` 或设立为`null` ，则字符串值必须是以₁₀ 为基数的有效十进制数，并且介于小数点的最小值和最大值之间。如果指定 `base`，则字符串必须仅包含以该基数表示的有效数字。不允许使用 `"0x"` 等前缀。生成的小数必须介于小数的最小值和最大值之间。
Date	返回日期值对应的纪元起的毫秒数。

下表列出了转换为十进制值的部分示例：

例子

结果

{ input: true, to: "decimal" }

Decimal128("1")

{ input: false, to: "decimal" }

Decimal128("0")

{ input: 2.5, to: "decimal" }

Decimal128("2.50000000000000")

{ input: Int32( 5 ), to: "decimal" }

Decimal128("5")

{ input: Long( 10000 ), to: "decimal" }

Decimal128("10000")

{ input: "-5.5", to: "decimal" }

Decimal128("-5.5")

{
   input: ISODate( "2018-03-26T04:38:28.044Z" ),
   to: "decimal"
}

Decimal128("1522039108044")

转换为 double

下表列出了可转换为 double 的输入类型：

输入类型	行为
布尔	Returns NumberDouble(0) for `false`. Returns NumberDouble(1) for `true`.
BinData	以双精度值形式返回 `binData` 值。 `binData` 被解释为 IEEE 754 单精度或双精度点。 `binData` 值中的字节数必须为 `4` 或 `8`。如果 `input` 的长度超出预期，则会产生错误。您可以通过配置 `$convert.onError` 来控制此行为。
double	不操作。返回 double。
Decimal 数据类型	以 double 形式返回该十进制值。该十进制值必须介于 double 的最小值与最大值范围之间。如果某一十进制值的值小于最小 double 值或大于最大 double 值，则无法转换该十进制值。
整型	以 double 形式返回该 int 值。
Long	以 double 形式返回该 long 值。
字符串	以 double 形式返回该字符串的数值。如果省略`base` 或设立为`null` ，则字符串值必须是有效的基₁₀ 双精度浮点数，并且介于双精度浮点数的最小值和最大值之间。如果指定 `base`，则字符串必须仅包含以该基数表示的有效数字。不允许使用 `"0x"` 等前缀。生成的双精度值必须介于双精度值的最小值和最大值之间。
Date	返回日期值对应的纪元起的毫秒数。

下表列出了转换为 double 的部分示例：

例子

结果

{ input: true, to: "double" }

{ input: false, to: "double" }

{ input: 2.5, to: "double" }

2.5

{ input: Int32( 5 ), to: "double" }

{ input: Long( "10000" ), to: "double" }

10000

{ input: "-5.5", to: "double" }

- 5.5

{ input: "5e10", to: "double" }

50000000000

{
   input: ISODate( "2018-03-26T04:38:28.044Z" ),
   to: "double"
}

1522039108044

{
   input: Binary(Buffer.from("04CCCCCD", "hex"), 0),
   to: "double",
   byteOrder: "big",
}

4.814824932714571e-36

{
   input: Binary(Buffer.from("0000", "hex"), 0),
   to: "double",
   byteOrder: "big",
}

错误：由于长度 2 无效，无法转换 binData

次正规数

从MongoDB8.3 开始，服务器能够解析所有可表示的双精度点的全范围。这包括最高有效数字有前导零且指数具有最小可能值的次正规数。有关详细信息，请参阅次正规数。

在MongoDB的早期版本中，当您尝试解析这些数字时，服务器会返回错误。以下示例会在MongoDB 8.3 之前的版本中引发错误：

db.t.insertOne( { v: "7.08263e-317" } )
db.t.aggregate([
  {
    $project: {
      converted: {
        $convert: { input: "$v", to: "double" },
      }
    }
   }
])

此示例失败并出现类似以下内容的错误：

MongoServerError[ConversionFailure]: Executor error during aggregate command on namespace: test.t ::
caused by :: Failed to parse number '7.08263e-317' in $convert with no onError value: Out of range

转换为长整型

下表列出了可转换为长整型的输入类型：

输入类型	行为
布尔	Returns `0` for `false`. Returns `1` for `true`.
BinData	以长整型形式返回 `binData` 值。`binData` 被解释为二进制的有符号补码有符号整数。 `binData` 值中的字节数必须为 `1`、`2`、`4` 或 `8`。如果 `input` 的长度超出预期，则会产生错误。您可以通过配置 `$convert.onError` 来控制此行为。
double	返回截断后的值。截断后的 double 值必须介于长整型值的最小值与最大值之间。如果 double 值的截断值小于最小长值或大于最大长值，则无法转换该 double 值。
Decimal 数据类型	返回截断后的值。截断后的十进制值必须介于长整型值的最小值与最大值之间。如果某一十进制数值的截断值小于最小长整型值或大于最大长整型值，则无法转换该十进制数值。
整型	以 long 形式返回整数值。
Long	不操作。返回长整型值。
字符串	返回字符串的数值。如果省略`base` 或设立为`null` ，则字符串值必须是有效的基₁₀ 长整型值，并且介于长整型值的最小值和最大值之间。如果指定 `base`，则字符串必须仅包含以该基数表示的有效数字。不允许使用 `"0x"` 等前缀。生成的长整型值必须介于长整型值的最小值与最大值之间。
Date	将“日期”转换为自纪元起的毫秒数。

下表列出了转换为长整型值的部分示例：

例子

结果

{ input: true, to: "long" }

Long("1")

{ input: false, to: "long"  }

Long("0")

{ input: 2.5, to: "long"  }

Long("2")

{ input: Decimal128( "5.5000" ), to: "long" }

Long("5")

{
   input: Decimal128( "9223372036854775808.0" ),
   to: "long"
}

错误

{ input: Int32( 8 ), to: "long" }

Long("8")

{
   input: ISODate( "2018-03-26T04:38:28.044Z" ),
   to: "long"
}

Long("1522039108044")

{ input: "-2", to: "long" }

Long("2")

{ input: "2.5", to: "long" }

错误

{ input: null, to: "long" }

null

{
   input: Binary(Buffer.from("001000000", "hex"), 0),
   to: "long",
   byteOrder: "big",
}

Long("1048576")

转换为日期

下表列出了可转换为日期的输入类型：

输入类型	行为
double	返回与截断后的由 double 值表示的毫秒数相对应的日期。正数对应于 1970 年 1 月 1 日以来的毫秒数。负数对应于 1970 年 1 月 1 日之前的毫秒数。
Decimal 数据类型	返回与由截断后的十进制值表示的毫秒数相对应的日期。正数对应于 1970 年 1 月 1 日以来的毫秒数。负数对应于 1970 年 1 月 1 日之前的毫秒数。
Long	返回与该长值表示的毫秒数相对应的日期。正数对应于 1970 年 1 月 1 日以来的毫秒数。负数对应于 1970 年 1 月 1 日之前的毫秒数。
字符串	返回与日期字符串相对应的日期。该字符串必须为有效的日期字符串，例如： "2018-03-03" "2018-03-03T12:00:00Z" "2018-03-03T12:00:00+0500"
ObjectId	返回与对象标识符的时间戳对应的日期。
时间戳	返回与时间戳相对应的日期。

下表列出了转换为日期的部分示例：

例子

结果

{
   input: 120000000000.5,
   to: "date"
}

ISODate("1973-10-20T21:20:00.000Z")

{
   input: Decimal128( "1253372036000.50" ),
   to: "date"
}

ISODate("2009-09-19T14:53:56.000Z")

{
   input: Long( "1100000000000" ),
   to: "date
}

ISODate("2004-11-09T11:33:20.000Z")

{
   input:  Long( "-1100000000000" ),
   to: "date"
}

ISODate("1935-02-22T12:26:40.000Z")

{
   input: ObjectId( "5ab9c3da31c2ab715d421285" ),
   to: "date"
}

ISODate("2018-03-27T04:08:58.000Z")

{ input:  "2018-03-03", to: "date" }

ISODate("2018-03-03T00:00:00.000Z")

{
   input: "2018-03-20 11:00:06 +0500",
   to: "date"
}

ISODate("2018-03-20T06:00:06.000Z")

{ input: "Friday", to: "date" }

错误

{
   input: Timestamp( { t: 1637688118, i: 1 } ),
   to: "date"
}

ISODate("2021-11-23T17:21:58.000Z")

转换为 ObjectId

下表列出可以转换为对象标识符的输入类型：

输入类型	行为
字符串	以长度为 24 的 16 进制字符串返回对象标识符。不能转换不是长度 24 的十六进制字符串的字符串值。

下表列出了转换为日期的部分示例：

例子

结果

{
   input: "5ab9cbfa31c2ab715d42129e",
   to: "objectId"
}

ObjectId("5ab9cbfa31c2ab715d42129e")

{
   input: "5ab9cbfa31c2ab715d42129",
   to: "objectId"
}

错误

转换为字符串

下表列出了可转换为字符串的输入类型：

输入类型	行为
阵列	以字符串形式返回`Array` 。 8.3版本新增。
BinData	如果 `BinData` 是 UUID，则以 string 形式返回该 UUID。否则，返回以 base64 编码的 string 值。
布尔	以字符串形式返回布尔值。
Date	以字符串形式返回`Date` 。
Decimal 数据类型	`Decimal`以字符串形式返回值。
double	`Double`以字符串形式返回值。
整型	`Integer`以字符串形式返回值。
Long	`Long`以字符串形式返回值。
Max key	以字符串形式返回`MaxKey` 。 8.3版本新增。
最小键值	以字符串形式返回`MinKey` 。 8.3版本新增。
对象	以字符串形式返回该对象。 8.3版本新增。
ObjectId	以十六进制字符串形式返回`ObjectId` 值。
正则表达式	以字符串形式返回`Regular Expression` 。 8.3版本新增。
字符串	无需操作。返回字符串值。
时间戳	以字符串形式返回`Timestamp` 。 8.3版本新增。

注意

当您指定base 且input 为数值类型时，$convert 会返回以该基数表示的整数值的字符串表示形式。字符串的基数转换仅支持针对整数值，否则，除非指定$convert ，否则onError 会返回转换错误。

下表列出了转换为字符串的部分示例：

例子

结果

{ input: true, to: "string" }

"true"

{ input: false, to: "string" }

"false"

{ input: 2.5, to: "string" }

"2.5"

{ input: Int32( 2 ), to: "string" }

"2"

{ input:  Long( 1000 ), to: "string" }

"1000"

{
   input: ObjectId( "5ab9c3da31c2ab715d421285" ),
   to: "string"
}

"5ab9c3da31c2ab715d421285"

{
   input:  ISODate( "2018-03-27T16:58:51.538Z" ),
   to: "string"
}

"2018-03-27T16:58:51.538Z"

{
   input: BinData(4, "hn3f"),
   to: "string",
   format: "base64"
}

'hn3f'

{
   input: 10.5,
   to: "string",
   base: 2,
   onError: "invalid"
}

"invalid"

示例

基数转换示例

使用占位符文档创建集合examples：

db.examples.insertOne({ _id: 1 })

以下示例使用不同进制在数字和字符串之间进行转换：

db.examples.aggregate([
  {
    $project: {
      _id: 0,
      bin:        { $convert: { input: 10,    to: "string", base: 2  } },
      hex:        { $convert: { input: 10,    to: "string", base: 16 } },
      intFromBin: { $convert: { input: "1010", to: "int",   base: 2  } },
      intFromHex: { $convert: { input: "A",    to: "int",   base: 16 } }
    }
  }
])

此操作返回以下文档：

{
  bin: "1010",
  hex: "A",
  intFromBin: 10,
  intFromHex: 10
}

类型转换示例

使用以下文档创建集合 orders：

db.orders.insertMany( [
   { _id: 1, item: "apple", qty: 5, price: 10 },
   { _id: 2, item: "pie", qty: 10, price: Decimal128("20.0") },
   { _id: 3, item: "ice cream", qty: 2, price: "4.99" },
   { _id: 4, item: "almonds" },
   { _id: 5, item: "bananas", qty: 5000000000, price: Decimal128("1.25") }
] )

对 orders 集合执行的以下聚合操作会将 price 转换为十进制值：

// Define stage to add convertedPrice and convertedQty fields with
//    the converted price and qty values.
// If price or qty values are missing, the conversion returns a
//    value of decimal value or int value of 0.
// If price or qty values cannot be converted, the conversion returns
//    a string
priceQtyConversionStage = {
   $addFields: {
      convertedPrice: { $convert:
         {
            input: "$price",
            to: "decimal",
            onError: "Error",
            onNull: Decimal128("0")
         } },
      convertedQty: { $convert:
         {
            input: "$qty",
            to: "int",
            onError:{ $concat:
               [
                  "Could not convert ",
                  { $toString:"$qty" },
                  " to type integer."
               ]
            },
         onNull: Int32("0")
      } },
   }
};
totalPriceCalculationStage = {
   $project: { totalPrice: {
     $switch: {
        branches: [
          { case:
             { $eq: [ { $type: "$convertedPrice" }, "string" ] },
             then: "NaN"
          },
          { case:
             { $eq: [ { $type: "$convertedQty" }, "string" ] },
             then: "NaN"
          },
        ],
        default: { $multiply: [ "$convertedPrice", "$convertedQty" ] }
     }
} } };
db.orders.aggregate( [
   priceQtyConversionStage,
   totalPriceCalculationStage
])

该操作将返回以下文档：

{ _id: 1, totalPrice: Decimal128("50") },
{ _id: 2, totalPrice: Decimal128("200.0") },
{ _id: 3, totalPrice: Decimal128("9.98") },
{ _id: 4, totalPrice: Decimal128("0") },
{ _id: 5, totalPrice: 'NaN' }

注意

这些示例使用 mongosh。旧版 mongo Shell 中的默认类型有所不同。

了解详情

使用以下命令将值转换为大量： $toArray
将字符串转换为对象 $toObject
将值转换为布尔值 $toBool
使用以下命令将值转换为整数： $toInt
使用以下命令将值转换为十进制： $toDecimal
使用以下命令将值转换为双精度值： $toDouble
将值转换为长整型值 $toLong
使用以下命令将值转换为日期： $toDate
使用以下命令将值转换为 ObjectId： $toObjectId
将值转换为字符串 $toString
将日期字符串转换为日期对象 $dateFromString
将日期对象转换为字符串 $dateToString

后退

$cond

来年

$cos

定义

兼容性

语法

行为

转换为 BinData

从数字类型转换为 binData:

从字符串转换为 BinData

注意

转换为数组

注意

将 binData 转换为数组

转换为对象

转换为布尔值

转换为整数

转换为十进制数

转换为 double

次正规数

转换为长整型

转换为日期

转换为 ObjectId

转换为字符串

注意

示例

基数转换示例

类型转换示例

注意

了解详情

从数字类型转换为 `binData`: