定義
互換性
次の環境でホストされる配置には $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は、次のフィールドを持つドキュメントを取得します。
フィールド | 必要性 | 説明 |
|---|---|---|
| 必須 | 引数には任意の有効な式を使用できます。 式の詳細については、「式 」を参照してください。 |
| 必須 |
|
| オブジェクトとして | |
| 任意 |
|
| binData との変換または binData からの変換時に必要です。 | 入力または出力の binData 形式を指定します。次のいずれかの値になります。
|
| 任意 | 変換中にエラーが発生した場合に返される値。サポートされていない型の変換などが含まれます。引数には任意の有効な式を使用できます。 指定されていない場合、エラーが発生すると操作はエラーをスローし、停止します。 |
| 任意 |
$convertに加えて、MongoDB は、デフォルトの "onError" および "onNull" の動作が受け入れられる場合、省略形として次の集計演算子を提供します。
タイプ識別子
to.typeフィールドは、次の数値識別子と string 識別子を受け入れます。
文字列識別子 | 数値識別子 | ノート |
|---|---|---|
"double" | 1 | 詳細については、double への変換を参照してください。 |
"string" | 2 | 「String への変換」を参照してください。 |
"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 への変換
binData に変換できるのは文字列のみです。他のすべての入力型はエラーになります。
次の binData への変換の例を参照してください。
例 | 結果 |
|---|---|
| |
| |
| |
| |
| |
| |
| |
| |
注意
MongoDB 8.0 では、$convert は元の値と元のサブタイプを返します。変換は行われません。8.0 より前の MongoDB バージョンには、binData 変換がありません。
ブール値に変換
次の表でブール値に変換できる入力型を一覧にしています。
入力タイプ | 動作 |
|---|---|
配列 | true を返します |
バイナリ データ | true を返します |
ブール値 | 何も起こりません。ブール値を返します。 |
コード | true を返します |
日付 | true を返します |
小数点 | 0 でない場合、`true` を返します。 |
Double | 0 でない場合、`true` を返します。 |
整数 | 0 でない場合、`true` を返します。 |
JavaScript | true を返します |
Long | 0 でない場合、`true` を返します。 |
Max key | true を返します |
MinKey | true を返します |
null |
|
オブジェクト | true を返します |
ObjectId | true を返します |
正規表現 | true を返します |
文字列 | true を返します |
タイムスタンプ | true を返します |
MongoDB のデータ型の詳細については、「BSON types」をご覧ください。
次の表でブール値への変換例を一覧にしています。
例 | 結果 |
|---|---|
| true |
| false |
| true |
| true |
| false |
| true |
| true |
| true |
| true |
| true |
| null |
Tip
整数への変換
次の表で、整数に変換できる入力型を一覧にしています。
入力タイプ | 動作 |
|---|---|
ブール値 |
|
Double | 切り捨てられた値を返します。 切り捨てられた double 値は、整数値の最小値と最大値の範囲内に収まる必要があります。 切り捨てられた値が最小の整数値より小さい、または最大の整数値より大きい場合、double 値を変換することはできません。 |
小数点 | 切り捨てられた値を返します。 切り捨てられた小数値は、整数の最小値と最大値の範囲内に収まる必要があります。 切り捨てられた値が最小整数値より小さい、または最大整数値より大きい 10 進数値は変換できません。 |
整数 | 何も起こりません。整数値を返します。 |
Long | long 値を整数として返します。 long 値は整数の最小値と最大値の範囲内になければなりません。 最小整数値より小さい、または最大整数値より大きい long 値を変換することはできません。 |
文字列 | 文字列の数値を整数として返します。 文字列の値は 10 進数の整数で(例: 浮動小数、小数、または10 進数以外の数(例: |
次の表に、整数への変換の例をいくつか示します。
例 | 結果 |
|---|---|
| 1 |
| 0 |
| 1 |
| 5 |
| エラー |
| 5,000 |
| エラー |
| -2 |
| エラー |
| null |
Tip
$toInt 演算子。
10 進数に変換
以下の表は、10 進数に変換できる入力型の一覧です。
入力タイプ | 動作 |
|---|---|
ブール値 |
|
Double | double 値を小数として返します。 |
小数点 | 何も起こりません。小数を返します。 |
整数 | int 値を小数で返します。 |
Long | long 値を小数で返します。 |
文字列 | 文字列の数値を小数で返します。 文字列の値は 10 進数の数値でなければなりません(例: 10 進数以外の数の文字列値は変換できません(例: |
日付 | 日付値に対応する UNIXエポックからのミリ秒数を返します。 |
次の表に 10 進数への変換の例をいくつか示します。
例 | 結果 |
|---|---|
| Decimal128("1") |
| Decimal128("0") |
| Decimal128("2.50000000000000" ) |
| Decimal128("5") |
| Decimal128("10000") |
| Decimal128("-5.5") |
| Decimal128("1522039108044") |
Tip
Double への変換
次の表に、double に変換できる入力型を一覧にしています。
入力タイプ | 動作 |
|---|---|
ブール値 |
|
Double | 何も処理しません。double を返します。 |
小数点 | 小数値を double として返します。 小数値は、double の最小値と最大値の範囲内に収まる必要があります。 最小の double 値より小さい値、または最大の double 値より大きい値の小数値は変換できません。 |
整数 | int 値を double として返します。 |
Long | long 値を double として返します。 |
文字列 | string の数値を double として返します。 string の値は 10 進数の数値で(例: 10 進数以外の数の string の値(例: |
日付 | 日付値に対応する UNIXエポックからのミリ秒数を返します。 |
次の表に、double への変換の例をいくつか示します。
例 | 結果 |
|---|---|
| 1 |
| 0 |
| 2.5 |
| 5 |
| 10000 |
| -5.5 |
| 50000000000 |
| 1522039108044 |
Tip
Long への変換
次の表で、long に変換できる入力型を一覧にしています。
入力タイプ | 動作 |
|---|---|
ブール値 |
|
Double | 切り捨てられた値を返します。 切り捨てられた double 値は、long 値の最小値と最大値の範囲内に収まる必要があります。 切り捨てられた値が最小の long 値より小さい、または最大の long 値より大きい場合、double 値を変換することはできません。 |
小数点 | 切り捨てられた値を返します。 切り捨てられた 10 進数値は、long 値の最小値と最大値の範囲内に収まる必要があります。 切り捨てた 10 進数値が最小の long 値より小さい、または最大の long 値より大きい場合、10 進値は変換できません。 |
整数 | 整数値を long として返します。 |
Long | 何も起こりません。long 値を返します。 |
文字列 | 文字列の数値を返します。 文字列値は 10 進数の long 値で(例えば 浮動小数、小数、または 10 進数以外の数(例: |
日付 | Date をUNIXエポックを基準としたミリ秒数に変換します。 |
次の表で long 値への変換例の一部を一覧にしています。
例 | 結果 |
|---|---|
| Long("1") |
| Long("0") |
| Long("2") |
| Long("5") |
| エラー |
| Long("8") |
| Long("1522039108044") |
| Long("-2") |
| エラー |
| null |
Tip
日付に変換
次の表で、日付に変換できる入力型を一覧にしています。
入力タイプ | 動作 |
|---|---|
Double | 切り捨てられた double 値で表されるミリ秒数に対応する日付を返します。 正の数は、1970 年 1 月 1 日からのミリ秒数に対応します。 負の数は、1970 年 1 月 1 日より前のミリ秒数に対応します。 |
小数点 | 切り捨てられた小数値で表されるミリ秒数に対応する日付を返します。 正の数は、1970 年 1 月 1 日からのミリ秒数に対応します。 負の数は、1970 年 1 月 1 日より前のミリ秒数に対応します。 |
Long | long 値で表されるミリ秒数に対応する日付を返します。 正の数は、1970 年 1 月 1 日からのミリ秒数に対応します。 負の数は、1970 年 1 月 1 日より前のミリ秒数に対応します。 |
文字列 | 日付文字列 に対応する日付を返します。 文字列は次のような有効な日付文字列でなければなりません。
|
ObjectId | ObjectId のタイムスタンプに対応する日付を返します。 |
タイムスタンプ | タイムスタンプに対応する日付を返します。 |
次の表で、日付への変換例の一部を示します。
例 | 結果 |
|---|---|
| ISODate("1973-10-20T21:20:00.000Z") |
| ISODate("2009-09-19T14:53:56.000Z") |
| ISODate("2004-11-09T11:33:20.000Z") |
| ISODate("1935-02-22T12:26:40.000Z") |
| ISODate("2018-03-27T04:08:58.000Z") |
| ISODate( "2018-03-03T00:00:00.000Z") |
| ISODate("2018-03-20T06:00:06.000Z") |
| エラー |
| ISODate("2021-11-23T17:21:58.000Z") |
Tip
$toDate演算子
ObjectId への変換
下表には、ObjectId に変換できる入力型が一覧表示されています。
入力タイプ | 動作 |
|---|---|
文字列 | 長さ 24 の 16 進文字列の ObjectId を返します。 長さ 24 の 16 進文字列ではない文字列値を変換することはできません。 |
次の表で、日付への変換例の一部を示します。
例 | 結果 |
|---|---|
| ObjectId("5ab9cbfa31c2ab715d42129e") |
| エラー |
Tip
$toObjectId 演算子。
文字列への変換
次の表に、文字列に変換できる入力タイプを示します。
入力タイプ | 動作 |
|---|---|
BinData | バイナリデータ値を文字列として返します。 |
ブール値 | ブール値を文字列として返します。 |
Double | double 値を string として返します。 |
小数点 | 10 進数値を文字列として返します。 |
整数 | 整数値を文字列として返します。 |
Long | long 値を文字列として返します。 |
ObjectId | ObjectId 値を文字列として返します。 |
文字列 | 何も起こりません。文字列値を返します。 |
日付 | 日付を文字列値として返します。 |
次の表に、文字列値への変換の例をいくつか示します。
例 | 結果 |
|---|---|
| "true" |
| "false" |
| "2.5" |
| "2" |
| "1000" |
| "5ab9c3da31c2ab715d421285" |
| "2018-03-27T16:58:51.538Z" |
| 'hn3f' |
| "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 を返します。