/ /

$convert (operador de expresión)

Definición

$convert: Convierte un valor a un tipo especificado.

Compatibilidad

Puedes usar $convert para implementaciones alojadas en los siguientes entornos:

MongoDB Atlas: El servicio totalmente gestionado para implementaciones de MongoDB en la nube

MongoDB Enterprise: La versión basada en suscripción y autogestionada de MongoDB
MongoDB Community: La versión de MongoDB con código fuente disponible, de uso gratuito y autogestionada.

Sintaxis

Cambiado en la versión 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 toma un documento con los siguientes campos:

Campo

Necesidad

Descripción

input

Requerido

El argumento puede ser cualquier expresión válida. Para obtener más información sobre las expresiones, consulta Expresiones.

A partir de MongoDB 8.1, puedes configurar el campo to como binData si configuras el campo input como uno de los siguientes tipos:

int
long
double

A partir de MongoDB,8.3 también puede establecer el to campo en binData si el input campo es un array de valores numéricos. Para ver ejemplos, consulte Convertir una matriz de valores numéricos a binData.

MongoDB también admite estos tipos numéricos como entrada al convertir un valor a binData.

to

Requerido

Especificar el tipo al que se va a convertir la expresión input. Se puede establecer to en uno de estos valores:

Un identificador de tipo de destino, ya sea de string o numérico. Consulte to.type.
Un objeto que contiene los campos to.type y to.subtype. Utiliza este formato para convertir a binData y especificar un subtipo binData.

to.type

Obligatorio si se especifica to como objeto

El argumento puede ser cualquier expresión válida que se resuelva en uno de los siguientes identificadores numéricos o de string:

Identificador de string	Identificador númerico	notas
"double"	1	Para obtener más información sobre la conversión a double, consulta Convertir a Double.
"string"	2	Para obtener más información sobre la conversión a string, ver Convertir a string.
"objeto"	3	Para obtener más información sobre la conversión a un objeto, consulte Convertir a objeto.
"arreglo"	4	Para obtener más información sobre la conversión a una matriz, consulte Convertir a matriz.
"binData"	5	Para obtener más información sobre la conversión a binData, consulta Convertir a BinData.
"objectId"	7	Si desea obtener más información sobre la conversión a objectId, consulte Convertir a ObjectId.
"bool"	8	Para obtener más información sobre la conversión a booleano, consulte Convertir a booleano.
"date"	9	Para más información sobre la conversión a fecha, consulta Convertir a fecha.
"int"	16	Para obtener más información sobre la conversión a entero, consulte Convertir a entero.
"long"	18	Para obtener más información sobre la conversión a long, consulte la sección Convertir a Long.
"Decimal"	19	Para obtener más información sobre la conversión a decimal, consulta Convertir a decimal.

to.subtype

Opcional

Si to.type es binData, to.subtype especifica el subtipo binData al que se debe convertir. Puedes especificar uno de estos valores para to.subtype:

Número	Descripción
0	Subtipo binario genérico
1	Datos de funciones
2	Binario (antiguo)
3	UUID (antiguo)
4	UUID
5	md5
6	Valor BSON cifrado
7	Datos de series de tiempo comprimidos Nuevo en la versión 5.2.
8	Datos sensibles, como una clave o un secreto. MongoDB no registra valores literales para datos binarios con subtipo 8. En cambio, MongoDB registra un valor de marcador de posición de `###`.
9	Datos vectoriales, que son arreglos densamente empaquetados de números del mismo tipo.
128	Datos personalizados

Por defecto: 0 (Subtipo binario genérico)

byteOrder

Opcional

Especifica el orden en bytes little-endian o big-endian para las conversiones entre los tipos binData y numéricos. Si no se especifica, el orden por defecto es bytes little-endian.

base

Opcional

Base entera para conversiones entre tipos de cadena y numéricos.

nullSi, se comporta como si se hubiera omitido la$convert base.
Si se especifica, MongoDB interpreta el valor en la base elegida al convertir entre cadenas y los tipos numéricos int, long, double y decimal. Para otras conversiones, MongoDB valida el valor de base, pero lo ignora en caso contrario.
La base debe ser 2, 8, 10 o 16.

Nuevo en la versión 8.3.

format

Requerido al convertir de binData o a string

Especifica el formato de las conversiones entre binData y la cadena

base64
base64url
utf8
hex
uuid

Si format es uuid, to.subtype debe ser 4.

onError

Opcional

Valor que se devuelve al encontrar un error durante la conversión, incluyendo conversiones de tipos no soportados. Los argumentos pueden ser cualquier expresión válida.

