Collections

On this page

Time Series Collections

Capped Collections
Convert an Existing Collection to Capped
Document Validation
Add Validation to an Existing Collection
Listing Collections
Dropping Collections

MongoDB stores documents in collections. If a collection does not exist, MongoDB creates the collection when you first insert a document in that collection.

You can also explicitly create a collection with various options, such as setting the maximum size or the documentation validation rules.

Time Series Collections

Time series collections were added in MongoDB 5.0. You can read the documentation here.

Time series collections efficiently store sequences of measurements over a period of time. Time series data is any data that is collected over time and is uniquely identified by one or more unchanging parameters. The unchanging parameters that identify your time series data is generally your data source's metadata.

Creating a Time Series Collection

In order to create a time series collection, you must explicitly create a collection using the time series options:

opts = {
  time_series: {
    timeField: "timestamp",
    metaField: "metadata",
    granularity: "hours"
  },
  expire_after: 604800
}
db['weather', opts].create

When creating a time series collection, specify the following options:

Field	Description
`time_series[:timeField]`	Required. The name of the field which contains the date in each time series document.
`time_series[:metaField]`	Optional. The name of the field which contains metadata in each time series document. The metadata in the specified field should be data that is used to label a unique series of documents. The metadata should rarely, if ever, change.
`time_series[:granularity]`	Optional. Possible values are "seconds", "minutes", and "hours". By default, MongoDB sets the granularity to "seconds" for high-frequency ingestion.
`:expireAfterSeconds`	Optional. Enable the automatic deletion of documents in a time series collection by specifying the number of seconds after which documents expire. MongoDB deletes expired documents automatically.

See the MongoDB docs for more information about time series collection options.

Inserting into a Time Series Collection

Inserting into a time series collection is similar to inserting into a regular collection:

db['weather'].insert_many([
  {
      metadata: { sensorId: 5578, type: "temperature" },
      timestamp: Time.utc(2021, 5, 18, 0, 0, 0),
      temp: 12
  },
  {
      metadata: { sensorId: 5578, type: "temperature" },
      timestamp: Time.utc(2021, 5, 18, 4, 0, 0),
      temp: 11
  },
  {
      metadata: { sensorId: 5578, type: "temperature" },
      timestamp: Time.utc(2021, 5, 18, 8, 0, 0),
      temp: 11
  },
  {
      metadata: { sensorId: 5578, type: "temperature" },
      timestamp: Time.utc(2021, 5, 18, 12, 0, 0),
      temp: 12
  },
  {
      metadata: { sensorId: 5578, type: "temperature" },
      timestamp: Time.utc(2021, 5, 18, 16, 0, 0),
      temp: 16
  },
  {
      metadata: { sensorId: 5578, type: "temperature" },
      timestamp: Time.utc(2021, 5, 18, 20, 0, 0),
      temp: 15
  }, {
      metadata: { sensorId: 5578, type: "temperature" },
      timestamp: Time.utc(2021, 5, 19, 0, 0, 0),
      temp: 13
  },
  {
      metadata: { sensorId: 5578, type: "temperature" },
      timestamp: Time.utc(2021, 5, 19, 4, 0, 0),
      temp: 12
  },
  {
      metadata: { sensorId: 5578, type: "temperature" },
      timestamp: Time.utc(2021, 5, 19, 8, 0, 0),
      temp: 11
  },
  {
      metadata: { sensorId: 5578, type: "temperature" },
      timestamp: Time.utc(2021, 5, 19, 12, 0, 0),
      temp: 12
  },
  {
      metadata: { sensorId: 5578, type: "temperature" },
      timestamp: Time.utc(2021, 5, 19, 16, 0, 0),
      temp: 17
  },
  {
      metadata: { sensorId: 5578, type: "temperature" },
      timestamp: Time.utc(2021, 5, 19, 20, 0, 0),
      temp: 12
  }
])

Querying a Time Series Collection

Querying a time series collection is also very similar to a regular collection:

weather.find(timestamp: Time.utc(2021, 5, 18, 0, 0, 0)).first

The result of this query:

{
  "timestamp" => 2021-05-18 00:00:00 UTC,
  "metadata" => {
    "sensorId" => 5578,
    "type" => "temperature"
  },
  "temp" => 12,
  "_id" => BSON::ObjectId('624dfb87d1327a60aeb048d2')
}

Using the Aggregation Pipeline on a Time Series Collection

The aggregation pipeline can also be used for additional query functionality:

weather.aggregate([
  {
    "$project": {
      date: {
        "$dateToParts": { date: "$timestamp" }
      },
      temp: 1
    }
  },
  {
    "$group": {
      _id: {
        date: {
          year: "$date.year",
          month: "$date.month",
          day: "$date.day"
        }
      },
      avgTmp: { "$avg": "$temp" }
    }
  }
]).to_a

The example aggregation pipeline groups all documents by the date of the measurement and then returns the average of all temperature measurements that day:

[{
  "_id" => {
    "date" => {
      "year" => 2021,
      "month" => 5,
      "day" => 18
    }
  },
  "avgTmp" => 12.833333333333334
},
{
  "_id" => {
    "date" => {
      "year" => 2021,
      "month" => 5,
      "day" => 19
    }
  },
  "avgTmp" => 12.833333333333334
}]

See the MongoDB documentation on time series collections for more information.

Capped Collections

Capped collections have maximum size or document counts that prevent them from growing beyond maximum thresholds. All capped collections must specify a maximum size and may also specify a maximum document count. MongoDB removes older documents if a collection reaches the maximum size limit before it reaches the maximum document count.

To create a capped collection, use the capped: true option along with a size in bytes.

client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
collection = client[:artists, capped: true, size: 10000]
collection.create
collection.capped? # => true

Convert an Existing Collection to Capped

To convert an existing collection from non-capped to capped, use the convertToCapped command.

client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
db = client.database
db.command({ 'convertToCapped' => 'artists', 'size' => 10000 })

Document Validation

If you're using MongoDB version 3.2 or later, you can use document validation. Collections with validations compare each inserted or updated document against the criteria specified in the validator option. Depending on the validationLevel and validationAction, MongoDB either returns a warning, or refuses to insert or update the document if it fails to meet the specified criteria.

The following example creates a contacts collection with a validator that specifies that inserted or updated documents should match at least one of three following conditions:

the phone field is a string
the email field matches the regular expression
the status field is either Unknown or Incomplete.

client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'test')
client[:contacts,
    {
       'validator' => { '$or' =>
          [
             { 'phone' => { '$type' => "string" } },
             { 'email' => { '$regex' => /@mongodb\.com$/ } },
             { 'status' => { '$in' => [ "Unknown", "Incomplete" ] } }
          ]
       }
    }
  ].create

Add Validation to an Existing Collection

To add document validation criteria to an existing collection, use the collMod command. The example below demonstrates how to add a validation to the contacts collection, ensuring that all new documents must contain an age field which is a number.

client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'test')
db = client.database
db.command({ 'collMod' => 'contacts',
             'validator' =>
               { 'age' =>
                 { '$type' => "number" }
               }
           })

Listing Collections

Use collections or collection_names methods on a database objects to list collections:

client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
database = client.database
database.collections      # Returns an array of Collection objects.
database.collection_names # Returns an array of collection names as strings.

Dropping Collections

To drop a collection, call drop on the collection object.

client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
artists = client[:artists]
artists.drop

Back

Databases

Indexing