AI エージェント向け: ドキュメントインデックスは https://www.mongodb.com/ja-jp/docs/llms.txt で利用できます。すべてのページの markdown バージョンは、いずれかの URL パスに .md を追加することで利用できます。

$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 を指定する場合は必須です

引数は、数値識別子または string 識別子に解決される有効な式であればどれでもかまいません。利用可能な識別子については、型識別子を参照してください。

to.subtype

任意

to.type がbinData の場合、to.subtype が変換する binData サブタイプを指定します。有効な値については、バイナリ サブタイプを参照してください。デフォルト: 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" の動作が受け入れられる場合、省略形として次の集計演算子を提供します。

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 への変換の例を参照してください。

例
結果
{ 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.
{ input: 123, to: { type: "binData", subtype: 0 }}
Unsupported conversion from int to binData in $convert with no onError value

注意

MongoDB 8.0 では、$convert は元の値と元のサブタイプを返します。変換は行われません。8.0 より前の MongoDB バージョンには、binData 変換がありません。

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

入力タイプ
動作

配列

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

Double

切り捨てられた値を返します。

切り捨てられた double 値は、整数値の最小値と最大値の範囲内に収まる必要があります。

切り捨てられた値が最小の整数値より小さい、または最大の整数値より大きい場合、double 値を変換することはできません。

小数点

切り捨てられた値を返します。

切り捨てられた小数値は、整数の最小値と最大値の範囲内に収まる必要があります。

切り捨てられた値が最小整数値より小さい、または最大整数値より大きい 10 進数値は変換できません。

整数

何も起こりません。整数値を返します。

Long

long 値を整数として返します。

long 値は整数の最小値と最大値の範囲内になければなりません。

最小整数値より小さい、または最大整数値より大きい long 値を変換することはできません。

文字列

文字列の数値を整数として返します。

文字列の値は 10 進数の整数で(例:"-5" 、 "123456")かつ、整数の最小値と最大値の範囲内である必要があります。

浮動小数、小数、または10 進数以外の数(例:"-5.0" 、"0x6400" )、あるいは整数の最小値と最大値の範囲外の数値の文字列は変換できません。

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

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

Tip

$toInt 演算子。

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

入力タイプ
動作

ブール値

false に対して Decimal128( "0" ) を返します。
true に対して Decimal128( "1" ) を返します。

Double

double 値を小数として返します。

小数点

何も起こりません。小数を返します。

整数

int 値を小数で返します。

Long

long 値を小数で返します。

文字列

文字列の数値を小数で返します。

文字列の値は 10 進数の数値でなければなりません(例: "-5.5"、"123456")。

10 進数以外の数の文字列値は変換できません(例: "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")

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

入力タイプ
動作

ブール値

false に対して NumberDouble(0) を返します。
true に対して NumberDouble(1) を返します。

Double

何も処理しません。double を返します。

小数点

小数値を double として返します。

小数値は、double の最小値と最大値の範囲内に収まる必要があります。

最小の double 値より小さい値、または最大の double 値より大きい値の小数値は変換できません。

整数

int 値を double として返します。

Long

long 値を double として返します。

文字列

string の数値を double として返します。

string の値は 10 進数の数値で(例: "-5.5"、"123456")、double の最小値と最大値の範囲内である必要があります。

10 進数以外の数の string の値(例: "0x6400")または 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

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

入力タイプ
動作

ブール値

false に対して 0 を返します。
true に対して 1 を返します。

Double

切り捨てられた値を返します。

切り捨てられた double 値は、long 値の最小値と最大値の範囲内に収まる必要があります。

切り捨てられた値が最小の long 値より小さい、または最大の long 値より大きい場合、double 値を変換することはできません。

小数点

切り捨てられた値を返します。

切り捨てられた 10 進数値は、long 値の最小値と最大値の範囲内に収まる必要があります。

切り捨てた 10 進数値が最小の long 値より小さい、または最大の long 値より大きい場合、10 進値は変換できません。

整数

整数値を long として返します。

Long

何も起こりません。long 値を返します。

文字列

文字列の数値を返します。

文字列値は 10 進数の long 値で(例えば"-5" 、 "123456" )、long 値の最小値と最大値の範囲内である必要があります。

浮動小数、小数、または 10 進数以外の数(例:"-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

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

入力タイプ
動作

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

下表には、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'

{ 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 ではデフォルトのタイプが異なります。

このページを評価