Si no se especifica, la operación arroja un error al encontrar un error y se detiene.

onNull

Opcional

Valor que se debe devolver si el input es nulo o se encuentra ausente. Los argumentos pueden ser cualquier expresión.

Si no se especifica, $convert devuelve nulo si input está nulo o no está presente.

Además de $convert, MongoDB proporciona los siguientes operadores de agregación como atajo cuando el comportamiento por defecto "onError" y "onNull" es aceptable:

Comportamiento

Las siguientes secciones describen cómo convertir valores a diferentes tipos.

Convertir a BinData

A partir de MongoDB 8.1, puedes configurar el campo to como binData si configuras el campo input como uno de los siguientes tipos:

int
long
double

A partir de MongoDB 8.1, $convert devuelve un error al intentar convertir entre diferentes subtipos de binData. En MongoDB 8.0, $convert devuelve el valor original y el subtipo original: no se realiza ninguna conversión. Las versiones de MongoDB anteriores a la 8.0 no realizan conversión de binData.

Convertir de tipos numéricos a `binData`:

Al convertir un tipo numérico a binData:

Un int se convierte en un binData de 4bytes.
Un long se convierte en un 8-byte binData.
Un double se convierte en un 8-byte binData.

El byteOrder de la salida numérica por defecto es "little" o la colocación del byte menos significativo primero. Por el contrario, "big" coloca el byte más significativo en primer lugar.

Convertir long a binData:

Entrada:

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

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

Producción:

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

Convierte long a binData con ordenación de bytes big-endian:

Entrada:

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

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

Producción:

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

Convertir double a binData:

Entrada:

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

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

Producción:

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

Convertir int a binData:

Entrada:

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

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

Producción:

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

Convierte una matriz de valores numéricos a binData:

Este ejemplo muestra cómo $convert convierte matrices que contienen diferentes tipos de valores numéricos en binData.

Entrada:

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

Producción:

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

Convertir de string a BinData

MongoDB también admite conversiones entre binData y cadenas de texto.

Los siguientes ejemplos demuestran cómo convertir strings a binData.

Ejemplo

Resultado

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

Nota

Convertir a matriz

Nuevo en la versión 8.3.

La siguiente tabla enumera los tipos de entrada que se pueden convertir en una matriz:

Tipo de entrada	Comportamiento
binData	Devuelve una matriz de valores numéricos. El tipo numérico de los elementos de la matriz depende del formato binData.
String	Devuelve una matriz que corresponde al contenido de la cadena. La cadena debe contener caracteres que representen una matriz JSON válida.
Nulo o faltante	Devuelve nulo.

La siguiente tabla muestra algunos ejemplos de conversión de cadena a matriz:

Ejemplo

Resultados

