DOCSP-45183-time-series-collections

source/data-formats.txt

@@ -0,0 +1,34 @@
+.. _ruby-data-formats:
+
+============
+Data Formats
+============
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :description: Learn how to use indexes by using the MongoDB Ruby Driver.
+   :keywords: ruby, query, collections, time series
+
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
+
+   Time Series Data </data-formats/time-series>
+
+Overview
+--------
+
+You can use several types of specialized data formats in your {+driver-short+}
+application. To learn how to work with these data formats, see the following
+sections:
+
+- :ref:`ruby-time-series`: Learn how to create a time series collection and interact with time series data.

source/data-formats/time-series.txt

@@ -0,0 +1,202 @@
+.. _ruby-time-series:
+
+================
+Time Series Data
+================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta:: 
+   :keywords: ruby, time series, collections, code example
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to use {+driver-short+} to store
+and interact with **time series data**.
+
+Time series data is composed of the following components:
+
+- Measured quantity
+- Timestamp for the measurement
+- Metadata that describes the measurement
+
+The following table describes sample situations for which you could store time
+series data:
+
+.. list-table::
+   :widths: 33, 33, 33
+   :header-rows: 1
+   :stub-columns: 1
+
+   * - Situation
+     - Measured Quantity
+     - Metadata
+
+   * - Recording monthly sales by industry
+     - Revenue in USD
+     - Company, country
+
+   * - Tracking weather changes
+     - Precipitation level
+     - Location, sensor type
+
+   * - Recording fluctuations in housing prices
+     - Monthly rent price
+     - Location, currency
+
+.. _ruby-time-series-create:
+
+Create a Time Series Collection
+-------------------------------
+
+.. important:: Server Version for Time Series Collections
+
+   To create and interact with time series collections, you must be
+   connected to a deployment running {+mdb-server+} 5.0 or later.
+
+To create a time series collection, you must pass an options hash that contains
+the specifications for the collection. You can specify the following specifications
+for your time series collection:
+
+- ``:timeField``: Specifies the field that stores a timestamp in each time series
+  document.
+- ``:metaField``: Specifies the field that stores metadata in each time series 
+  document.
+- ``:granularity``: Specifies the approximate time between consecutive timestamps.
+  The possible values are ``'seconds'``, ``'minutes'``, and ``'hours'``.
+- ``:bucketMaxSpanSeconds``: Sets the maximum time between timestamps in the 
+  same bucket.
+- ``:bucketRoundingSeconds``: Sets the number of seconds to round down by when 
+  MongoDB sets the minimum timestamp for a new bucket. Must be equal to 
+  ``:bucketMaxSpanSeconds``.
+
+See :manual:`Command Fields </reference/command/create/#command-fields>`
+in the {+mdb-server+} manual entry on the ``create`` command to learn more about
+these parameters. 
+
+Example
+~~~~~~~
+
+The following example uses the ``Collection#create`` method to create a time series
+collection named ``october2024`` with the ``:timeField``` option set to ``"timestamp"``:
+
+.. literalinclude:: /includes/usage-examples/time-series.rb
+   :language: ruby
+   :dedent:
+   :start-after: start-create
+   :end-before: end-create
+
+To verify that you have successfully created the collection, print a list of all
+collections in your database and filter by collection name, as shown in the following
+code:
+
+.. io-code-block::
+
+    .. input:: /includes/usage-examples/time-series.rb
+       :language: ruby
+       :start-after: start-correct
+       :end-before: end-correct
+       :dedent:
+
+    .. output::
+       :language: json
+       :visible: false
+
+       [
+         {
+           "name": "october2024", 
+           "type": "timeseries", 
+           "options": {
+             "timeseries": { 
+               "timeField": "timestamp",
+               "granularity": "seconds", 
+               "bucketMaxSpanSeconds": 3600 
+          }
+          }, 
+           "info": {
+             "readOnly": false
+           }
+          }
+        ]
+
+
+.. _ruby-time-series-write:
+
+Store Time Series Data
+----------------------
+
+You can insert data into a time series collection by using the ``insert_one``
+or ``insert_many`` method and specifying the measurement, timestamp, and 
+metadata in each inserted document.
+
+To learn more about inserting documents, see the :ref:`ruby-write-insert` guide.
+
+Example
+~~~~~~~
+
+This example inserts New York City temperature data into the ``october2024``
+time series collection created in the preceding :ref:`ruby-time-series-create`
+section. Each document contains the following fields:
+
+- ``temperature``, which stores temperature measurements in degrees Fahrenheit
+- ``location``, which stores location metadata
+- ``timestamp``, which stores the measurement timestamp
+
+.. literalinclude:: /includes/usage-examples/time-series.rb
+   :language: ruby
+   :dedent:
+   :start-after: start-insert
+   :end-before: end-insert
+
+.. TODO: add link 
+
+.. .. tip:: Formatting Dates and Times
+
+    .. To learn more about using ``datetime`` objects in {+driver-short+}, see 
+    .. :ref:`ruby-dates-times`.
+
+.. _ruby-time-series-read:
+
+Query Time Series Data
+----------------------
+
+You can use the same syntax and conventions to query data stored in a time 
+series collection as you use when performing read or aggregation operations on 
+other collections. 
+
+.. TODO: add links
+.. To learn more about these operations, see :ref:`ruby-read`
+.. and :ref:`ruby-aggregation`.
+
+.. _ruby-time-series-addtl-info:
+
+Additional Information
+----------------------
+
+To learn more about the concepts in this guide, see the following {+mdb-server+}
+manual entries:
+
+- :manual:`Time Series </core/timeseries-collections/>`
+- :manual:`Create and Query a Time Series Collection </core/timeseries/timeseries-procedures/>`
+- :manual:`Set Granularity for Time Series Data </core/timeseries/timeseries-granularity/>`
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about the methods mentioned in this guide, see the following
+API documentation:
+
+- `create <{+api-root+}/Mongo/Collection.html#create-instance_method>`__
+- `list_collections <{+api-root+}/Mongo/Database.html#list_collections-instance_method>`__
+- `insert_one <{+api-root+}/Mongo/Collection.html#insert_one-instance_method>`__
+- `insert_many <{+api-root+}/Mongo/Collection.html#insert_many-instance_method>`__
+

