/ /

/ /

$toString (aggregation)

Definition

$toString

Converts a value to a string. If the value cannot be converted to a string, $toString errors. If the value is null or missing, $toString returns null.

$toString has the following syntax:

{
   $toString: <expression>
}

The $toString takes any valid expression.

The $toString is a shorthand for the following $convert expression:

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

Tip

Behavior

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

Input Type	Behavior
Array	Returns the `Array` as a string. New in version 8.3.
BinData	Returns the `BinData` as a string.
Boolean	Returns the Boolean value as a string.
Date	Returns the `Date` as a string.
Decimal	Returns the `Decimal` value as a string.
Double	Returns the `Double` value as a string.
Integer	Returns the `Integer` value as a string.
Long	Returns the `Long` value as a string.
MaxKey	Returns the `MaxKey` as a string. New in version 8.3.
MinKey	Returns the `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` value as a hexadecimal string.
Regular Expression	Returns the `Regular Expression` as a string. New in version 8.3.
String	No operation. Returns the string value.
Timestamp	Returns the `Timestamp` as a string. New in version 8.3.

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:

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:

// 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:

{
  _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 instead.

Back

$toObjectId

$toLower