$convert（集計）

項目一覧

定義

互換性
構文
動作
例

定義

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

互換性

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

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

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

構文

バージョン8.0で変更。

{
   $convert:
      {
         input: <expression>,
         to: <type expression> || {
            type: <type expression>,
            subtype: <int>
         },
         format: <string>,
         onError: <expression>,
         onNull: <expression>
      }
}

$convertは、次のフィールドを持つドキュメントを取得します。

フィールド

必要性

説明

input

必須

引数には任意の有効な式を使用できます。式の詳細については、「式演算子」を参照してください。

to

必須

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

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

to.type

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

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

文字列識別子	数値識別子	ノート
"double"	1	double への変換の詳細については、「Double への変換」を参照してください。
"string"	2	文字列への変換の詳細については、「文字列への変換」を参照してください。
"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（汎用バイナリのサブタイプ）

format

binData との変換または binData からの変換時に必要です。

入力または出力の binData 形式を指定します。次のいずれかの値になります。

base64
base64url
utf8
hex
uuid

format がuuid の場合、to.subtype は4 である必要があります。

onError

任意

変換中にエラーが発生した場合に返される値。サポートされていない型の変換などが含まれます。引数には任意の有効な式を使用できます。

指定されていない場合、エラーが発生すると操作はエラーをスローし、停止します。

onNull

任意

input がNULLまたは見つからない場合に返す値。引数には任意の有効な式を使用できます。

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

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

動作

BinData への変換

binData に変換できるのは文字列のみです。他のすべての入力型はエラーになります。

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

{
   input: 123,
   to: { type: "binData", subtype: 0 }
}

Unsupported conversion from int to binData in $convert with no onError value

ブール値に変換

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

入力タイプ	動作
配列	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

Tip

以下も参照してください。

$toBool

整数への変換

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

入力タイプ	動作
ブール値	Returns `0` for `false`. Returns `1` for `true`.
Double	切り捨てられた値を返します。切り捨てられた double 値は、整数値の最小値と最大値の範囲内に収まる必要があります。切り捨てられた値が最小の整数値より小さい、または最大の整数値より大きい場合、double 値を変換することはできません。
小数点	切り捨てられた値を返します。切り捨てられた小数値は、整数の最小値と最大値の範囲内に収まる必要があります。切り捨てられた値が最小整数値より小さい、または最大整数値より大きい 10 進数値は変換できません。
整数	何も起こりません。整数値を返します。
Long	long 値を整数として返します。 long 値は整数の最小値と最大値の範囲内になければなりません。最小整数値より小さい、または最大整数値より大きい long 値を変換することはできません。
文字列	文字列の数値を整数として返します。文字列の値は ₁₀ 進数の整数で（例:`"-5"` 、 `"123456"`）かつ、整数の最小値と最大値の範囲内である必要があります。浮動小数、小数、または₁₀ 進数以外の数（例:`"-5.0"` 、`"0x6400"` ）、あるいは整数の最小値と最大値の範囲外の数値の文字列は変換できません。

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

例

結果

{ 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

Tip

以下も参照してください。

$toInt 演算子。

10 進数に変換

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

入力タイプ	動作
ブール値	Returns `Decimal128( "0" )` for `false`. Returns `Decimal128( "1" )` for `true`.
Double	double 値を小数として返します。
小数点	何も起こりません。小数を返します。
整数	int 値を小数で返します。
Long	long 値を小数で返します。
文字列	文字列の数値を小数で返します。文字列の値は ₁₀ 進数の数値でなければなりません（例: `"-5.5"`、`"123456"`）。 ₁₀ 進数以外の数の文字列値は変換できません（例: `"0x6400"` ）
日付	日付値に対応する 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")

Tip

以下も参照してください。

$toDecimal

Double への変換

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

入力タイプ	動作
ブール値	Returns NumberDouble(0) for `false`. Returns NumberDouble(1) for `true`.
Double	何も処理しません。double を返します。
小数点	小数値を double として返します。小数値は、double の最小値と最大値の範囲内に収まる必要があります。最小の double 値より小さい値、または最大の double 値より大きい値の小数値は変換できません。
整数	int 値を double として返します。
Long	long 値を double として返します。
文字列	string の数値を double として返します。 string の値は ₁₀ 進数の数値で（例: `"-5.5"`、`"123456"`）、double の最小値と最大値の範囲内である必要があります。 ₁₀ 進数以外の数の string の値（例: `"0x6400"`）または 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

Tip

以下も参照してください。

$toDouble

Long への変換

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

入力タイプ	動作
ブール値	Returns `0` for `false`. Returns `1` for `true`.
Double	切り捨てられた値を返します。切り捨てられた double 値は、long 値の最小値と最大値の範囲内に収まる必要があります。切り捨てられた値が最小の long 値より小さい、または最大の long 値より大きい場合、double 値を変換することはできません。
小数点	切り捨てられた値を返します。切り捨てられた 10 進数値は、long 値の最小値と最大値の範囲内に収まる必要があります。切り捨てた 10 進数値が最小の long 値より小さい、または最大の long 値より大きい場合、10 進値は変換できません。
整数	整数値を long として返します。
Long	何も起こりません。long 値を返します。
文字列	文字列の数値を返します。文字列値は ₁₀ 進数の long 値で（例えば`"-5"` 、 `"123456"` ）、long 値の最小値と最大値の範囲内である必要があります。浮動小数、小数、または ₁₀ 進数以外の数（例:`"-5.0"`、`"0x6400"`）、あるいは 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

Tip

以下も参照してください。

$toLong

日付に変換

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

入力タイプ	動作
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")

Tip

以下も参照してください。

$toDate 演算子
$dateFromString

ObjectId への変換

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

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

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

例

結果

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

ObjectId("5ab9cbfa31c2ab715d42129e")

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

エラー

Tip

以下も参照してください。

$toObjectId 演算子。

文字列への変換

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

入力タイプ	動作
BinData	バイナリデータ値を文字列として返します。
ブール値	ブール値を文字列として返します。
Double	double 値を string として返します。
小数点	10 進数値を文字列として返します。
整数	整数値を文字列として返します。
Long	long 値を文字列として返します。
ObjectId	ObjectId 値を文字列として返します。
文字列	何も起こりません。文字列値を返します。
日付	日付を文字列値として返します。

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

例

結果

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

Tip

以下も参照してください。

$toString 演算子
$dateToString

例

次のドキュメントを使用してコレクション 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 ではデフォルトのタイプが異なります。

戻る

$cond

$cos