/ /

$convert (expression operator)

Definition

$convert: Converts a value to a specified type.

Compatibility

You can use $convert for deployments hosted in the following environments:

MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

MongoDB Enterprise: The subscription-based, self-managed version of MongoDB
MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB

Syntax

Changed in version 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 takes a document with the following fields:

Field

Necessity

Description

input

Required

The argument can be any valid expression. For more information on expressions, see Expressions.

Starting in MongoDB 8.1, you can set the to field to binData if you set the input field to one of the following types:

int
long
double

Starting in MongoDB 8.3, you can also set the to field to binData if the input field is an array of numeric values. For examples, see Convert an Array of Numeric Values to binData.

MongoDB also supports these numeric types as input when converting a value to binData.

to

Required

Specifies the type to convert the input expression to. You can set to to one of these values:

A string or numeric identifier for the target type. See to.type.
An object containing the fields to.type and to.subtype. Use this format to convert to binData and specify a binData subtype.

to.type

Required if specifying to as an object

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 Convert to Double.
"string"	2	For more information on the conversion to string, see Convert to String.
"object"	3	For more information on the conversion to an object, see Convert to Object.
"array"	4	For more information on the conversion to an array, see Convert to Array.
"binData"	5	For more information on the conversion to binData, see Convert to BinData.
"objectId"	7	For more information on the conversion to objectId, see Convert to ObjectId.
"bool"	8	For more information on the conversion to boolean, see Convert to Boolean.
"date"	9	For more information on the conversion to date, see Convert to Date.
"int"	16	For more information on the conversion to integer, see Convert to Integer.
"long"	18	For more information on the conversion to long, see Convert to Long.
"decimal"	19	For more information on the conversion to decimal, see Convert to Decimal.

to.subtype

Optional

If to.type is binData, to.subtype specifies the binData subtype to convert to. You can specify one of these values for to.subtype:

Number	Description
0	Generic binary subtype
1	Function data
2	Binary (old)
3	UUID (old)
4	UUID
5	MD5
6	Encrypted BSON value
7	Compressed time series data New in version 5.2.
8	Sensitive data, such as a key or secret. MongoDB does not log literal values for binary data with subtype 8. Instead, MongoDB logs a placeholder value of `###`.
9	Vector data, which is densely packed arrays of numbers of the same type.
128	Custom data

Default: 0 (Generic binary subtype)

byteOrder

Optional

Specifies big or little endian byte ordering for conversions between binData and numeric types. If unspecified, the default is little endian byte ordering.

base

Optional

Integer base for conversions between string and numeric types.

If null, $convert behaves as if you omitted base.
If specified, MongoDB interprets the value in the chosen base when converting between strings and the numeric types int, long, double, and decimal. For other conversions, MongoDB validates the value of base but otherwise ignores it.
Base must be 2, 8, 10, or 16.

New in version 8.3.

format

Required when converting to or from binData and string

Specifies format of conversions between binData and string

base64
base64url
utf8
hex
uuid

If format is uuid, to.subtype must be 4.

onError

Optional

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

Value to return if the input is null or missing. The arguments can be any valid expression.

If unspecified, $convert returns null if the input is null or missing.

In addition to $convert, MongoDB provides the following aggregation operators as shorthand when the default "onError" and "onNull" behavior is acceptable:

Behavior

The following sections describe how to convert values to different types.

Convert to BinData

Starting in MongoDB 8.1, you can set the to field to binData if you set the input field to one of the following types:

int
long
double

Starting in MongoDB 8.1, $convert returns an error when attempting to convert between different binData subtypes. In MongoDB 8.0, $convert returns the original value and original subtype: no conversion is performed. MongoDB versions before 8.0 don't have binData conversion.

Convert from numeric types to `binData`:

When converting a numeric type to binData:

An int becomes a 4-byte binData.
A long becomes an 8-byte binData.
A double becomes an 8-byte binData.

The byteOrder of the numeric output defaults to "little", or the placement of the least significant byte first. In contrast, "big" places the most significant byte first.

Convert long to binData:

Input:

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

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

Output:

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

Convert long to binData with big-endian byte ordering:

Input:

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

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

