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.

Prerequisites

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

Procedures

Shard a New Time Series Collection

Connect to your sharded cluster.

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>

Confirm that sharding is enabled on your database.

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,
...

Create the collection.

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
} )

Shard an Existing Time Series Collection

Connect to your sharded cluster.

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>

Confirm that sharding is enabled on your database.

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,
...

Create a hashed index on your collection.

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" } )

Shard your collection.

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.

Additional Information

Back

Compression

Query