Docs Menu

mongosh Data Types

On this page

MongoDB Server stores data using the BSON format which supports some additional data types that are not available using the JSON format. Compared to the legacy mongo shell, MongoDB Shell (mongosh) has type handling which is better aligned with the default types used by the MongoDB drivers.

This document highlights changes in type usage between mongosh and the legacy mongo shell. See the Extended JSON reference for additional information on supported types.

mongosh provides various methods to return the date, either as a string or as a Date object:

  • Date() method which returns the current date as a string.
  • new Date() constructor which returns a Date object using the ISODate() wrapper.
  • ISODate() constructor which returns a Date object using the ISODate() wrapper.

mongosh provides the ObjectId() wrapper class around the ObjectId data type. To generate a new ObjectId, use the following operation in mongosh:

new ObjectId
Tip
See also:

If a number can be converted to a 32-bit integer, mongosh will store it as Int32. If not, mongosh defaults to storing the number as a Double. Numerical values that are stored as Int32 in mongosh would have been stored by default as Double in the mongo shell.

The Int32() constructor can be used to explicitly specify 32-bit integers.

db.types.insertOne(
{
"_id": 1,
"value": Int32("1"),
"expectedType": "Int32"
}
)
Warning

Default Int32 and Double types may be stored inconsistently if you connect to the same collection using both mongosh and the legacy mongo shell.

The Long() constructor can be used to explicitly specify a 64-bit integer.

db.types.insertOne(
{
"_id": 3,
"value": Long("1"),
"expectedType": "Long"
}
)
Note

In the legacy mongo shell NumberLong() accepted either a string or integer value. In mongosh, NumberLong() only accepts string values. Long() provides methods to manage conversions to and from 64-bit values.

Decimal128() values are 128-bit decimal-based floating-point numbers that emulate decimal rounding with exact precision.

This functionality is intended for applications that handle monetary data, such as financial, tax, and scientific computations.

The Decimal128 BSON type uses the IEEE 754 decimal128 floating-point numbering format which supports 34 decimal digits (i.e. significant digits) and an exponent range of −6143 to +6144.

db.types.insertOne(
{
"_id": 5,
"value": Decimal128("1"),
"expectedType": "Decimal128"
}
)
Note

To use the Decimal128 data type with a MongoDB driver, be sure to use a driver version that supports it.

Values of the Decimal128 type are compared and sorted with other numeric types based on their actual numeric value. Numeric values of the binary-based Double type generally have approximate representations of decimal-based values and may not be exactly equal to their decimal representations.

MongoDB uses a BSON Timestamp internally in the oplog. The Timestamp type works similarly to the Java Timestamp type. Use the Date type for operations involving dates.

A Timestamp signature has two optional parameters.

Timestamp( { "t": <integer>, "i": <integer> } )
Parameter
Type
Default
Definition
t
integer
Current time since UNIX epoch.
Optional. A time in seconds.
i
integer
1
Optional. Used for ordering when there are multiple operations within a given second. i has no effect if used without t.

For usage examples, see Timestamp a New Document, Create a Custom Timestamp.

Use the $type query operator or examine the object constructor to determine types.

The Javascript typeof operator returns generic values such as number or object rather than the more specific Int32 or ObjectId.

Javascript's instanceof operator is not reliable. For example, instanceof assigns BSON values in a server response to a different base class than user supplied values.

For usage examples, see Type Checking with $type() and Type Checking with a Constructor.

To return the date as a string, use the Date() method, as in the following example:

var myDateString = Date();

To print the value of the variable, type the variable name in the shell, as in the following:

myDateString

The result is the value of myDateString:

Wed Dec 19 2012 01:03:25 GMT-0500 (EST)

To verify the type, use the typeof operator, as in the following:

typeof myDateString

The operation returns string.

mongosh wraps objects of Date type with the ISODate helper; however, the objects remain of type Date.

The following example uses both the new Date() constructor and the ISODate() constructor to return Date objects.

var myDate = new Date();
var myDateInitUsingISODateWrapper = ISODate();

You can use the new operator with the ISODate() constructor as well.

To print the value of the variable, type the variable name in the shell, as in the following:

myDate

The result is the Date value of myDate wrapped in the ISODate() helper:

ISODate("2012-12-19T06:01:17.171Z")

To verify the type:

var myDate = ISODate("2021-03-21T06:00:00.171Z")
Object.prototype.toString.call(myDate) === "[object Date]"

The operation returns true.

Consider the types collection:

{ _id: 1, value: 1, expectedType: 'Int32' },
{ _id: 2, value: Long("1"), expectedType: 'Long' },
{ _id: 3, value: 1.01, expectedType: 'Double' },
{ _id: 4, value: Decimal128("1.01"), expectedType: 'Decimal128' },
{ _id: 5, value: 3200000001, expectedType: 'Double' }

