$substr (Substring)
Last updated: 2026-10-09
$substr (Substring)
$substr extracts a substring starting at a given position with a given length. Since MongoDB 3.4, $substr is an alias for $substrCP, counting positions in Unicode code points (roughly characters), so it is safe for multi-byte text like Chinese and emoji — no torn characters. start is zero-based; a negative start returns an empty string, and a negative length returns everything from start onward.
| Category | String |
|---|---|
| MongoDB Version | 1.0+ |
| Example Language | mongosh (Shell) |
📝 Syntax
{ $substr: [ <string-expression>, <start>, <length> ] }⚙️ Parameters
| string | Required; the source string expression. |
|---|---|
| start index | Required integer, zero-based; negative yields an empty string. |
| length | Required integer; negative returns from start to the end. |
Returns：The extracted substring; null if any argument is null.
▶ Example
Run the commands below in your local mongosh (requires a running mongod):
// $substr: first 3 digits of phone numbers
db.users.aggregate([
{ $project: { code: { $substr: [ '$phone', 0, 3 ] } } }
])Output：
{ "_id": 1, "code": "138" }
{ "_id": 2, "code": "139" }📌 Notes
- Alias of $substrCP since 3.4 — code-point based, multi-byte safe
- Negative start gives an empty string; negative length gives the rest
- For UTF-8 byte-based cutting, use $substrBytes
🏷️ Related Tags
💡 Related Cases
More hands-on cases coming soon.
📚 Related Tutorials
❓ FAQ
QAre $substr and $substrCP the same?
ASince 3.4, $substr is an alias of $substrCP — identical behavior.
QDoes cutting Chinese cause garbled text?
ANo — it counts code points, so Chinese is safe.
QCan start be negative?
AYes — a negative start returns an empty string.