Output:

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

Convert double to binData:

Input:

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

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

Output:

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

Convert int to binData:

Input:

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

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

Output:

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

Convert an array of numeric values to binData:

This example shows how $convert converts arrays containing different types of numeric values into binData.

Input:

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

Output:

[
  {
    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 ]))
  }
]

Convert from string to BinData

MongoDB also supports conversions between binData and strings.

The following examples demonstrate how to convert strings to binData.

Example

Result

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

Note

Convert to Array

New in version 8.3.

The following table lists the input types that can be converted to an array:

Input Type	Behavior
binData	Returns an array of numeric values. The numeric type of the array elements depends on the binData format.
String	Returns an array corresponding to the content within the string. The string must contain characters that represent a valid JSON array.
Null or Missing	Returns null.

The following table lists some conversion of string to array examples:

Example

Results

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

[ 1, 2, 3 ]

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

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

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

[ ]

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

Error: Input doesn't match expected type 'array'

{ input: 123, to: "array" }

Error: Unsupported conversion from int to array in $convert with no onError value

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

Error: Input doesn't represent valid JSON: Unexpected standalone value

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

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

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

[ 1, 2, 3 ]

Note

The format option is ignored.

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

'on error!'

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

'on null!'

Convert binData to Array

This example shows how $convert converts binData of different formats into arrays containing values of their respective types:

Input:

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

Output:

[
  { 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 ]
  }
]

Convert to Object

New in version 8.3.

The following table lists the input types that can be converted to an object:

Input Type	Behavior
String	Returns a document corresponding to the content within the string. The string must contain characters that represent a valid JSON object.
Null or Missing	Returns null.

The following table lists some conversion to object examples:

Example

Results

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

{ a: 1, b: 2 }

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

{ }

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

Error: Input doesn't match expected type 'object'

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

Error: Input doesn't represent valid JSON: Unexpected standalone value

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

Error: Input doesn't represent valid JSON: Illegal embedded null byte

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

}

Convert to Boolean

The following table lists the input types that can be converted to a boolean:

Input Type	Behavior
Array	Returns true
Binary data	Returns true
Boolean	No-op. Returns the boolean value.
Code	Returns true
Date	Returns true
Decimal	Returns true if not zero Return false if zero
Double	Returns true if not zero Return false if zero
Integer	Returns true if not zero Return false if zero
JavaScript	Returns true
Long	Returns true if not zero Return false if zero
MaxKey	Returns true
MinKey	Returns true
Null	Returns the value specified for the `onNull` option. By default, returns null.
Object	Returns true
ObjectId	Returns true
Regular expression	Returns true
String	Returns true
Timestamp	Returns true

To learn more about data types in MongoDB, see BSON Types.

The following table lists some conversion to boolean examples:

Example

Results

