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

# $toString  (expression operator)

## Definition

Converts a value to a string. If the value cannot be converted to a string, [`$toString`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/tostring.md#mongodb-expression-exp.-toString) errors. If the value is null or missing, [`$toString`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/tostring.md#mongodb-expression-exp.-toString) returns null.

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

```javascript
{
   $toString: <expression>
}
```

The [`$toString`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/tostring.md#mongodb-expression-exp.-toString) takes any valid [expression.](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions)

The [`$toString`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/tostring.md#mongodb-expression-exp.-toString) is a shorthand for the following [`$convert`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/convert.md#mongodb-expression-exp.-convert) expression:

```javascript
{ $convert: { input: <expression>, to: "string" } }
```

**See also:**

- [`$convert`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/convert.md#mongodb-expression-exp.-convert)

- [`$dateToString`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/datetostring.md#mongodb-expression-exp.-dateToString)

## Behavior

The following table lists the input types that can be converted to a string:

| Input Type | Behavior |
| --- | --- |
| Array | Returns the [`Array`](https://www.mongodb.com/docs/manual/reference/mongodb-extended-json.md#mongodb-bsontype-Array) as a string. **New in version 8.3** |
| BinData | If the [`BinData`](https://www.mongodb.com/docs/manual/reference/mongodb-extended-json.md#mongodb-bsontype-Binary) is a UUID, returns the UUID as a string. Otherwise, returns the base64 encoded string value. |
| Boolean | Returns the Boolean value as a string. |
| Date | Returns the [`Date`](https://www.mongodb.com/docs/manual/reference/mongodb-extended-json.md#mongodb-bsontype-Date) as a string. |
| Decimal | Returns the [`Decimal`](https://www.mongodb.com/docs/manual/reference/mongodb-extended-json.md#mongodb-bsontype-Decimal128) value as a string. |
| Double | Returns the [`Double`](https://www.mongodb.com/docs/manual/reference/mongodb-extended-json.md#mongodb-bsontype-Double) value as a string. |
| Integer | Returns the [`Integer`](https://www.mongodb.com/docs/manual/reference/mongodb-extended-json.md#mongodb-bsontype-Int32) value as a string. |
| Long | Returns the [`Long`](https://www.mongodb.com/docs/manual/reference/mongodb-extended-json.md#mongodb-bsontype-Int64) value as a string. |
| MaxKey | Returns the [`MaxKey`](https://www.mongodb.com/docs/manual/reference/mongodb-extended-json.md#mongodb-bsontype-MaxKey) as a string. **New in version 8.3** |
| MinKey | Returns the [`MinKey`](https://www.mongodb.com/docs/manual/reference/mongodb-extended-json.md#mongodb-bsontype-MinKey) as a string. **New in version 8.3** |
| Object | Returns the object as a string. **New in version 8.3** |
| ObjectId | Returns the [`ObjectId`](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-ObjectId) value as a hexadecimal string. |
| Regular Expression | Returns the [`Regular Expression`](https://www.mongodb.com/docs/manual/reference/mongodb-extended-json.md#mongodb-bsontype-Regular-Expression) as a string. **New in version 8.3** |
| String | No operation. Returns the string value. |
| Timestamp | Returns the [`Timestamp`](https://www.mongodb.com/docs/manual/reference/mongodb-extended-json.md#mongodb-bsontype-Timestamp) as a string. **New in version 8.3** |

**See also:**

To convert strings in bases other than `10`, use [`$convert`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/convert.md#mongodb-expression-exp.-convert) with the `base` option.

The following table lists some conversion to string examples:

| Example | Results |
| --- | --- |
| `{ $toString: true }` | `"true"` |
| `{ $toString: false }` | `"false"` |
| `{ $toString: 2.5 }` | `"2.5"` |
| `{ $toString: Int32(2) }` | `"2"` |
| `{ $toString: Long(1000) }` | `"1000"` |
| `{ $toString: ObjectId("5ab9c3da31c2ab715d421285") }` | `"5ab9c3da31c2ab715d421285"` |
| `{ $toString:  ISODate("2018-03-27T16:58:51.538Z") }` | `"2018-03-27T16:58:51.538Z"` |
| `{ $toString: BinData(4, "hn3f") }` | `"hn3f"` |
| `{ $toString: /^ABC/i }` | `"/^ABC/i"` **New in version 8.3** |
| `{ $toString: new Timestamp(1565545664, 1) }` | `"Timestamp(1565545664, 1)"` **New in version 8.3** |
| `{ $toString:  [["pizza", {type: "cheese"}]] }` | `"[\"pizza\",{\"type\":\"cheese\"}]"` **New in version 8.3** |
| `{ $toString: {pizza: {type: "cheese"}} }` | `"{\"pizza\":{\"type\":\"cheese\"}}"` **New in version 8.3** |
| `{ $toString: MinKey }` | `"MinKey"` **New in version 8.3** |
| `{ $toString: MaxKey }` | `"MaxKey"` **New in version 8.3** |

## Example

Create a collection `orders` with the following documents:

```javascript
db.orders.insertMany( [
   { _id: 1, item: "apple",  qty: 5, zipcode: 93445 },
   { _id: 2, item: "almonds", qty: 2, zipcode: "12345-0030" },
   { _id: 3, item: "peaches",  qty: 5, zipcode: 12345 },
] )
```

The following aggregation operation on the `orders` collection converts the `zipcode` to string before sorting by the string value:

```javascript
// Define stage to add convertedZipCode field with the converted zipcode value

zipConversionStage = {
   $addFields: {
      convertedZipCode: { $toString: "$zipcode" }
   }
};

// Define stage to sort documents by the converted zipcode

sortStage = {
   $sort: { "convertedZipCode": 1 }
};

db.orders.aggregate( [
  zipConversionStage,
  sortStage
] )
```

The operation returns the following documents:

```javascript
{
  _id: 3,
  item: 'peaches',
  qty: 5,
  zipcode: 12345,
  convertedZipCode: '12345'
},
{
  _id: 2,
  item: 'almonds',
  qty: 2,
  zipcode: '12345-0030',
  convertedZipCode: '12345-0030'
},
{
  _id: 1,
  item: 'apple',
  qty: 5,
  zipcode: 93445,
  convertedZipCode: '93445'
}
```

**Note:**

If the conversion operation encounters an error, the aggregation operation stops and throws an error. To override this behavior, use [`$convert`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/convert.md#mongodb-expression-exp.-convert) instead.