Docs 菜单
Docs 主页
/
MongoDB Manual
/ / /

$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.typeto.subtype 的对象。使用此格式转换为 binData 并指定 binData 子类型。

to.type

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

to.subtype

Optional

如果 to.typebinData,则 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

如果 formatuuidto.subtype 必须是 4

onError

Optional

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

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

onNull

Optional

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

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

$convert 外,当默认 "onError" 和 "onNull" 行为可以接受时,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.
{
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

提示

另请参阅:

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

输入类型
行为

布尔

Returns 0 for false.
Returns 1 for true.

double

返回截断后的值。

截断后的 double 值必须介于整数的最小值与最大值之间。

如果 double 值的截断值小于最小整数值或大于最大整数值,则无法转换该 double 值。

Decimal 数据类型

返回截断后的值。

截断后的十进制值必须介于整数的最小值与最大值之间。

如果十进制数值的截断值小于最小整数值或大于最大整数值,则无法转换该十进制数值。

整型

不操作。返回整数值。

Long

以整数形式返回该长整型值。

该长整型值必须介于整数的最小值与最大值范围之间。

不能转换小于最小整数值或大于最大整数值的长整数值。

字符串

以整数形式返回字符串的数值。

该字符串值必须是以 10 为基数的整数(例如 "-5""123456"),且介于整数的最小值与最大值范围之间。

无法转换浮点数、十进制数或非进制数的字符串值(例如 "-5.0""0x6400")或超出整数最小值和最大值的值。

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

例子
结果
{ input: true, to: "int" }

1

{ input: false, to: "int" }

0

{ input: 1.99999, to: "int" }

1

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

5

{
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

以十进制形式返回该长值。

字符串

以十进制形式返回该字符串的数值。

字符串值必须是以 10 为基数的数值(例如"-5.5""123456")。

无法转换不以 10 为基数的字符串值(例如 "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")

提示

另请参阅:

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

输入类型
行为

布尔

Returns NumberDouble(0) for false.
Returns NumberDouble(1) for true.

double

不操作。返回 double。

Decimal 数据类型

以 double 形式返回该十进制值。

该十进制值必须介于 double 的最小值与最大值范围之间。

如果某一十进制值的值小于最小 double 值或大于最大 double 值,则无法转换该十进制值。

整型

以 double 形式返回该 int 值。

Long

以 double 形式返回该 long 值。

字符串

以 double 形式返回该字符串的数值。

该字符串值必须是以 10 为基数的数值(例如 "-5.5""123456"),且介于 double 值的最小值与最大值之间。

无法转换不以 10 为基数的字符串值(例如"0x6400")或超出 double 值最小值和最大值的值。

Date

返回日期值对应的纪元起的毫秒数。

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

例子
结果
{ input: true, to: "double" }

1

{ input: false, to: "double" }

0

{ input: 2.5, to: "double" }

2.5

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

5

{ 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

提示

另请参阅:

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

输入类型
行为

布尔

Returns 0 for false.
Returns 1 for true.

double

返回截断后的值。

截断后的 double 值必须介于长整型值的最小值与最大值之间。

如果 double 值的截断值小于最小长值或大于最大长值,则无法转换该 double 值。

Decimal 数据类型

返回截断后的值。

截断后的十进制值必须介于长整型值的最小值与最大值之间。

如果某一十进制数值的截断值小于最小长整型值或大于最大长整型值,则无法转换该十进制数值。

整型

以 long 形式返回整数值。

Long

不操作。返回长整型值。

字符串

返回字符串的数值。

该字符串值必须是以 10 为基数的长整型值(例如 "-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

提示

另请参阅:

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

输入类型
行为

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")

提示

另请参阅:

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

输入类型
行为

字符串

以长度为 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'

提示

另请参阅:

使用以下文档创建集合 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