{ 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: La entrada no coincide con el tipo esperado 'array'.

{ input: 123, to: "array" }

Error: Conversión no compatible de entero a matriz en $convert sin valor onError

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

Error: La entrada no representa un JSON válido: Valor independiente inesperado

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

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

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

[ 1, 2, 3 ]

Nota

La opción format se ignora.

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

'on error!'

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

'on null!'

Convertir binData a matriz

Este ejemplo muestra cómo $convert convierte binData de diferentes formatos en matrices que contienen valores de sus respectivos tipos:

Aporte:

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

Producción:

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

Convertir a objeto

Nuevo en la versión 8.3.

La siguiente tabla enumera los tipos de entrada que se pueden convertir en un objeto:

Tipo de entrada	Comportamiento
String	Devuelve un documento que corresponde al contenido de la cadena. La cadena debe contener caracteres que representen un objeto JSON válido.
Nulo o faltante	Devuelve nulo.

La siguiente tabla enumera algunos ejemplos de conversión a objeto:

Ejemplo

Resultados

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

{ a: 1, b: 2 }

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

{ }

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

Error: La entrada no coincide con el tipo esperado 'object'.

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

Error: La entrada no representa un JSON válido: Valor independiente inesperado

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

Error: La entrada no representa un JSON válido: Byte nulo incrustado ilegal

{ input: "{\"name\": \"fo\\u0000o\"}", to: "object" }

{ nombre: '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" }

Nulo

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

}

Convertir a Booleano

La siguiente tabla enumera los tipos de entrada que pueden convertirse en booleanos:

Tipo de entrada	Comportamiento
Arreglo	Devuelve verdadero
Datos binarios	Devuelve verdadero
Booleano	Sin-op. Devuelve el valor booleano.
Código	Devuelve verdadero
fecha	Devuelve verdadero
Decimal	Returns true if not zero Return false if zero
Double	Returns true if not zero Return false if zero
entero	Returns true if not zero Return false if zero
JavaScript	Devuelve verdadero
Long	Returns true if not zero Return false if zero
Clave máxima	Devuelve verdadero
MinKey	Devuelve verdadero
Nulo	Devuelve el valor especificado para la opción `onNull`. Por defecto, devuelve null.
Objeto	Devuelve verdadero
ObjectId	Devuelve verdadero
Expresión regular	Devuelve verdadero
String	Devuelve verdadero
Marca de tiempo	Devuelve verdadero

Para obtener más información sobre los tipos de datos en MongoDB, consulta BSON Types.

En la siguiente tabla se enumeran algunos ejemplos de conversión a booleanos:

Ejemplo

Resultados

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

Nulo

Convertir a entero

La siguiente tabla enumera los tipos de entrada que se pueden convertir a un número entero:

Tipo de entrada	Comportamiento
Booleano	Returns `0` for `false`. Returns `1` for `true`.
BinData	Devuelve el valor `binData` como un entero. `binData` se interpreta como un entero con signo, complemento a dos. El número de bytes en el valor `binData` debe ser `1`, `2` o `4`. Si la `input` tiene una longitud inesperada, se genera un error. Puedes controlar este comportamiento configurando `$convert.onError`.
Double	Retorna un valor truncado. El valor double truncado debe estar dentro del valor mínimo y máximo para un número entero. No se puede convertir un valor double cuyo valor truncado sea inferior al valor entero mínimo o superior al valor entero máximo.
Decimal	Retorna un valor truncado. El valor decimal truncado debe encontrarse dentro del valor mínimo y máximo de un entero. No puedes convertir un valor decimal cuyo valor truncado sea menor que el valor entero mínimo o mayor que el valor entero máximo.
entero	Sin operación. Devuelve el valor entero.
Long	Devuelve el valor largo como un entero. El valor largo debe estar dentro del valor mínimo y máximo para un entero. No se puede convertir un valor largo que sea menor que el valor entero mínimo o mayor que el valor entero máximo.
String	Devuelve el valor numérico del string como un entero. Si omite `base` o `null` establece, el valor de la cadena debe ser un entero válido en base ₁₀ y estar dentro del valor mínimo y máximo para un entero. Si especifica `base`, la cadena solo debe contener dígitos válidos en esa base. No se permiten prefijos como `"0x"`. El número entero resultante debe estar dentro del rango de valores mínimo y máximo para un entero.

En la siguiente tabla se enumeran algunos ejemplos de conversión a enteros:

Ejemplo

Resultados

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

Nulo

{
   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: No se pudo convertir BinData debido a una longitud inválida: 7

Convertir a decimal

La siguiente tabla enumera los tipos de entrada que se pueden convertir a decimal:

Tipo de entrada	Comportamiento
Booleano	Returns `Decimal128( "0" )` for `false`. Returns `Decimal128( "1" )` for `true`.
Double	Devuelve el valor double como un decimal.
Decimal	Sin-op. Devuelve el decimal.
entero	Devuelve el valor int como decimal.
Long	Devuelve el valor largo como decimal.
String	Devuelve el valor numérico de la string como un número decimal. Si omite `base` o `null` establece, el valor de la cadena debe ser un ₁₀ decimal válido en base y estar dentro del valor mínimo y máximo para un decimal. Si especifica `base`, la cadena solo debe contener dígitos válidos en esa base. No se permiten prefijos como `"0x"`. El decimal resultante debe estar dentro del rango de valores mínimo y máximo para un decimal.
fecha	Devuelve la cantidad de milisegundos desde la Unix epoch que corresponde al valor de la fecha.

La siguiente tabla enumera algunos ejemplos de conversión a decimal:

Ejemplo

Resultados

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

Convertir a double

La siguiente tabla enumera los tipos de entrada que se pueden convertir a doble:

Tipo de entrada	Comportamiento
Booleano	Returns NumberDouble(0) for `false`. Returns NumberDouble(1) for `true`.
BinData	Retorna el valor `binData` como double. `binData` se interpreta como un número de punto flotante de precisión simple o doble IEEE 754. El número de bytes del valor `binData` debe ser `4` o `8`. Si la `input` tiene una longitud inesperada, se genera un error. Puedes controlar este comportamiento configurando `$convert.onError`.
Double	Sin operación. Devuelve el double.
Decimal	Devuelve el valor decimal como un double. El valor decimal debe estar dentro del valor mínimo y máximo para un double. No puedes convertir un valor decimal cuyo valor es menor que el valor double mínimo o mayor que el valor double máximo.
entero	Devuelve el valor int como un double.
Long	Devuelve el valor largo como un double.
String	Retorna el valor numérico de la string como un doble. Si omite `base` o `null` establece, el valor de la cadena debe ser un ₁₀ double válido en base y estar dentro del rango de valores mínimo y máximo para un double. Si especifica `base`, la cadena solo debe contener dígitos válidos en esa base. No se permiten prefijos como `"0x"`. El valor resultante de tipo double debe estar dentro del rango mínimo y máximo permitido para este tipo de dato.
fecha	Devuelve la cantidad de milisegundos desde la Unix epoch que corresponde al valor de la fecha.

La siguiente tabla enumera algunos ejemplos de conversión a doble:

Ejemplo

Resultados

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

50.000.000.000

{
   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: No se pudo convertir binData debido a una longitud inválida: 2

Números subnormales

A partir de 8.3 MongoDB, el servidor puede analizar todo el rango de números de coma flotante de doble precisión representables. Esto incluye números subnormales, donde el dígito más significativo tiene ceros iniciales y el exponente tiene el menor valor posible. Para obtener más información, consulte Números subnormales..

En versiones anteriores de MongoDB, el servidor devuelve un error al intentar analizar estos números. El siguiente ejemplo genera un error en versiones anteriores a MongoDB 8.3:

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

Este ejemplo falla con un error similar al siguiente:

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

Convertir a longitud

La siguiente tabla enumera los tipos de entrada que pueden convertirse a un "long":

Tipo de entrada	Comportamiento
Booleano	Returns `0` for `false`. Returns `1` for `true`.
BinData	Devuelve el valor `binData` como long. `binData` se interpreta como un entero con signo en complemento a dos. El número de bytes en el valor `binData` debe ser `1`, `2`, `4` o `8`. Si la `input` tiene una longitud inesperada, se genera un error. Puedes controlar este comportamiento configurando `$convert.onError`.
Double	Retorna un valor truncado. El valor double truncado debe estar dentro del valor mínimo y máximo para un largo. No se puede convertir un valor double cuyo valor truncado es inferior al valor mínimo de long o superior al valor máximo de long.
Decimal	Retorna un valor truncado. El valor decimal truncado debe estar dentro del valor mínimo y máximo para un entero largo. No puedes convertir un valor decimal cuyo valor truncado sea inferior al valor mínimo de long o supere el valor máximo de long.
entero	Devuelve el valor int como un long.
Long	No-op. Devuelve el valor long.
String	Devuelve el valor numérico de la string. Si omite `base` o `null` establece, el valor de la cadena debe ser un ₁₀ long base válido y estar dentro del valor mínimo y máximo para un long. Si especifica `base`, la cadena solo debe contener dígitos válidos en esa base. No se permiten prefijos como `"0x"`. El valor resultante debe estar dentro del rango mínimo y máximo permitido para un valor de tipo long.
fecha	Convierte la fecha en el número de milisegundos transcurridos desde la Unix epoch.

La siguiente tabla muestra algunos ejemplos de conversión a long:

Ejemplo

Resultados

{ input: true, to: "long" }

Long("1")

{ input: false, to: "long"  }

Long("0")

{ input: 2.5, to: "long"  }

Largo("2")

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

Prolongado ("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" }

large("-2")

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

Error

{ input: null, to: "long" }

Nulo

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

Long("1048576")

Convertir a Fecha

En la siguiente tabla se enumeran los tipos de datos que se pueden convertir en una fecha:

Tipo de entrada	Comportamiento
Double	Devuelve una fecha que corresponde al número de milisegundos representado por el valor double truncado. Un número positivo corresponde al número de milisegundos desde el 1 de enero de 1970. Un número negativo corresponde al número de milisegundos anteriores al 1 de enero de 1970.
Decimal	Devuelve una fecha que corresponde al número de milisegundos representado por el valor decimal truncado. Un número positivo corresponde al número de milisegundos desde el 1 de enero de 1970. Un número negativo corresponde al número de milisegundos anteriores al 1 de enero de 1970.
Long	Devuelve una fecha que corresponde al número de milisegundos representados por el valor long. Un número positivo corresponde al número de milisegundos desde el 1 de enero de 1970. Un número negativo corresponde al número de milisegundos anteriores al 1 de enero de 1970.
String	Devuelve una fecha que corresponde a la string de fecha. La string debe ser una string de fecha válida, como: "2018-03-03" "2018-03-03T12:00:00Z" "2018-03-03T12:00:00+0500"
ObjectId	Devuelve una fecha que corresponde a la marca de tiempo del ObjectId.
Marca de tiempo	Devuelve una fecha que corresponde a la marca de tiempo.

La siguiente tabla enumera algunos ejemplos de conversión a fecha:

Ejemplo

Resultados

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

Convertir a ObjectId

La siguiente tabla enumera los tipos de entrada que se pueden convertir en un ObjectId:

Tipo de entrada	Comportamiento
String	Devuelve un ObjectId para la string hexadecimal de 24 caracteres. No puedes convertir un valor de string que no sea una string hexadecimal de longitud 24.

La siguiente tabla enumera algunos ejemplos de conversión a fecha:

Ejemplo

Resultados

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

ObjectId("5ab9cbfa31c2ab715d42129e")

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

Error

Convertir a string

La siguiente tabla enumera los tipos de entrada que se pueden convertir en una string:

Tipo de entrada	Comportamiento
Arreglo	Devuelve el como una `Array` cadena. Nuevo en la versión 8.3.
BinData	Si el `BinData` es un UUID, se devuelve el UUID como un string. De lo contrario, devuelve el valor de string codificada en base64.
Booleano	Devuelve el valor booleano como una cadena de texto.
fecha	Devuelve el como una `Date` cadena.
Decimal	Devuelve el valor como una `Decimal` cadena.
Double	Devuelve el valor como una `Double` cadena.
entero	Devuelve el valor como una `Integer` cadena.
Long	Devuelve el valor como una `Long` cadena.
Clave máxima	Devuelve el como una `MaxKey` cadena. Nuevo en la versión 8.3.
MinKey	Devuelve el como una `MinKey` cadena. Nuevo en la versión 8.3.
Objeto	Devuelve el objeto como una cadena de texto. Nuevo en la versión 8.3.
ObjectId	Devuelve el valor como una cadena `ObjectId` hexadecimal.
Expresión regular	Devuelve el como una `Regular Expression` cadena. Nuevo en la versión 8.3.
String	No realiza ninguna operación. Devuelve el valor de la cadena.
Marca de tiempo	Devuelve el como una `Timestamp` cadena. Nuevo en la versión 8.3.

Nota

Cuando se especifica base y input es un tipo numérico, $convert devuelve la representación en cadena del valor entero en esa base. La conversión de base para cadenas solo es compatible con valores enteros; de lo $convert contrario, devuelve un error de conversión a menos que se onError especifique.

La siguiente tabla enumera algunos ejemplos de conversión a string:

Ejemplo

Resultados

{ input: true, to: "string" }

"true"

{ input: false, to: "string" }

"falso"

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

Ejemplos

Ejemplo de conversión de base

Crea una colección examples con un documento de marcador de posición:

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

El siguiente ejemplo realiza conversiones entre números y cadenas de texto utilizando diferentes 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 } }
    }
  }
])

