Docs Menu

Docs HomeDevelop ApplicationsMongoDB Manual

Shard a Time Series Collection

On this page

  • Prerequisites
  • Procedures
  • Additional Information

New in version 5.1.

Use this tutorial to shard a new or existing time series collection.

Important

Before completing this tutorial, review the sharding limitations for time series collections.

To shard a time series collection, you must deploy a sharded cluster to host the database that contains your time series collection.

1

Connect mongosh to the mongos for your sharded cluster. Specify the host and port on which the mongos is running:

mongosh --host <hostname> --port <port>
2

Run sh.status() to confirm that sharding is enabled on your database:

sh.status()

The command returns the sharding information:

--- Sharding Status ---
sharding version: {
"_id" : 1,
"minCompatibleVersion" : 5,
"currentVersion" : 6,
...
3

Use the shardCollection() method with the timeseries option.

For example:

sh.shardCollection(
"test.weather",
{ "metadata.sensorId": 1 },
{
timeseries: {
timeField: "timestamp",
metaField: "metadata",
granularity: "hours"
}
}
)

In this example, sh.shardCollection():

  • Shards a new time series collection named weather on the test database.

  • Specifies the metadata.sensorId field as the shard key.

  • Specifies a granularity of hours.

The following document contains the appropriate metadata for the collection:

db.weather.insertOne( {
"metadata": { "sensorId": 5578, "type": "temperature" },
"timestamp": ISODate("2021-05-18T00:00:00.000Z"),
"temp": 12
} )
1

Connect mongosh to the mongos for your sharded cluster. Specify the host and port on which the mongos is running:

mongosh --host <hostname> --port <port>
2

Run sh.status() to confirm that sharding is enabled on your database:

sh.status()

The command returns the sharding information:

--- Sharding Status ---
sharding version: {
"_id" : 1,
"minCompatibleVersion" : 5,
"currentVersion" : 6,
...
3

Enable sharding on your collection by creating an index that supports the shard key.

Consider a time series collection with the following properties:

db.createCollection(
"deliverySensor",
{
timeseries: {
timeField: "timestamp",
metaField: "metadata",
granularity: "minutes"
}
}
)

A sample document from the collection resembles:

db.deliverySensor.insertOne( {
"metadata": { "location": "USA", "vehicle": "truck" },
"timestamp": ISODate("2021-08-21T00:00:10.000Z"),
"speed": 50
} )

Run the following command to create a hashed index on the metadata.location field:

db.deliverySensor.createIndex( { "metadata.location" : "hashed" } )
4

Use the shardCollection() method to shard the collection.

To shard the deliverySensor collection described in the preceding step, run the following command:

sh.shardCollection( "test.deliverySensor", { "metadata.location": "hashed" } )

In this example, sh.shardCollection():

  • Shards an existing time series collection named deliverySensor on the test database.

  • Specifies the metadata.location field as the shard key. location is a sub-field of the collection's metaField.

When the collection you specify to sh.shardCollection() is a time series collection, you do not need to specify the timeseries option.

←  Build Materialized Views on Top of Time Series DataBest Practices for Time Series Collections →