$convert (aggregation)

Definition定义

$convert

Converts a value to a specified type.将值转换为指定的类型。

$convert has the following syntax:具有以下语法：

{
   $convert:
      {
         input: <expression>,
         to: <type expression>,
         onError: <expression>,  // Optional.
         onNull: <expression>    // Optional.
      }
}

The $convert takes a document with the following fields:$convert获取具有以下字段的文档：

Field字段	Description描述
input	The argument can be any valid expression. 参数可以是任何有效的表达式。For more information on expressions, see Expressions.有关表达式的详细信息，请参阅表达式。
to	The argument can be any valid expression that resolves to one of the following numeric or string identifiers: 参数可以是解析为以下数字或字符串标识符之一的任何有效表达式： String Identifier字符串标识符 Numeric Identifier数字标识符 Notes备注 "double" 1 For more information on the conversion to double, see Converting to a Double.有关转换为double的详细信息，请参阅转换为double。 "string" 2 For more information on the conversion to string, see Converting to a String.有关转换为字符串的详细信息，请参阅转换为字符串。 "objectId" 7 For more information on the conversion to objectId, see Converting to an ObjectId.有关转换为objectId的详细信息，请参阅转换为objectId。 "bool" 8 For more information on the conversion to boolean, see Converting to a Boolean.有关转换为布尔值的详细信息，请参阅转换为布尔型。 "date" 9 For more information on the conversion to date, see Converting to a Date.有关转换为日期的详细信息，请参阅转换为日期。 "int" 16 For more information on the conversion to integer, see Converting to an Integer.有关转换为整数的详细信息，请参阅转换为整数。 "long" 18 For more information on the conversion to long, see Converting to a Long.有关转换为长的详细信息，请参阅转换为Long。 "decimal" 19 For more information on the conversion to decimal, see Converting to a Decimal.有关转换为十进制的详细信息，请参阅转换为十进制。
onError	Optional.可选的。The value to return on encountering an error during conversion, including unsupported type conversions. 在转换过程中遇到错误时返回的值，包括不支持的类型转换。The arguments can be any valid expression.参数可以是任何有效的表达式。 If unspecified, the operation throws an error upon encountering an error and stops. 如果未指定，则操作在遇到错误时抛出错误并停止。
onNull	Optional.可选的。The value to return if the input is null or missing. 如果input为null或缺少，则返回的值。The arguments can be any valid expression.参数可以是任何有效的表达式。 If unspecified, $convert returns null if the input is null or missing. 如果未指定，如果输入为null或缺少，$convert将返回null。

In addition to $convert, MongoDB provides the following aggregation operators as shorthand when the default "onError" and "onNull" behavior is acceptable:除了$convert之外，当默认的“onError”和“onNull”行为可以接受时，MongoDB还提供了以下聚合运算符作为简写：

• $toBool
• $toDate
• $toDecimal
• $toDouble
• $toInt
• $toLong
• $toObjectId
• $toString

Behavior行为

{ input: true, to: "bool" }

{ input: false, to: "bool" }

{ input: 1.99999, to: "bool" }

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

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

{ input: 100, to: "bool" }

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

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

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

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

{ input: null, to: "bool" }

{ 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" }

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

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

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

{ input: null, to: "int" }

{ input: true, to: "decimal" }

{ input: false, to: "decimal" }

{ input: 2.5, to: "decimal" }

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

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

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

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

{ input: true, to: "double" }

{ input: false, to: "double" }

{ input: 2.5, to: "double" }

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

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

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

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

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

{ input: true, to: "long" }

{ input: false, to: "long"  }

{ input: 2.5, to: "long"  }

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

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

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

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

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

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

{ input: null, to: "long" }

{
   input: 120000000000.5,
   to: "date"
}

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

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

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

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

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

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

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

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

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

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

{ input: true, to: "string" }

{ input: false, to: "string" }

{ input: 2.5, to: "string" }

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

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

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

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

Example实例

Create a collection orders with the following documents:使用以下文档创建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") }
] )

The following aggregation operation on the orders collection converts the price to a decimal: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
])

The operation returns the following documents:该操作返回以下文档：

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