定义
兼容性
可以使用 $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 接受包含以下字段的文档:
字段 | 必要性 | 说明 |
|---|---|---|
| 必需 | |
| 必需 | 指定将
|
| 如果将 | |
| Optional | 如果 |
| 转换为 binData 或从 binData 转换时为必填项。 | 指定输入或输出的 binData 格式。可以是以下值之一:
如果 |
| Optional | 转换期间出现错误时返回的值,其中包括不支持的类型转换。参数可以是任何有效表达式。 如果未指定,此操作则会在出现错误时引发错误并停止。 |
| Optional |
除 $convert 外,当默认 "onError" 和 "onNull" 行为可以接受时,MongoDB 还提供以下聚合操作符作为速记:
类型标识符
to.type 字段接受以下数字和 string 标识符:
字符串标识符 | 数字标识符 | 注意 |
|---|---|---|
"double" | 1 | 请参阅 转换为 double。 |
"string" | 2 | 请参阅转换为字符串。 |
"binData" | 5 | 请参阅 转换为 BinData。 |
"objectId" | 7 | 请参阅 转换为 ObjectId。 |
"bool" | 8 | 请参阅转换为布尔值。 |
"date" | 9 | 请参阅转换为日期。 |
"int" | 16 | 请参阅 转换为整数。 |
"long" | 18 | 请参阅转换为长整型。 |
"decimal" | 19 | 请参阅 转换为十进制数。 |
二进制子类型
下表列出 to.subtype 字段的有效值:
数值 | 说明 |
|---|---|
0 | 通用二进制子类型 |
1 | 函数数据 |
2 | 二进制(旧版) |
3 | UUID(旧) |
4 | UUID |
5 | MD5 |
6 | 加密的 BSON 值 |
7 | 压缩时间序列数据 5.2版本新增。 |
8 | 敏感数据,例如密钥或密码。 MongoDB 不会记录子类型为 8 的二进制数据的字面值。相反,MongoDB 会记录占位符值 |
9 | 向量数据是由相同类型的数字组成的密集数组。 |
128 | 自定义数据 |
行为
转换为 BinData
您只能将字符串转换为 binData。所有其他输入类型都会导致错误。
请参阅以下转换为 binData 的示例:
例子 | 结果 |
|---|---|
| |
| |
| |
| |
| |
| |
| |
| |
注意
在 MongoDB 8.0 中,$convert 会返回原始值和原始子类型:而不执行转换。8.0 之前的 MongoDB 版本不支持 binData 转换。
转换为布尔值
下表列出了可转换为布尔值的输入类型:
输入类型 | 行为 |
|---|---|
阵列 | 返回 true |
二进制数据 | 返回 true |
布尔 | 不操作。返回布尔值。 |
代码 | 返回 true |
Date | 返回 true |
Decimal 数据类型 | 如果不为零,返回 true |
double | 如果不为零,返回 true |
整型 | 如果不为零,返回 true |
JavaScript | 返回 true |
Long | 如果不为零,返回 true |
Max key | 返回 true |
最小键值 | 返回 true |
null | 返回为 |
对象 | 返回 true |
ObjectId | 返回 true |
正则表达式 | 返回 true |
字符串 | 返回 true |
时间戳 | 返回 true |
要详细了解 MongoDB 中的数据类型,请参阅 BSON 类型。
下表列出了一些转换为布尔值的示例:
例子 | 结果 |
|---|---|
| true |
| false |
| true |
| true |
| false |
| true |
| true |
| true |
| true |
| true |
| null |
提示
转换为整数
下表列出了可转换为整数的输入类型:
输入类型 | 行为 |
|---|---|
布尔 | 返回 |
double | 返回截断后的值。 截断后的 double 值必须介于整数的最小值与最大值之间。 如果 double 值的截断值小于最小整数值或大于最大整数值,则无法转换该 double 值。 |
Decimal 数据类型 | 返回截断后的值。 截断后的十进制值必须介于整数的最小值与最大值之间。 如果十进制数值的截断值小于最小整数值或大于最大整数值,则无法转换该十进制数值。 |
整型 | 不操作。返回整数值。 |
Long | 以整数形式返回该长整型值。 该长整型值必须介于整数的最小值与最大值范围之间。 不能转换小于最小整数值或大于最大整数值的长整数值。 |
字符串 | 以整数形式返回字符串的数值。 该字符串值必须是以 10 为基数的整数(例如 无法转换浮点数、十进制数或非十进制数的字符串值(例如 |
下表列出了转换为整数的部分示例:
例子 | 结果 |
|---|---|
| 1 |
| 0 |
| 1 |
| 5 |
| 错误 |
| 5000 |
| 错误 |
| -2 |
| 错误 |
| null |
提示
$toInt 操作符。
转换为十进制数
下表列出了可转换为十进制值的输入类型:
输入类型 | 行为 |
|---|---|
布尔 | 返回 |
double | 以十进制形式返回 double 值。 |
Decimal 数据类型 | 不操作。返回该十进制数。 |
整型 | 以十进制形式返回该整型值。 |
Long | 以十进制形式返回该长值。 |
字符串 | 以十进制形式返回该字符串的数值。 字符串值必须是以 10 为基数的数值(例如 无法转换不以 10 为基数的字符串值(例如 |
Date | 返回日期值对应的纪元起的毫秒数。 |
下表列出了转换为十进制值的部分示例:
例子 | 结果 |
|---|---|
| Decimal128("1") |
| Decimal128("0") |
| Decimal128("2.50000000000000") |
| Decimal128("5") |
| Decimal128("10000") |
| Decimal128("-5.5") |
| Decimal128("1522039108044") |
转换为 double
下表列出了可转换为 double 的输入类型:
输入类型 | 行为 |
|---|---|
布尔 | 返回 NumberDouble(0) 以表示 |
double | 不操作。返回 double。 |
Decimal 数据类型 | 以 double 形式返回该十进制值。 该十进制值必须介于 double 的最小值与最大值范围之间。 如果某一十进制值的值小于最小 double 值或大于最大 double 值,则无法转换该十进制值。 |
整型 | 以 double 形式返回该 int 值。 |
Long | 以 double 形式返回该 long 值。 |
字符串 | 以 double 形式返回该字符串的数值。 该字符串值必须是以 10 为基数的数值(例如 无法转换不以 10 为基数的字符串值(例如 |
Date | 返回日期值对应的纪元起的毫秒数。 |
下表列出了转换为 double 的部分示例:
例子 | 结果 |
|---|---|
| 1 |
| 0 |
| 2.5 |
| 5 |
| 10000 |
| - 5.5 |
| 50000000000 |
| 1522039108044 |
转换为长整型
下表列出了可转换为长整型的输入类型:
输入类型 | 行为 |
|---|---|
布尔 | 返回 |
double | 返回截断后的值。 截断后的 double 值必须介于长整型值的最小值与最大值之间。 如果 double 值的截断值小于最小长值或大于最大长值,则无法转换该 double 值。 |
Decimal 数据类型 | 返回截断后的值。 截断后的十进制值必须介于长整型值的最小值与最大值之间。 如果某一十进制数值的截断值小于最小长整型值或大于最大长整型值,则无法转换该十进制数值。 |
整型 | 以 long 形式返回整数值。 |
Long | 不操作。返回长整型值。 |
字符串 | 返回字符串的数值。 该字符串值必须是以 10 为基数的长整型值(例如 无法转换浮点数、十进制数或非十进制数的字符串值(例如 |
Date | 将“日期”转换为自纪元起的毫秒数。 |
下表列出了转换为长整型值的部分示例:
例子 | 结果 |
|---|---|
| Long("1") |
| Long("0") |
| Long("2") |
| Long("5") |
| 错误 |
| Long("8") |
| Long("1522039108044") |
| Long("2") |
| 错误 |
| null |
提示
转换为日期
下表列出了可转换为日期的输入类型:
输入类型 | 行为 |
|---|---|
double | 返回与截断后的由 double 值表示的毫秒数相对应的日期。 正数对应于 1970 年 1 月 1 日以来的毫秒数。 负数对应于 1970 年 1 月 1 日之前的毫秒数。 |
Decimal 数据类型 | 返回与由截断后的十进制值表示的毫秒数相对应的日期。 正数对应于 1970 年 1 月 1 日以来的毫秒数。 负数对应于 1970 年 1 月 1 日之前的毫秒数。 |
Long | 返回与该长值表示的毫秒数相对应的日期。 正数对应于 1970 年 1 月 1 日以来的毫秒数。 负数对应于 1970 年 1 月 1 日之前的毫秒数。 |
字符串 | 返回与日期字符串相对应的日期。 该字符串必须为有效的日期字符串,例如:
|
ObjectId | 返回与对象标识符的时间戳对应的日期。 |
时间戳 | 返回与时间戳相对应的日期。 |
下表列出了转换为日期的部分示例:
例子 | 结果 |
|---|---|
| ISODate("1973-10-20T21:20:00.000Z") |
| ISODate("2009-09-19T14:53:56.000Z") |
| ISODate("2004-11-09T11:33:20.000Z") |
| ISODate("1935-02-22T12:26:40.000Z") |
| ISODate("2018-03-27T04:08:58.000Z") |
| ISODate("2018-03-03T00:00:00.000Z") |
| ISODate("2018-03-20T06:00:06.000Z") |
| 错误 |
| ISODate("2021-11-23T17:21:58.000Z") |
提示
$toDate运算符
转换为 ObjectId
下表列出可以转换为对象标识符的输入类型:
输入类型 | 行为 |
|---|---|
字符串 | 以长度为 24 的 16 进制字符串返回对象标识符。 不能转换不是长度 24 的十六进制字符串的字符串值。 |
下表列出了转换为日期的部分示例:
例子 | 结果 |
|---|---|
| ObjectId("5ab9cbfa31c2ab715d42129e") |
| 错误 |
提示
$toObjectId 操作符。
转换为字符串
下表列出了可转换为字符串的输入类型:
输入类型 | 行为 |
|---|---|
BinData | 以字符串形式返回二进制数据值。 |
布尔 | 以字符串形式返回该布尔值。 |
double | 以字符串形式返回该 double 值。 |
Decimal 数据类型 | 以字符串形式返回该十进制值。 |
整型 | 以字符串形式返回该整型值。 |
Long | 以字符串形式返回该长整型值。 |
ObjectId | 以十六进制字符串形式返回该 ObjectId 值。 |
字符串 | 不操作。返回该字符串值。 |
Date | 以字符串形式返回该日期。 |
下表列出了转换为字符串的部分示例:
例子 | 结果 |
|---|---|
| "true" |
| "false" |
| "2.5" |
| "2" |
| "1000" |
| "5ab9c3da31c2ab715d421285" |
| "2018-03-27T16:58:51.538Z" |
| 'hn3f' |
| "invalid" |
示例
本页上的示例使用来自 sample_mflix 数据集的数据。有关如何将此数据集加载到您的自管理 MongoDB 部署中的详细信息,请参阅 加载示例数据集。如果您对示例数据库进行了任何修改,您可能需要删除并重新创建数据库,才能运行此页面上的示例。
基数转换示例
十六进制字符串是一种表示整数的紧凑方式,许多系统将标识符作为十六进制值进行交换。以下示例将每部电影的数字 imdb.id 转换为十六进制字符串:
db.movies.aggregate( [ { $match: { title: { $in: [ "The Godfather", "Toy Story", "Metropolis" ] } } }, { $sort: { title: 1 } }, { $project: { _id: 0, title: 1, imdbId: "$imdb.id", hexId: { $convert: { input: "$imdb.id", to: "string", base: 16 } } } }] )[ { title: 'Metropolis', imdbId: 293416, hexId: '47A28' }, { title: 'The Godfather', imdbId: 68646, hexId: '10C26' }, { title: 'Toy Story', imdbId: 114709, hexId: '1C015' }]要将十六进制字符串转换回整数,请将该字符串传递给 $convert,并使用 base: 16 和 to: "int"。
类型转换示例
以下聚合操作将 imdb.rating 字段转换为 double,该字段在大多数文档中是 double,但在其他文档中是空字符串。它还将 metacritic 字段(某些文档中缺少该字段)转换为整数。$match 阶段选择了三部电影来说明每种转换结果:
db.movies.aggregate( [ { $match: { title: { $in: [ "The Danish Girl", "The Godfather", "Gertie the Dinosaur" ] } } }, { $project: { _id: 0, title: 1, rating: { $convert: { input: "$imdb.rating", to: "double", onError: "Error", onNull: 0 } }, metacritic: { $convert: { input: "$metacritic", to: "int", onError: "Error", onNull: 0 } } } }, { $sort: { title: 1 } }] )[ { title: 'Gertie the Dinosaur', rating: 7.3, metacritic: 0 }, { title: 'The Danish Girl', rating: 'Error', metacritic: 0 }, { title: 'The Godfather', rating: 9.2, metacritic: 100 }]对于 The Danish Girl,imdb.rating 中的空 string 无法转换为 double,因此 onError 返回 "Error"。对于 Gertie the Dinosaur 和 The Danish Girl,缺少 metacritic,因此 onNull 返回 0。