{ 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

Convert to Integer

The following table lists the input types that can be converted to an integer:

Input Type	Behavior
Boolean	Returns `0` for `false`. Returns `1` for `true`.
BinData	Returns the `binData` value as an integer. `binData` is interpreted as two's signed complement signed integer. The number of bytes in the `binData` value must be `1`, `2`, or `4`. If the `input` is of an unexpected length an error is generated. You can control this behavior by configuring `$convert.onError`.
Double	Returns truncated value. The truncated double value must fall within the minimum and maximum value for an integer. You cannot convert a double value whose truncated value is less than the minimum integer value or is greater than the maximum integer value.
Decimal	Returns truncated value. The truncated decimal value must fall within the minimum and maximum value for an integer. You cannot convert a decimal value whose truncated value is less than the minimum integer value or is greater than the maximum integer value.
Integer	No-op. Returns the integer value.
Long	Returns the long value as an integer. The long value must fall within the minimum and maximum value for an integer. You cannot convert a long value that is less than the minimum integer value or is greater than the maximum integer value.
String	Returns the numerical value of the string as an integer. If you omit `base` or set to `null`, the string value must be a valid base ₁₀ integer and fall within the minimum and maximum value for an integer. If you specify `base`, the string must only contain digits valid in that base. Prefixes, such as `"0x"`, are not allowed. The resulting integer must be within the minimum and maximum value for an integer.

The following table lists some conversion to integer examples:

Example

Results

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

Error

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

5000

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

Error

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

-2

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

Error

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

Error: Failed to convert BinData because of invalid length: 7

Convert to Decimal

The following table lists the input types that can be converted to a decimal:

Input Type	Behavior
Boolean	Returns `Decimal128( "0" )` for `false`. Returns `Decimal128( "1" )` for `true`.
Double	Returns double value as a decimal.
Decimal	No-op. Returns the decimal.
Integer	Returns the int value as a decimal.
Long	Returns the long value as a decimal.
String	Returns the numerical value of the string as a decimal. If you omit `base` or set to `null`, the string value must be a valid base ₁₀ decimal and fall within the minimum and maximum value for a decimal. If you specify `base`, the string must only contain digits valid in that base. Prefixes, such as `"0x"`, are not allowed. The resulting decimal must be within the minimum and maximum value for a decimal.
Date	Returns the number of milliseconds since the epoch that corresponds to the date value.

The following table lists some conversion to decimal examples:

Example

Results

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

Convert to Double

The following table lists the input types that can be converted to a double:

Input Type	Behavior
Boolean	Returns NumberDouble(0) for `false`. Returns NumberDouble(1) for `true`.
BinData	Returns the `binData` value as a double. `binData` is interpreted as an IEEE 754 single-precision or double-precision floating point. The number of bytes in the `binData` value must be `4` or `8`. If the `input` is of an unexpected length an error is generated. You can control this behavior by configuring `$convert.onError`.
Double	No-op. Returns the double.
Decimal	Returns the decimal value as a double. The decimal value must fall within the minimum and maximum value for a double. You cannot convert a decimal value whose value is less than the minimum double value or is greater than the maximum double value.
Integer	Returns the int value as a double.
Long	Returns the long value as a double.
String	Returns the numerical value of the string as a double. If you omit `base` or set to `null`, the string value must be a valid base ₁₀ double and fall within the minimum and maximum value for a double. If you specify `base`, the string must only contain digits valid in that base. Prefixes, such as `"0x"`, are not allowed. The resulting double must be within the minimum and maximum value for a double.
Date	Returns the number of milliseconds since the epoch that corresponds to the date value.

The following table lists some conversion to double examples:

Example

Results

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

Error: Failed to convert binData because of invalid length: 2

Subnormal Numbers

Starting in MongoDB 8.3, the server is able to parse the full range of all representable double precision floating point numbers. This includes subnormal numbers where the most significant digit has leading zeroes and the exponent has the least possible value. For details, see Subnormal Number.

In earlier versions of MongoDB, the server returns an error when you try to parse these numbers. The following example raises an error in versions earlier than MongoDB 8.3:

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

This example fails with an error similar to the following:

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

Convert to Long

The following table lists the input types that can be converted to a long:

Input Type	Behavior
Boolean	Returns `0` for `false`. Returns `1` for `true`.
BinData	Returns the `binData` value as a long. `binData` is interpreted as two's signed complement signed integer. The number of bytes in the `binData` value must be `1`, `2`, `4` or `8`. If the `input` is of an unexpected length an error is generated. You can control this behavior by configuring `$convert.onError`.
Double	Returns truncated value. The truncated double value must fall within the minimum and maximum value for a long. You cannot convert a double value whose truncated value is less than the minimum long value or is greater than the maximum long value.
Decimal	Returns truncated value. The truncated decimal value must fall within the minimum and maximum value for a long. You cannot convert a decimal value whose truncated value is less than the minimum long value or is greater than the maximum long value.
Integer	Returns the int value as a long.
Long	No-op. Returns the long value.
String	Returns the numerical value of the string. If you omit `base` or set to `null`, the string value must be a valid base ₁₀ long and fall within the minimum and maximum value for a long. If you specify `base`, the string must only contain digits valid in that base. Prefixes, such as `"0x"`, are not allowed. The resulting long must be within the minimum and maximum value for a long.
Date	Converts the Date into the number of milliseconds since the epoch.

The following table lists some conversion to long examples:

Example

Results

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

Error

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

Error

{ input: null, to: "long" }

null

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

Long("1048576")

Convert to Date

The following table lists the input types that can be converted to a date:

Input Type	Behavior
Double	Returns a date that corresponds to the number of milliseconds represented by the truncated double value. Positive number corresponds to the number of milliseconds since Jan 1, 1970. Negative number corresponds to the number of milliseconds before Jan 1, 1970.
Decimal	Returns a date that corresponds to the number of milliseconds represented by the truncated decimal value. Positive number corresponds to the number of milliseconds since Jan 1, 1970. Negative number corresponds to the number of milliseconds before Jan 1, 1970.
Long	Returns a date that corresponds to the number of milliseconds represented by the long value. Positive number corresponds to the number of milliseconds since Jan 1, 1970. Negative number corresponds to the number of milliseconds before Jan 1, 1970.
String	Returns a date that corresponds to the date string. The string must be a valid date string, such as: "2018-03-03" "2018-03-03T12:00:00Z" "2018-03-03T12:00:00+0500"
ObjectId	Returns a date that corresponds to the timestamp of the ObjectId.
Timestamp	Returns a date that corresponds to the timestamp.

The following table lists some conversion to date examples:

Example

Results

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

Error

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

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

Convert to ObjectId

The following table lists the input types that can be converted to an ObjectId:

Input Type	Behavior
String	Returns an ObjectId for the hexadecimal string of length 24. You cannot convert a string value that is not a hexadecimal string of length 24.

The following table lists some conversion to date examples:

Example

Results

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

ObjectId("5ab9cbfa31c2ab715d42129e")

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

Error

Convert to String

The following table lists the input types that can be converted to a string:

Input Type	Behavior
Array	Returns the `Array` as a string. New in version 8.3.
BinData	If the `BinData` is a UUID, returns the UUID as a string. Otherwise, returns the base64 encoded string value.
Boolean	Returns the Boolean value as a string.
Date	Returns the `Date` as a string.
Decimal	Returns the `Decimal` value as a string.
Double	Returns the `Double` value as a string.
Integer	Returns the `Integer` value as a string.
Long	Returns the `Long` value as a string.
MaxKey	Returns the `MaxKey` as a string. New in version 8.3.
MinKey	Returns the `MinKey` as a string. New in version 8.3.
Object	Returns the object as a string. New in version 8.3.
ObjectId	Returns the `ObjectId` value as a hexadecimal string.
Regular Expression	Returns the `Regular Expression` as a string. New in version 8.3.
String	No operation. Returns the string value.
Timestamp	Returns the `Timestamp` as a string. New in version 8.3.

Note

When you specify base and the input is a numeric type, $convert returns the string representation of the integer value in that base. Base conversion for strings is only supported for integer values, otherwise $convert returns a conversion error unless you specify onError.

The following table lists some conversion to string examples:

Example

Results

{ 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

Base Conversion Example

Create a collection examples with a placeholder document:

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

The following example converts between numbers and strings using different bases:

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 } }
    }
  }
])

This operation returns the following document:

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

Type Conversion Example

Create a collection orders with the following documents:

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:

// 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' }

Note

These examples use mongosh. The default types are different in the legacy mongo shell.

Learn More

Convert a value to an array with $toArray
Convert a string to an object with $toObject
Convert a value to a boolean with $toBool
Convert a value to an integer with $toInt
Convert a value to a decimal with $toDecimal
Convert a value to a double with $toDouble
Convert a value to a long with $toLong
Convert a value to a date with $toDate
Convert a value to an ObjectId with $toObjectId
Convert a value to a string with $toString
Convert a date string to a date object with $dateFromString
Convert a date object to a string with $dateToString

Back

$cond

$cos

Definition

Compatibility

Syntax

Behavior

Convert to BinData

Convert from numeric types to binData:

Convert from string to BinData

Note

Convert to Array

Note

Convert binData to Array

Convert to Object

Convert to Boolean

Convert to Integer

Convert to Decimal

Convert to Double

Subnormal Numbers

Convert to Long

Convert to Date

Convert to ObjectId

Convert to String

Note

Examples

Base Conversion Example

Type Conversion Example

Note

Learn More

Convert from numeric types to `binData`: