$convert (型変換)
最終更新：2026-10-09
$convert (型変換)
$convert は値を指定の BSON 型にキャストし、型変換の代表的な入口です。to パラメータには double、string、objectId、bool、date、int、long、decimal を指定できます。変換の失敗は既定ではエラーになりますが、onError でフォールバックを指定できます。null の入力は既定で null を返し、onNull で上書きできます。代表的な用途は、数値文字列を算術用の数値に変換したり、日付文字列を日付に解析したりすることです。$toInt のような短縮形と比べ、$convert は失敗処理を追加できます。
| カテゴリ | 集合・条件・変換 |
|---|---|
| MongoDB バージョン | 1.0+ |
| 例の言語 | mongosh（シェル） |
📝 構文
{ $convert: { input: <expression>, to: <type>, onError: <fallback>, onNull: <nullResult> } }⚙️ パラメータ
| input | 変換する値。 |
|---|---|
| to | 対象の型: double/string/objectId/bool/date/int/long/decimal。 |
| onError | 変換が失敗した場合に返される任意の値。 |
| onNull | 入力が null または欠落している場合に返される任意の値。 |
戻り値：変換後の値。失敗時または null 時は onError/onNull が適用されます
▶ 例
以下のコマンドをローカルの mongosh で実行してください（mongod が起動済みである必要があります）：
// $convert: 文字列価格を数値に変換、フォールバック 0
db.products.aggregate([
{ $project: {
priceNum: { $convert: { input: '$priceStr', to: 'double', onError: 0 } }
} }
])出力：
{ '_id': 1, 'priceNum': 19.9 }
{ '_id': 2, 'priceNum': 0 }📌 注意事項
- 失敗は既定でエラーになる。本番では必ず onError を指定する
- null の入力は null を返す。onNull で上書きできる
- $toInt/$toDouble などは $convert の短縮形だが、onError がない
🏷️ 関連タグ
💡 関連ケース
さらなる実践ケースを近日公開予定。
📚 関連チュートリアル
❓ よくある質問
Q$convert が失敗するとどうなりますか？
Aエラーになりパイプラインが中断します。onError があればフォールバック値を返します。
Q$toInt との違いは？
A$toInt は $convert の省略形です。$convert には onError/onNull の処理があります。
Qto にはどの型を指定できますか？
Adouble、string、objectId、bool、date、int、long、decimal です。
