$convert（式演算子）

定義

$convert: 値を指定した型に変換します。

互換性

次の環境でホストされる配置には $convert を使用できます。

MongoDB Atlas はクラウドでの MongoDB 配置のためのフルマネージドサービスです

MongoDB Enterprise: サブスクリプションベースの自己管理型 MongoDB バージョン
MongoDB Community: ソースが利用可能で、無料で使用できる自己管理型の MongoDB のバージョン

構文

バージョン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 次のフィールドが含まれるドキュメントについて、

フィールド	必要性	説明
`input`	必須	引数には任意の有効な式を使用できます。式の詳細については、「式」を参照してください。 MongoDB 8.1 以降では、`input`フィールドを次のいずれかのタイプに設定すると、`to`フィールドを `binData` に設定できます。 `int` `long` `double` MongoDB 8.3以降では、`input`フィールドが数値の`array`である場合、`to`フィールドを`binData`に設定することもできます。例については、「数値の配列を binData に変換する」を参照してください。 MongoDB は、値を `binData` に変換するときに、入力としてこれらの数値型もサポートしています。 MongoDB 9.0以降では、`input`フィールドがオブジェクトに解決される場合、`to`フィールドを`binData`に設定できます。例については、オブジェクトをbinDataに変換するを参照してください。
`to`	必須	`input` 式を変換する型を指定します。`to` を次のいずれかの値に設定できます。ターゲット型の文字列または数値識別子。`to.type` を参照してください。 `to.type` と `to.subtype` フィールドを含むオブジェクト。この形式を使用して `binData` に変換し、`binData` サブタイプを指定します。
`to.type`	オブジェクトとして `to` を指定する場合は必須です	引数は、数値識別子または string 識別子に解決される有効な式であればどれでもかまいません。利用可能な識別子については、型識別子を参照してください。
`to.subtype`	任意	`to.type` が`binData` の場合、`to.subtype` が変換する binData サブタイプを指定します。有効な値については、バイナリサブタイプを参照してください。デフォルト: 0 (汎用バイナリのサブタイプ)。
`byteOrder`	任意	`binData` と数値型の間の変換に対してビッグエンディアンバイトまたはリトルエンディアンバイトの順序付けを指定します。指定しない場合、デフォルトはリトルエンディアンバイト順になります。
`base`	任意	string 型と数値型間の変換の整数基数。 `null` の場合、`$convert` は base を省略したかのように動作します。指定すると、 MongoDB は、string と数値型 `int`、`long`、`double`、`decimal` の間で変換するときに、選択した基数の値を解釈します。その他の変換では、 MongoDB は`base` の値を検証しますが、それ以外の場合は無視します。ベースは、`2`、`8`、`10`、または `16` である必要があります。バージョン8.3の新機能。
`format`	`binData` と string にまたはから変換するときに必要です	`binData` と string の間の変換の形式を指定します `base64` `base64url` `utf8` `hex` `uuid` `format` が`uuid` の場合、`to.subtype` は`4` である必要があります。
`onError`	任意	変換中にエラーが発生した場合に返される値。サポートされていない型の変換などが含まれます。引数には任意の有効な式を使用できます。指定されていない場合、エラーが発生すると操作はエラーをスローし、停止します。
`onNull`	任意	`input` がNULLまたは見つからない場合に返す値。引数には任意の有効な式を使用できます。指定されていない場合、`input` が null または欠落していれば、`$convert` は null を返します。

$convertに加えて、MongoDB は、デフォルトの "onError" および "onNull" の動作が受け入れられる場合、省略形として次の集計演算子を提供します。

タイプ識別子

to.typeフィールドは、次の数値識別子と string 識別子を受け入れます。

文字列識別子	数値識別子	ノート
"double"	1	詳細については、double への変換を参照してください。
"string"	2	「String への変換」を参照してください。
"object"	3	オブジェクトへの変換を参照してください。
"array"	4	「配列へ変換」を参照してください。
"binData"	5	BinData への変換を参照してください。
"objectId"	7	ObjectId への変換を参照してください。
"bool"	8	「ブール値に変換」を参照してください。
"date"	9	「日付に変換」を参照してください。
"int"	16	整数への変換を参照してください。
"long"	18	「Long への変換」を参照してください。
"decimal"	19	「10 進数に変換」を参照してください。

