> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# $substr (expression operator)

## Definition

**Deprecated since version 3.4**[`$substr`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/substr.md#mongodb-expression-exp.-substr) is now an alias for [`$substrBytes`.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/substrbytes.md#mongodb-expression-exp.-substrBytes)

Returns a substring of a string, starting at a specified index position and including the specified number of characters. The index is zero-based.

[`$substr`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/substr.md#mongodb-expression-exp.-substr) has the following syntax:

```javascript
{ $substr: [ <string>, <start>, <length> ] }
```

The arguments can be any valid [expression](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions) as long as the first argument resolves to a string, and the second and third arguments resolve to integers. For more information on expressions, see [Expressions.](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions)

## Behavior

If `<start>` is a negative number, [`$substr`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/substr.md#mongodb-expression-exp.-substr) returns an empty string `""`.

If `<length>` is a negative number, [`$substr`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/substr.md#mongodb-expression-exp.-substr) returns a substring that starts at the specified index and includes the rest of the string.

[`$substr`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/substr.md#mongodb-expression-exp.-substr) only has a well-defined behavior for strings of ASCII characters.

## Example

The following example uses the `movies` collection from the [sample\_mflix sample dataset](https://www.mongodb.com/docs/manual/sample-data/sample-mflix.md#std-label-sample-mflix).  For details on how to load this dataset into your deployment, see [Load the sample dataset.](https://www.mongodb.com/docs/manual/sample-data/load-sample-data-local.md#std-label-sample-dataset-local)

This aggregation operation uses the [`$substr`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/substr.md#mongodb-expression-exp.-substr) operator to separate the `title` value into a `titleStart` and a `titleRest`. The second expression uses a negative `<length>` to return the characters from index `3` to the end of the string:

```javascript
db.movies.aggregate( [
   { $match: { runtime: { $gt: 1000 } } },
   {
      $project:
        {
          _id: 0,
          title: 1,
          titleStart: { $substr: [ "$title", 0, 3 ] },
          titleRest: { $substr: [ "$title", 3, -1 ] }
        }
   }
] )

```

**Output:**

```javascript
[
  {
    title: 'Centennial',
    titleStart: 'Cen',
    titleRest: 'tennial'
  },
  {
    title: 'Baseball',
    titleStart: 'Bas',
    titleRest: 'eball'
  }
]

```