source/includes/usage-examples/time-series.rb

@@ -0,0 +1,35 @@
+require 'bundler/inline'
+gemfile do
+  source 'https://rubygems.org'
+  gem 'mongo'
+end
+
+
+  # start-create
+  client = Mongo::Client.new('<connection string>', database: 'weather')
+  collection_name = 'october2024'
+
+  time_series_options = { timeField: 'timestamp' }
+  database = client.database
+  database.command(
+    create: collection_name,
+    timeseries: time_series_options
+  )
+  # end-create
+
+  # start-correct
+  collections = database.list_collections(filter: { name: 'october2024' }).to_a
+  puts collections
+  # end-correct
+
+  # start-insert
+  client = Mongo::Client.new('<connection string>', database => 'your_db')
+  collection = client[:october2024]
+
+  document_list = [
+    { temperature: 77, location: "New York City", timestamp: DateTime.new(2024, 10, 22, 6, 0, 0) },
+    { temperature: 74, location: "New York City", timestamp: DateTime.new(2024, 10, 23, 6, 0, 0) }
+  ]
+
+  collection.insert_many(document_list)
+  #end-insert

source/index.txt

@@ -17,6 +17,7 @@
    Write Data </write>
    Read Data </read>
    Indexes </indexes>
+   Data Formats </data-formats>
    View the Source <https://github.com/mongodb/mongo-ruby-driver>
    API Documentation <{+api-root+}>
    What's New </whats-new>
@@ -90,6 +91,12 @@ working with data in the :ref:`ruby-get-started` tutorial.
 .. Learn how to authenticate your application and encrypt your data in the
 .. :ref:`ruby-security` section.
 
+Specialized Data Formats
+------------------------
+
+Learn how to work with specialized data formats and custom types in the
+:ref:`ruby-data-formats` section.
+
 What's New
 ----------