バイナリサブタイプ

次の表に、to.subtype フィールドの有効な値を示します。

番号	説明
0	汎用バイナリのサブタイプ
1	関数データ
2	バイナリ（旧）
3	UUID（旧）
4	UUID
5	MD5
6	暗号化された BSON 値
7	圧縮された時系列データバージョン5.2の新機能。
8	キーやシークレットなどの機密データ。 MongoDB では、サブタイプ 8 のバイナリデータのリテラル値はログに記録されません。代わりに、MongoDB は`###`のプレースホルダー値をログに記録します。
9	ベクトルデータとは、同じ型の数値が高密度に圧縮された配列です。
128	カスタムデータ

動作

次のセクションでは、値を別の型に変換する方法について説明します。

BinData への変換

MongoDB 8.1 以降では、inputフィールドを次のいずれかのタイプに設定すると、toフィールドを binData に設定できます。

int
long
double

MongoDB 8.1 以降では、異なる binData サブタイプ間で変換を試みると、$convert はエラーを返します。MongoDB 8.0 では、$convert は元の値と元のサブタイプを返します。変換は実行されません。8.0 より前のMongoDBバージョンには binData 変換はありません。

数値型から `binData` に変換する:

数値型を binData に変換する場合:

int は 4 バイトの binData になります。
long は 8 バイトの binData になります。
double は 8 バイトの binData になります。

数値出力の byteOrder はデフォルトで "リトル" 、つまり最下位バイトが先の配置になります。対照的に、"big" は最上位バイトを先頭に配置します。

long を binData に変換する:

入力:

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

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

出力:

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

ビッグエンディアンバイト順で long を binData に変換する:

入力:

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

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

出力:

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

double を binData に変換する:

入力:

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

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

出力:

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

int を binData に変換する:

入力:

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

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

出力:

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

数値の配列を binData に変換する:

この例では、$convert がさまざまなタイプの数値を含む配列を binData に変換する方法を示しています。

入力:

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

出力:

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

オブジェクトを変換します。 `binData`

バージョン9.0の新機能。

input フィールドがオブジェクトに解決され、to フィールドが binData である場合、$convert はオブジェクトの生の BSON 表現を返します。to.subtype で別の値を指定しない限り、返される binData 値のサブタイプは 0 になります。

出力はオブジェクトの生のBSONであるため、オブジェクトのフィールドの順序と配列内の要素の順序の両方が、返されるバイトに影響します。

$convert この変換のために format、byteOrder、および base フィールドを検証しますが、これらのフィールドは出力には影響しません。

次の表は、オブジェクトから binData への変換の例を示しています。

例	結果
`{ input: {}, to: "binData" }`	`Binary.createFromBase64('BQAAAAA=', 0)`
`{ input: { a: "hello", b: { x: NumberInt(42), y: [NumberInt(1), NumberInt(2), NumberInt(3)] }, c: BinData(0, "AQIDBA==") }, to: "binData"}`	`Binary.createFromBase64('SgAAAAJhAAYAAABoZWxsbwADYgApAAAAEHgAKgAAAAR5ABoAAAAQMAABAAAAEDEAAgAAABAyAAMAAAAAAAVjAAQAAAAAAQIDBAA=', 0)`
`{ input: { a: "a", b: "b" }, to: "binData" }`	`Binary.createFromBase64('FwAAAAJhAAIAAABhAAJiAAIAAABiAAA=', 0)`
`{ input: { b: "b", a: "a" }, to: "binData" }`	`Binary.createFromBase64('FwAAAAJiAAIAAABiAAJhAAIAAABhAAA=', 0)` フィールドの順序が異なるため、出力は前の例とは異なります。
`{ input: { a: [ NumberInt(1), NumberInt(2) ] }, to: "binData" }`	`Binary.createFromBase64('GwAAAARhABMAAAAQMAABAAAAEDEAAgAAAAAA', 0)`
`{ input: { a: [ NumberInt(2), NumberInt(1) ] }, to: "binData" }`	`Binary.createFromBase64('GwAAAARhABMAAAAQMAACAAAAEDEAAQAAAAAA', 0)` 配列の要素の順序が異なるため、出力は前の例と異なります。
`{ input: { a: "a" }, to: { type: 5, subtype: 128 } }`	`Binary.createFromBase64('DgAAAAJhAAIAAABhAAA=', 128)`
`{ input: { a: "a" }, to: "binData", format: "hex" }`	`Binary.createFromBase64('DgAAAAJhAAIAAABhAAA=', 0)` `$convert` `format` フィールドを無視します。
`{ input: { a: "a" }, to: "binData", format: "bson" }`	Error: Invalid 'format' argument for $convert: bson `$convert` `format` フィールドを無視する前に検証します。
`{ input: null, to: "binData" }`	null

string から BinData への変換

MongoDB は、binData と string の間の変換もサポートしています。

次の例は、string を 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 base64string.`
`{ input: "hn3uUsMxSE6S0cVkebjmfg==", to: { type: "binData", subtype: 4 }, format: "base64"}`	`Failed to parse BinData 'hn3uUsMxSE6S0cVkebjmfg==' in $convertwith 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 onErrorvalue: 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.`

注意

配列への変換

バージョン8.3の新機能。

次の表で、配列に変換できる入力型を一覧にしています。

入力タイプ	動作
binData	数値の配列を返します。配列要素の数値型は、 binData形式によって異なります。
文字列	string 内の内容に対応する配列を返します。 string には有効なJSON配列を表す文字が含まれている必要があります。
null または欠落	null を返します。

次の表に、string を配列に変換する例をいくつか示します。

例	結果
`{ input: "[1, 2, 3]", to: "array" }`	[ 1, 2, 3 ]
`{ input: '["a", "b", "c"]', to: "array" }`	[ 'a', 'b', 'c' ]
`{ input: "[]", to: "array" }`	[ ]
`{ input: "{}", to: "array" }`	エラー: inputが予想されるタイプの「配列」と一致しません
`{ input: 123, to: "array" }`	エラー: $convert で onError 値がない場合、int から配列への変換がサポートされていません
`{ input: "123", to: "array" }`	エラー: inputは有効なJSONを表しません : 予期しないスタンドアロン値
`{ input: "[{\"$oid\": \"507f1f77bcf86cd799439011\"}]", to:"array" }`	[ { '$oid': '507f1f77bcf86cd799439011' } ]
`{ input: "[1, 2, 3]", to: "array", format: "base64url" }`	[ 1, 2, 3 ]
`{ input: "asdf", to: "array", onError: "on error!" }`	'on error!'
`{ input: null, to: "array", onNull: "on null!" }`	'on null!'

binData を配列に変換する

次の例では、$convert が異なる形式の binData をそれぞれの型の値を含む配列に変換する方法を示しています。

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

出力:

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

オブジェクトへの変換

バージョン8.3の新機能。

次の表は、オブジェクトに変換できるinput型を一覧表示したものです。

入力タイプ	動作
文字列	string 内の内容に対応する document を返します。 string には、有効なJSONオブジェクトを表す文字が含まれている必要があります。
null または欠落	null を返します。

次の表に、オブジェクトへの変換の例をいくつか示します。

例	結果
`{ input: "{\"a\": 1, \"b\": 2}", to: "object" }`	{ a: 1, b: 2 }
`{ input: "{}", to: "object" }`	{ }
`{ input: "[]", to: "object" }`	エラー: inputは予想される型「オブジェクト」と一致しません
`{ input: "123", to: "object" }`	エラー: inputは有効なJSONを表しません : 予期しないスタンドアロン値
`{ input: "{\"nam\\u0000e\": \"foo\"}", to: "object" }`	エラー: input は有効なJSONを表しません : 埋め込み null バイトは無効
`{ input: "{\"name\": \"fo\\u0000o\"}", to: "object" }`	{ name: 'fex00o' }
`{ 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" }`	{LargeNetg: -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 ] }

ブール値に変換

次の表でブール値に変換できる入力型を一覧にしています。

入力タイプ	動作
配列	true を返します
バイナリデータ	true を返します
ブール値	何も起こりません。ブール値を返します。
コード	true を返します
日付	true を返します
小数点	0 でない場合、`true` を返します。 0 の場合、`false` を返します。
Double	0 でない場合、`true` を返します。 0 の場合、`false` を返します。
整数	0 でない場合、`true` を返します。 0 の場合、`false` を返します。
JavaScript	true を返します
Long	0 でない場合、`true` を返します。 0 の場合、`false` を返します。
Max key	true を返します
MinKey	true を返します
null	`onNull`オプションに指定された値を返します。デフォルトでは、null を返します。
オブジェクト	true を返します
ObjectId	true を返します
正規表現	true を返します
文字列	true を返します
タイムスタンプ	true を返します

MongoDB のデータ型の詳細については、「BSON types」をご覧ください。

次の表でブール値への変換例を一覧にしています。

例	結果
`{ 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

整数への変換

次の表で、整数に変換できる入力型を一覧にしています。

入力タイプ	動作
ブール値	`false` に対して `0` を返します。 `true` に対して `1` を返します。
BinData	`binData` 値を整数として返します。`binData` は、2 の符号付き整数として解釈されます。 `binData` 値のバイト数は、`1`、`2`、または `4` である必要があります。 `input` が予期しない長さである場合、エラーが発生します。この動作は `$convert.onError` を設定することで制御できます。
Double	切り捨てられた値を返します。切り捨てられた double 値は、整数値の最小値と最大値の範囲内に収まる必要があります。切り捨てられた値が最小の整数値より小さい、または最大の整数値より大きい場合、double 値を変換することはできません。
小数点	切り捨てられた値を返します。切り捨てられた小数値は、整数の最小値と最大値の範囲内に収まる必要があります。切り捨てられた値が最小整数値より小さい、または最大整数値より大きい 10 進数値は変換できません。
整数	何も起こりません。整数値を返します。
Long	long 値を整数として返します。 long 値は整数の最小値と最大値の範囲内になければなりません。最小整数値より小さい、または最大整数値より大きい long 値を変換することはできません。
文字列	文字列の数値を整数として返します。 `base` を省略するか、`null` に設定する場合、string の値は有効な基数 ₁₀ 整数で、整数の最小値と最大値の範囲内である必要があります。 `base` を指定する場合、string にはその基数で有効な数字のみを含める必要があります。`"0x"` などのプレフィックスは許可されていません。結果の整数は、整数の最小値と最大値の範囲内である必要があります。

次の表に、整数への変換の例をいくつか示します。

例	結果
`{ 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" }`	5,000
`{ input: Long( "922337203600" ), to: "int" }`	エラー
`{ input: "-2", to: "int" }`	-2
`{ input: "2.5", to: "int" }`	エラー
`{ 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",}`	エラー: 長さが無効であるため、BinData の変換に失敗しました: 7

10 進数に変換

以下の表は、10 進数に変換できる入力型の一覧です。

入力タイプ	動作
ブール値	`false` に対して `Decimal128( "0" )` を返します。 `true` に対して `Decimal128( "1" )` を返します。
Double	double 値を小数として返します。
小数点	何も起こりません。小数を返します。
整数	int 値を小数で返します。
Long	long 値を小数で返します。
文字列	文字列の数値を小数で返します。 `base` を省略するか、`null` に設定する場合、string 値は有効な ₁₀ 進数で、小数の最小値と最大値の範囲内である必要があります。 `base` を指定する場合、string にはその基数で有効な数字のみを含める必要があります。`"0x"` などのプレフィックスは許可されていません。結果の小数は、小数の最小値と最大値の範囲内である必要があります。
日付	日付値に対応する UNIXエポックからのミリ秒数を返します。

次の表に 10 進数への変換の例をいくつか示します。

例	結果
`{ 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 への変換

次の表に、double に変換できる入力型を一覧にしています。

入力タイプ	動作
ブール値	`false` に対して NumberDouble(0) を返します。 `true` に対して NumberDouble(1) を返します。
BinData	`binData` 値を double として返します。`binData` は、IEEE で規定される 754 の単精度または倍精度浮動点として解釈されます。 `binData` 値のバイト数は `4` または `8` である必要があります。 `input` が予期しない長さである場合、エラーが発生します。この動作は `$convert.onError` を設定することで制御できます。
Double	何も処理しません。double を返します。
小数点	小数値を double として返します。小数値は、double の最小値と最大値の範囲内に収まる必要があります。最小の double 値より小さい値、または最大の double 値より大きい値の小数値は変換できません。
整数	int 値を double として返します。
Long	long 値を double として返します。
文字列	string の数値を double として返します。 `base` を省略するか、`null` に設定する場合、string 値は有効な基本 ₁₀ double であり、double の最小値と最大値の範囲内である必要があります。 `base` を指定する場合、string にはその基数で有効な数字のみを含める必要があります。`"0x"` などのプレフィックスは許可されていません。結果として得られる double は、double の最小値と最大値の範囲内である必要があります。
日付	日付値に対応する UNIXエポックからのミリ秒数を返します。

次の表に、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
`{ 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",}`	エラー: 長さが無効であるため、binData の変換に失敗しました: 2

非正規数

MongoDB 8.3 以降、サーバーは表現可能なすべての倍精度浮動点数の全範囲を解析できます。これには、非正規数で最上位桁の先頭にゼロがあり、指数の値が最小であるものが含まれます。詳細については、サブ正規数を参照してください。

MongoDBの以前のバージョンでは、これらの数値を解析しようとすると、サーバーはエラーを返します。次の例ではMongoDB 8.3 より前のバージョンでエラーを発生させます。

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

この例は失敗し、次のようなエラーが発生します。

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

Long への変換

次の表で、long に変換できる入力型を一覧にしています。

入力タイプ	動作
ブール値	`false` に対して `0` を返します。 `true` に対して `1` を返します。
BinData	`binData` 値を long として返します。`binData` は、2 の符号付き整数として解釈されます。 `binData` 値のバイト数は、`1`、`2`、`4`、または `8` である必要があります。 `input` が予期しない長さである場合、エラーが発生します。この動作は `$convert.onError` を設定することで制御できます。
Double	切り捨てられた値を返します。切り捨てられた double 値は、long 値の最小値と最大値の範囲内に収まる必要があります。切り捨てられた値が最小の long 値より小さい、または最大の long 値より大きい場合、double 値を変換することはできません。
小数点	切り捨てられた値を返します。切り捨てられた 10 進数値は、long 値の最小値と最大値の範囲内に収まる必要があります。切り捨てた 10 進数値が最小の long 値より小さい、または最大の long 値より大きい場合、10 進値は変換できません。
整数	整数値を long として返します。
Long	何も起こりません。long 値を返します。
文字列	文字列の数値を返します。 `base` を省略するか、`null` に設定する場合、string 値は有効な基数 ₁₀ long で、long 値の最小値と最大値の範囲内である必要があります。 `base` を指定する場合、string にはその基数で有効な数字のみを含める必要があります。`"0x"` などのプレフィックスは許可されていません。結果の long は、long 値の最小値と最大値の範囲内である必要があります。
日付	Date をUNIXエポックを基準としたミリ秒数に変換します。

次の表で long 値への変換例の一部を一覧にしています。

例	結果
`{ 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
`{ input: Binary(Buffer.from("001000000", "hex"), 0), to: "long", byteOrder: "big",}`	Long("1048576")

日付に変換

次の表で、日付に変換できる入力型を一覧にしています。

入力タイプ	動作
Double	切り捨てられた double 値で表されるミリ秒数に対応する日付を返します。正の数は、1970 年 1 月 1 日からのミリ秒数に対応します。負の数は、1970 年 1 月 1 日より前のミリ秒数に対応します。
小数点	切り捨てられた小数値で表されるミリ秒数に対応する日付を返します。正の数は、1970 年 1 月 1 日からのミリ秒数に対応します。負の数は、1970 年 1 月 1 日より前のミリ秒数に対応します。
Long	long 値で表されるミリ秒数に対応する日付を返します。正の数は、1970 年 1 月 1 日からのミリ秒数に対応します。負の数は、1970 年 1 月 1 日より前のミリ秒数に対応します。
文字列	日付文字列に対応する日付を返します。文字列は次のような有効な日付文字列でなければなりません。 "2018-03-03" "2018-03-03T12:00:00Z" "2018-03-03T12:00:00+0500"
ObjectId	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")

ObjectId への変換

下表には、ObjectId に変換できる入力型が一覧表示されています。

入力タイプ	動作
文字列	長さ 24 の 16 進文字列の ObjectId を返します。長さ 24 の 16 進文字列ではない文字列値を変換することはできません。

次の表で、日付への変換例の一部を示します。

例	結果
`{ input: "5ab9cbfa31c2ab715d42129e", to: "objectId"}`	ObjectId("5ab9cbfa31c2ab715d42129e")
`{ input: "5ab9cbfa31c2ab715d42129", to: "objectId"}`	エラー

文字列への変換

次の表に、文字列に変換できる入力タイプを示します。

入力タイプ	動作
配列	`Array` を string として返します。バージョン8.3の新機能。
BinData	`BinData` が UUID の場合、は UUID を string として返します。それ以外の場合、は base64 でエンコードされた string の値を返します。
ブール値	ブール値を文字列として返します。
日付	`Date` を string として返します。
小数点	`Decimal` 値を string として返します。
Double	`Double` 値を string として返します。
整数	`Integer` 値を string として返します。
Long	`Long` 値を string として返します。
Max key	`MaxKey` を string として返します。バージョン8.3の新機能。
MinKey	`MinKey` を string として返します。バージョン8.3の新機能。
オブジェクト	オブジェクトを string として返します。バージョン8.3の新機能。
ObjectId	`ObjectId` 値を16進数文字列として返します。
正規表現	`Regular Expression` を string として返します。バージョン8.3の新機能。
文字列	操作はありません。string 値を返します。
タイムスタンプ	`Timestamp` を string として返します。バージョン8.3の新機能。

注意

base を指定し、かつ input が数値型である場合、$convert はその基数の整数値の string 表現を返します。文字列の基本変換は整数値でのみサポートされます。それ以外の場合、$convert は変換エラーを返します。onError を指定しない限り。

次の表に、文字列値への変換の例をいくつか示します。

例	結果
`{ 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"

例

このページの例では、sample_mflix データセットのデータを使用しています。自己管理型 MongoDB 配置にこのデータセットをロードする方法の詳細については、「サンプルデータセットのロード」を参照してください。サンプルデータベースに何らかの変更を加えた場合は、今ページの例を実行するには、データベースを削除して再作成する必要がある可能性があります。

基本変換の例

16進数文字列は整数を表現するコンパクトな方法であり、多くのシステムが識別子を16進数値として交換しています。次の例では、各映画の数値imdb.idを16進数文字列に変換します。

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

16進数文字列を整数に戻すには、その文字列を $convert に base: 16 および to: "int" とともに渡します。

タイプ変換の例

次の集計操作では、ほとんどのドキュメントではdoubleですが、他のドキュメントでは空のstringであるimdb.ratingフィールドをdoubleに変換します。また、一部のドキュメントで欠落しているmetacriticフィールドを整数に変換します。$matchステージでは、各変換結果を示す3つの映画を選択します。

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 を返します。

注意

これらの例では mongosh を使用します。レガシーの mongo shell ではデフォルトのタイプが異なります。

詳細

を使用して値を配列に変換する $toArray
を使用して string をオブジェクトに変換する $toObject
を使用して値をブール値に変換する $toBool
を使用して値を整数に変換する $toInt
を使用して値を小数に変換します $toDecimal
を使用して値を double に変換します $toDouble
を使用して値を long に変換する $toLong
を使用して値を日付に変換する $toDate
を使用して値を ObjectId に変換する $toObjectId
を使用して値を string に変換する $toString
を使用して日付 string を日付オブジェクトに変換する $dateFromString
を使用して日付オブジェクトを string に変換する $dateToString

戻る

$cond

$cos

$convert（式演算子）

定義

互換性

構文

タイプ識別子

バイナリ サブタイプ

動作

BinData への変換

数値型から binData に変換する:

オブジェクトを変換します。 binData

string から BinData への変換

配列への変換

binData を配列に変換する

オブジェクトへの変換

ブール値に変換

整数への変換

10 進数に変換

Double への変換

非正規数

Long への変換

日付に変換

ObjectId への変換

文字列への変換

例

基本変換の例

タイプ変換の例

詳細

バイナリサブタイプ

数値型から `binData` に変換する:

オブジェクトを変換します。 `binData`