$convert（聚合）

在此页面上

定义

兼容性
语法
行为
例子

定义

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

兼容性

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

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

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

语法

在版本8.0中进行了更改。

{
   $convert:
      {
         input: <expression>,
         to: <type expression> || {
            type: <type expression>,
            subtype: <int>
         },
         format: <string>,
         onError: <expression>,
         onNull: <expression>
      }
}

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

字段

必要性

说明

input

必需

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

to

必需

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

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

to.type

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

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

字符串标识符	数字标识符	注意
"double"	1	有关转换为 double 的更多信息，请参阅转换为 double。
"string"	2	有关转换为字符串的更多信息，请参阅转换为字符串。
"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（通用二进制子类型）

format

转换为 binData 或从 binData 转换时为必填项。

指定输入或输出的 binData 格式。可以是以下值之一：

base64
base64url
utf8
hex
uuid

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

onError

Optional

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

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

onNull

Optional

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

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

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

行为

转换为 BinData

您只能将字符串转换为 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.

{
   input: 123,
   to: { type: "binData", subtype: 0 }
}

Unsupported conversion from int to binData in $convert with no onError value

转换为布尔值

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

输入类型	行为
阵列	返回 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

提示

另请参阅：

$toBool

转换为整数

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

输入类型	行为
布尔	Returns `0` for `false`. Returns `1` for `true`.
double	返回截断后的值。截断后的 double 值必须介于整数的最小值与最大值之间。如果 double 值的截断值小于最小整数值或大于最大整数值，则无法转换该 double 值。
Decimal 数据类型	返回截断后的值。截断后的十进制值必须介于整数的最小值与最大值之间。如果十进制数值的截断值小于最小整数值或大于最大整数值，则无法转换该十进制数值。
整型	不操作。返回整数值。
Long	以整数形式返回该长整型值。该长整型值必须介于整数的最小值与最大值范围之间。不能转换小于最小整数值或大于最大整数值的长整数值。
字符串	以整数形式返回字符串的数值。该字符串值必须是以 ₁₀ 为基数的整数（例如 `"-5"`、`"123456"`)，且介于整数的最小值与最大值范围之间。无法转换浮点数、十进制数或非_十进制数的字符串值（例如 `"-5.0"`，`"0x6400"`）或超出整数最小值和最大值的值。

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

例子

结果

{ 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

提示

另请参阅：

$toInt 操作符。

转换为十进制数

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

输入类型	行为
布尔	Returns `Decimal128( "0" )` for `false`. Returns `Decimal128( "1" )` for `true`.
double	以十进制形式返回 double 值。
Decimal 数据类型	不操作。返回该十进制数。
整型	以十进制形式返回该整型值。
Long	以十进制形式返回该长值。
字符串	以十进制形式返回该字符串的数值。字符串值必须是以 ₁₀ 为基数的数值（例如`"-5.5"`、`"123456"`)。无法转换不以 ₁₀ 为基数的字符串值（例如 `"0x6400"`）
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")

提示

另请参阅：

$toDecimal

转换为 double

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

输入类型	行为
布尔	Returns NumberDouble(0) for `false`. Returns NumberDouble(1) for `true`.
double	不操作。返回 double。
Decimal 数据类型	以 double 形式返回该十进制值。该十进制值必须介于 double 的最小值与最大值范围之间。如果某一十进制值的值小于最小 double 值或大于最大 double 值，则无法转换该十进制值。
整型	以 double 形式返回该 int 值。
Long	以 double 形式返回该 long 值。
字符串	以 double 形式返回该字符串的数值。该字符串值必须是以 ₁₀ 为基数的数值（例如 `"-5.5"`、`"123456"`），且介于 double 值的最小值与最大值之间。无法转换不以 ₁₀ 为基数的字符串值（例如`"0x6400"`）或超出 double 值最小值和最大值的值。
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

提示

另请参阅：

$toDouble

转换为长整型

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

输入类型	行为
布尔	Returns `0` for `false`. Returns `1` for `true`.
double	返回截断后的值。截断后的 double 值必须介于长整型值的最小值与最大值之间。如果 double 值的截断值小于最小长值或大于最大长值，则无法转换该 double 值。
Decimal 数据类型	返回截断后的值。截断后的十进制值必须介于长整型值的最小值与最大值之间。如果某一十进制数值的截断值小于最小长整型值或大于最大长整型值，则无法转换该十进制数值。
整型	以 long 形式返回整数值。
Long	不操作。返回长整型值。
字符串	返回字符串的数值。该字符串值必须是以 ₁₀ 为基数的长整型值（例如 `"-5"`、`"123456"`），且介于长整型值的最小值与最大值之间。无法转换浮点数、十进制数或非_十进制数的字符串值（例如 `"-5.0"`、`"0x6400"`）或是超出长整型值的最小值与最大值的值。
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

提示

另请参阅：

$toLong

转换为日期

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

输入类型	行为
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")

提示

另请参阅：

$toDate 运算符
$dateFromString

转换为 ObjectId

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

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

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

例子

结果

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

ObjectId("5ab9cbfa31c2ab715d42129e")

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

错误

提示

另请参阅：

$toObjectId 操作符。

转换为字符串

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

输入类型	行为
BinData	以字符串形式返回二进制数据值。
布尔	以字符串形式返回该布尔值。
double	以字符串形式返回该 double 值。
Decimal 数据类型	以字符串形式返回该十进制值。
整型	以字符串形式返回该整型值。
Long	以字符串形式返回该长整型值。
ObjectId	以十六进制字符串形式返回该 ObjectId 值。
字符串	不操作。返回该字符串值。
Date	以字符串形式返回该日期。

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

例子

结果

{ 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'

提示

另请参阅：

$toString 运算符
$dateToString

例子

使用以下文档创建集合 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 中的默认类型有所不同。

后退

$cond

来年

$cos