Esta operación devuelve el siguiente documento:

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

Ejemplo de conversión de tipo

Cree una colección orders con los siguientes documentos:

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

La siguiente operación de agregación en la colección orders convierte el price en 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
])

La operación devuelve los siguientes documentos:

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

Nota

Estos ejemplos utilizan mongosh. Los tipos por defecto son diferentes en la shell heredada mongo.

Obtén más información

Convierta un valor en una matriz con $toArray
Convierta una cadena en un objeto con $toObject
Convierta un valor a un booleano con $toBool
Convierta un valor a un entero con $toInt
Convierta un valor a decimal con $toDecimal
Convierta un valor a un double con $toDouble
Convertir un valor a un long con $toLong
Convierta un valor en una fecha con $toDate
Convierta un valor en un ObjectId con $toObjectId
Convierta un valor en una cadena con $toString
Convierta una cadena de fecha en un objeto de fecha con $dateFromString
Convierta un objeto de fecha en una cadena con $dateToString

Volver

$cond

$cos

Definición

Compatibilidad

Sintaxis

Comportamiento

Convertir a BinData

Convertir de tipos numéricos a binData:

Convertir de string a BinData

Nota

Convertir a matriz

Nota

Convertir binData a matriz

Convertir a objeto

Convertir a Booleano

Convertir a entero

Convertir a decimal

Convertir a double

Números subnormales

Convertir a longitud

Convertir a Fecha

Convertir a ObjectId

Convertir a string

Nota

Ejemplos

Ejemplo de conversión de base

Ejemplo de conversión de tipo

Nota

Obtén más información

Convertir de tipos numéricos a `binData`: