DOCSP-38307: Add time series collections page (#200)

Author: mcmorisi

source/fundamentals.txt

@@ -23,6 +23,7 @@ Fundamentals
    /fundamentals/specify-query
    /fundamentals/serialization
    /fundamentals/logging
+   /fundamentals/time-series
    /fundamentals/encrypt-fields
 
 - :ref:`Connecting to MongoDB <csharp-connection>`
@@ -37,4 +38,5 @@ Fundamentals
 - :ref:`csharp-specify-query`
 - :ref:`csharp-serialization`
 - :ref:`csharp-logging`
+- :ref:`csharp-time-series`
 - :ref:`Encrypt Fields <csharp-fle>`

source/fundamentals/time-series.txt

@@ -0,0 +1,117 @@
+.. _csharp-time-series:
+
+=======================
+Time Series Collections
+=======================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to use and interact with **time series collections** in
+MongoDB using the {+driver-long+}.
+
+Time series collections efficiently store sequences of measurements over
+a period of time. Time series data consists of any data collected over
+time, metadata that describes the measurement, and the time of the
+measurement.
+
+.. list-table::
+   :widths: 33, 33, 33
+   :header-rows: 1
+   :stub-columns: 1
+
+   * - Example
+     - Measurement
+     - Metadata
+
+   * - Sales Data
+     - Revenue
+     - Company
+
+   * - Infection Rates
+     - Amount of People Infected
+     - Location
+
+Create a Time Series Collection
+-------------------------------
+
+.. important::
+
+   Time series collections require MongoDB 5.0 or later.
+
+To create a time series collection, pass the following parameters to the
+``CreateCollection()`` method:
+
+- Name of the new collection to create
+- ``CreateCollectionOptions`` object that contains a ``TimeSeriesOptions`` object
+
+.. literalinclude:: /includes/fundamentals/code-examples/TimeSeries.cs
+   :start-after: begin-time-series
+   :end-before: end-time-series
+   :language: csharp
+   :dedent:
+
+To check if you successfully created the collection, send the
+``"listCollections"`` command to the ``RunCommand()`` method as shown in the following
+example:
+
+.. literalinclude:: /includes/fundamentals/code-examples/TimeSeries.cs
+   :start-after: begin-run-command
+   :end-before: end-run-command
+   :language: csharp
+   :dedent:
+
+Your output will look similar to the following:
+
+.. code-block:: json
+
+    {
+    "cursor":{
+        ...
+        "firstBatch":[
+            {
+                "name":"september2021",
+                "type":"timeseries",
+                "options":{
+                "timeseries":{
+                    ...
+                }
+                },
+                "info":{
+                "readOnly":false
+                }
+            },
+    ...   
+    }
+
+Query a Time Series Collection
+------------------------------
+
+To query a time series collection, follow the conventions for retrieving and aggregating
+data. For more information about these conventions, see the :ref:`csharp-retrieve` guide.
+
+Additional Information
+----------------------
+
+To learn more about the operations mentioned on this page, see the following
+Server manual guides:
+
+- :ref:`manual-timeseries-collection`
+- :ref:`manual-timeseries-collection-limitations`
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about any of the methods or types discussed in this
+guide, see the following API documentation:
+
+- `CreateCollection() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoDatabase.CreateCollection.html>`__
+- `CreateCollectionOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.CreateCollectionOptions.html>`__
+- `TimeSeriesOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.TimeSeriesOptions.html>`__
+- `RunCommand() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoDatabase.RunCommand.html>`__

source/includes/fundamentals/code-examples/TimeSeries.cs

@@ -0,0 +1,30 @@
+using MongoDB.Bson;
+using MongoDB.Bson.Serialization.Attributes;
+using MongoDB.Bson.Serialization.Conventions;
+using MongoDB.Driver;
+
+public class TimeSeries
+{
+    // Replace with your connection string
+    private const string MongoConnectionString = "<YOUR_CONNECTION_STRING>";
+
+    public static void Main(string[] args)
+    {   
+        var mongoClient = new MongoClient(MongoConnectionString);
+        
+        // begin-time-series
+        var database = mongoClient.GetDatabase("fall_weather");
+        var tsOptions = new TimeSeriesOptions("temperature");
+
+        // Creates a time series collection that stores "temperature" values over time
+        var collOptions = new CreateCollectionOptions { TimeSeriesOptions = tsOptions };
+        database.CreateCollection("september2021", collOptions);
+        // end-time-series
+        
+        // begin-run-command
+        var commandResult = database.RunCommand<BsonDocument>(new BsonDocument("listCollections", 1 ));
+        Console.WriteLine(commandResult.ToJson());
+        // end-run-command
+    }
+
+}