$substr (部分文字列)
最終更新：2026-10-09
$substr (部分文字列)
$substr は指定した位置から指定した長さの部分文字列を取り出します。MongoDB 3.4 以降、$substr は $substrCP の別名で、位置を Unicode コードポイント（おおよそ文字数）で数えます。中国語や絵文字のようなマルチバイト文字でも安全で、文字が途中で切れることはありません。start は 0 始まりで、負の start は空文字列を、負の length は start 以降のすべてを返します。
| カテゴリ | 文字列 |
|---|---|
| MongoDB バージョン | 1.0+ |
| 例の言語 | mongosh（シェル） |
📝 構文
{ $substr: [ <string-expression>, <start>, <length> ] }⚙️ パラメータ
| 文字列 | 必須。元の文字列式。 |
|---|---|
| 開始位置 | 必須の整数（0 始まり）。負の場合は空文字列になります。 |
| 長さ | 必須の整数。負の場合は start から末尾までを返します。 |
戻り値：抽出された部分文字列。いずれかの引数が null の場合は null。
▶ 例
以下のコマンドをローカルの mongosh で実行してください（mongod が起動済みである必要があります）：
// $substr: 電話番号の最初の 3 桁
db.users.aggregate([
{ $project: { code: { $substr: [ '$phone', 0, 3 ] } } }
])出力：
{ "_id": 1, "code": "138" }
{ "_id": 2, "code": "139" }📌 注意事項
- 3.4 以降は $substrCP の別名 — コードポイント基準でマルチバイト安全
- 負の start は空文字列、負の length は残り全部を返す
- UTF-8 バイト単位で切りたい場合は $substrBytes を使う
🏷️ 関連タグ
💡 関連ケース
さらなる実践ケースを近日公開予定。
📚 関連チュートリアル
❓ よくある質問
Q$substr と $substrCP は同じですか？
A3.4 以降、$substr は $substrCP の別名で、動作は完全に同じです。
Q中国語を切り出して文字化けしませんか？
Aしません — コードポイントで数えるため、中国語でも安全です。
Qstart を負にできますか？
Aはい — 負の start は空文字列を返します。