This table shows the results of the db.types.find( <QUERY> ) command for the corresponding <QUERY>. The type names and aliases are given on the BSON types page.

Query
Results
{
"value":
{
$type: "int"
}
}
{
_id: 1,
value: 1,
expectedType: 'Int32'
}
{
"value":
{
$type: "long"
}
}
{
_id: 2,
value: Long("1"),
expectedType: 'Long'
}
{
"value":
{
$type: "decimal"
}
}
{
_id: 4,
value: Decimal128("1"),
expectedType: 'Decimal128'
}
{
"value":
{
$type: "double"
}
}
{
_id: 3,
value: 1.01,
expectedType: 'Double'
}
{
_id: 5,
value: 3200000001,
expectedType: 'Double'
}
{
"value":
{
$type: "number"
}
}
{
_id: 1,
value: 1,
expectedType: 'Int32'
}
{
_id: 2,
value: Long("1"),
expectedType: 'Long'
}
{
_id: 3,
value: 1.01,
expectedType: 'Double'
}
{
_id: 4,
value: Decimal128("1.01"),
expectedType: 'Decimal128'
}
{
_id: 5,
value: 3200000001,
expectedType: 'Double'
}
{
"value": 1.01
}
{
_id: 3,
value: 1.01,
expectedType: 'Double'
}
{
"value": 1
}
{
_id: 1,
value: 1,
expectedType: 'Int32'
}
{
_id: 2,
value: Long("1"),
expectedType: 'Long'
}

The query { "value": 1.01 } implicitly searches for the Double representation of 1.01. Document _id: 4 is a Decimal128 so it is not selected.

Note, however, that { "value": 1 } returns both Int32 and Long types.

Consider the typeExample collection. This collection consists of two identical documents, { "a": 1 }. The first document was created in the legacy mongo shell, the second document was created in mongosh.

We can use the $type operator in an aggregation pipeline to see the type that was assigned in each shell.

db.typeExample.aggregate(
[
{
$project:
{
"valueType":
{
"$type": "$a"
},
"_id": 0
}
}
]
)

In the first document, created in the legacy mongo shell, the value was stored as a double. In the mongosh document the value was stored as type int.

[
{
valueType: 'double' // inserted in legacy mongo shell
},
{
valueType: 'int' // inserted in mongosh
}
]

Use Timestamp() without parameters to insert multiple documents using the default settings:

db.flights.insertMany(
[
{ arrival: "true", ts: Timestamp() },
{ arrival: "true", ts: Timestamp() },
{ arrival: "true", ts: Timestamp() }
]
)

Run db.flights.find({}) to see the timestamps. Notice that even though all three entries were stamped in the same second, the interval was incremented on each one.

[
{
_id: ObjectId("6114216907d84f5370391919"),
arrival: 'true',
ts: Timestamp({ t: 1628709225, i: 1 })
},
{
_id: ObjectId("6114216907d84f537039191a"),
arrival: 'true',
ts: Timestamp({ t: 1628709225, i: 2 })
},
{
_id: ObjectId("6114216907d84f537039191b"),
arrival: 'true',
ts: Timestamp({ t: 1628709225, i: 3 })
}
]

Use custom parameters to insert multiple documents with a specific Timestamp.

This operation inserts three documents into the flights collection and uses the UNIX epoch value 1627811580 to set the ts times to 9:53 GMT on August 1, 2021.

db.flights.insertMany(
[
{ arrival: "true", ts: Timestamp(1627811580, 10) },
{ arrival: "true", ts: Timestamp(1627811580, 20) },
{ arrival: "true", ts: Timestamp(1627811580, 30) }
]
)

The resulting documents look like this:

[
{
_id: ObjectId("6123d8315e6bba6f61a1031c"),
arrival: 'true',
ts: Timestamp({ t: 1627811580, i: 10 })
},
{
_id: ObjectId("6123d8315e6bba6f61a1031d"),
arrival: 'true',
ts: Timestamp({ t: 1627811580, i: 20 })
},
{
_id: ObjectId("6123d8315e6bba6f61a1031e"),
arrival: 'true',
ts: Timestamp({ t: 1627811580, i: 30 })
}
]

The $type query operator accepts either a string alias or a numeric code corresponding to the data type. See BSON Types for a list of BSON data types and their corresponding numeric codes.

For example, these checks for the Decimal128 type are equivalent:

db.types.find( { "value": { $type: "decimal" } } )
db.types.find( { "value": { $type: 19 } } )

Examine the object constructor to determine the type. For example, the output of db.collection.find() is a Cursor.

var findResults = db.housing.find({"multiUnit": true} )
findResults.constructor.name // Returns the type
Give Feedback
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.