/ /

$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

MongoDB8.3 以降では、to フィールドが数値のである場合、フィールドをbinData inputarrayに設定することもできます。例については、「数値の配列を binData に変換する」を参照してください。

MongoDB は、値を binData に変換するときに、入力としてこれらの数値型もサポートしています。

to

必須

input 式を変換する型を指定します。to を次のいずれかの値に設定できます。

ターゲット型の文字列または数値識別子。to.type を参照してください。
to.type と to.subtype フィールドを含むオブジェクト。この形式を使用して binData に変換し、binData サブタイプを指定します。

to.type

オブジェクトとして to を指定する場合は必須です

引数は、以下の数値識別子または文字列識別子のいずれかに変換される有効な式であればどれでもかまいません。

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

to.subtype

任意

to.type がbinData の場合、to.subtype が変換する binData サブタイプを指定します。to.subtype には、次のいずれかの値を指定できます。

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

デフォルト: 0（汎用バイナリのサブタイプ）

byteOrder

任意

binData と数値型の間の変換に対してビッグエンディアンバイトまたはリトルエンディアンバイトの順序付けを指定します。指定しない場合、デフォルトはリトルエンディアンバイト順になります。

base

任意

string 型と数値型間の変換の整数基数。

nullの場合、は base$convert を省略した場合と同様に動作します。
指定すると、 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または見つからない場合に返す値。引数には任意の有効な式を使用できます。

指定されていない場合、が null または欠落していれば、は null$convert を返します。input

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

動作

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

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

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

注意

配列への変換

バージョン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: 123, to: "array" }

エラー: $convert で onError 値がない場合、int から配列への変換がサポートされていません

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

エラー: 入力は有効なJSONを表しません : 予期しないスタンドアロン値

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

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

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

[ 1, 2, 3 ]

注意

format オプションは無視されます。

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

'on error!'

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

'on null!'

binData を配列に変換する

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

入力:

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の新機能。

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

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

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

例

結果

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

{ a: 1, b: 2 }

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

{ }

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

エラー: 入力は予想される型「オブジェクト」と一致しません

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

エラー: 入力は有効なJSONを表しません : 予期しないスタンドアロン値

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

エラー: 入力は有効な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 を返します
小数点	Returns true if not zero Return false if zero
Double	Returns true if not zero Return false if zero
整数	Returns true if not zero Return false if zero
JavaScript	true を返します
Long	Returns true if not zero Return false if zero
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

整数への変換

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

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

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

例

結果

{ input: true, to: "int" }

{ input: false, to: "int" }

{ input: 1.99999, to: "int" }

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

{
   input: Decimal128( "9223372036000.000" ),
   to: "int"
}

エラー

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

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 進数に変換できる入力型の一覧です。

入力タイプ	動作
ブール値	Returns `Decimal128( "0" )` for `false`. Returns `Decimal128( "1" )` for `true`.
Double	double 値を小数として返します。
小数点	何も起こりません。小数を返します。
整数	int 値を小数で返します。
Long	long 値を小数で返します。
文字列	文字列の数値を小数で返します。 `basenull`を省略するか、に設定する場合、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 に変換できる入力型を一覧にしています。

入力タイプ	動作
ブール値	Returns NumberDouble(0) for `false`. Returns NumberDouble(1) for `true`.
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 として返します。 `basenull`を省略するか、に設定する場合、string 値は有効な基本 double であり、double₁₀ の最小値と最大値の範囲内である必要があります。 `base` を指定する場合、string にはその基数で有効な数字のみを含める必要があります。 `"0x"` などのプレフィックスは許可されていません。結果として得られる double は、double の最小値と最大値の範囲内である必要があります。
日付	日付値に対応する UNIXエポックからのミリ秒数を返します。

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

例

結果

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

エラー: 長さが無効であるため、binData の変換に失敗しました: 2

非正規数

MongoDB8.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 に変換できる入力型を一覧にしています。

入力タイプ	動作
ブール値	Returns `0` for `false`. Returns `1` for `true`.
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 値を返します。
文字列	文字列の数値を返します。 `basenull`を省略するか、に設定する場合、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 の値を返します。
ブール値	ブール値を 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"

例

基本変換の例

プレースホルダードキュメントを含むコレクションexamples を作成します。

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

次の例では、異なる基数を使用して数値と string を変換します。

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

この操作、次のドキュメントが返されます。

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

タイプ変換の例

次のドキュメントを使用してコレクション orders を作成します。

db.orders.insertMany( [
   { _id: 1, item: "apple", qty: 5, price: 10 },
   { _id: 2, item: "pie", qty: 10, price: Decimal128("20.0") },
   { _id: 3, item: "ice cream", qty: 2, price: "4.99" },
   { _id: 4, item: "almonds" },
   { _id: 5, item: "bananas", qty: 5000000000, price: Decimal128("1.25") }
] )

orders コレクションにおける次の集計操作では、 price を10 進数に変換します。

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

この操作により、次のドキュメントが返されます。

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

注意

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

詳細

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

戻る

$cond

$cos

定義

互換性

構文

動作

BinData への変換

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

string から BinData への変換

注意

配列への変換

注意

binData を配列に変換する

オブジェクトへの変換

ブール値に変換

整数への変換

10 進数に変換

Double への変換

非正規数

Long への変換

日付に変換

ObjectId への変換

文字列への変換

注意

例

基本変換の例

タイプ変換の例

注意

詳細

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