DOCSP-19062 time series (#91)

kyuan-mongodb · web-flow · commit 312196820c4c · 2022-03-30T12:01:46.000-04:00
* added time series page
diff --git a/snooty.toml b/snooty.toml
@@ -13,6 +13,7 @@ intersphinx = [
 ]
 
 [constants]
+driver-long = "MongoDB Go Driver"
 docs-branch = "master" # always set this to the docs branch (i.e. master, 1.7, 1.8, etc.)
 version = "v1.8.4" # always set this to the driver branch (i.e. v1.7.0, v1.8.0, etc.)
 example = "https://raw.githubusercontent.com/mongodb/docs-golang/{+docs-branch+}/source/includes/usage-examples/code-snippets"
diff --git a/source/compatibility.txt b/source/compatibility.txt
@@ -5,7 +5,7 @@ MongoDB Compatibility
 ~~~~~~~~~~~~~~~~~~~~~
 
 The following compatibility table specifies the recommended version(s) of the
-MongoDB Go Driver for use with a specific version of MongoDB.
+{+driver-long+} for use with a specific version of MongoDB.
 
 The first column lists the driver version(s).
 
diff --git a/source/fundamentals.txt b/source/fundamentals.txt
@@ -13,6 +13,7 @@ Fundamentals
    /fundamentals/auth
    /fundamentals/bson
    /fundamentals/crud
+   /fundamentals/time-series
 
 ..
   /fundamentals/enterprise-auth
diff --git a/source/fundamentals/context.txt b/source/fundamentals/context.txt
@@ -13,7 +13,7 @@ Context
 Overview
 --------
 
-The MongoDB Go Driver uses the `context package
+The {+driver-long+} uses the `context package
 <https://pkg.go.dev/context>`__ from Go's standard library to allow
 applications to signal timeouts and cancellations for any **blocking function**
 call. A blocking function relies on an external event, such as a network
diff --git a/source/fundamentals/crud.txt b/source/fundamentals/crud.txt
@@ -9,7 +9,6 @@ CRUD Operations
 
    /fundamentals/crud/read-operations
    /fundamentals/crud/write-operations
-   /fundamentals/crud/query-document
    /fundamentals/crud/compound-operations
 
 CRUD (Create, Read, Update, Delete) operations enable you to work with
diff --git a/source/fundamentals/crud/compound-operations.txt b/source/fundamentals/crud/compound-operations.txt
@@ -310,7 +310,7 @@ Additional Information
 For more information on performing the operations mentioned, see the
 following guides:
 
-- :doc:`Specify a Query </fundamentals/crud/query-document>`
+- :ref:`query_document_golang`
 - :doc:`Retrieve Data </fundamentals/crud/read-operations/retrieve>`
 - :doc:`Delete a Document </fundamentals/crud/write-operations/delete>`
 - :doc:`Update or Replace a Document </fundamentals/crud/write-operations/change-a-document>`
diff --git a/source/fundamentals/crud/read-operations.txt b/source/fundamentals/crud/read-operations.txt
@@ -4,6 +4,7 @@ Read Operations
 
 .. default-domain:: mongodb
 
+- :doc:`/fundamentals/crud/read-operations/query-document`
 - :doc:`/fundamentals/crud/read-operations/count`
 - :doc:`/fundamentals/crud/read-operations/retrieve`
 - :doc:`/fundamentals/crud/read-operations/cursor`
@@ -20,6 +21,7 @@ Read Operations
 .. toctree::
    :caption: Read Operations
    
+   /fundamentals/crud/read-operations/query-document
    /fundamentals/crud/read-operations/count
    /fundamentals/crud/read-operations/retrieve
    /fundamentals/crud/read-operations/cursor
diff --git a/source/fundamentals/crud/read-operations/count.txt b/source/fundamentals/crud/read-operations/count.txt
@@ -191,7 +191,7 @@ Additional Information
 For more information on the operations mentioned, see the following
 guides:
 
-- :doc:`Specify a Query </fundamentals/crud/query-document>`
+- :ref:`query_document_golang`
 - :doc:`Skip Returned Results </fundamentals/crud/read-operations/skip>`
 - :doc:`Limit the Number of Returned Results </fundamentals/crud/read-operations/limit>`
 
diff --git a/source/fundamentals/crud/read-operations/distinct.txt b/source/fundamentals/crud/read-operations/distinct.txt
@@ -105,7 +105,7 @@ For a runnable example of retrieving distinct values, see the
 usage example.
 
 For information about construting a query filter, see the
-:doc:`Specify a Query </fundamentals/crud/query-document>` guide.
+:ref:`query_document_golang` guide.
 
 API Documentation
 ~~~~~~~~~~~~~~~~~
diff --git a/source/fundamentals/crud/read-operations/limit.txt b/source/fundamentals/crud/read-operations/limit.txt
@@ -146,7 +146,7 @@ Additional Information
 For more information about the operations mentioned, see the following
 guides:
 
-- :doc:`Specify a Query </fundamentals/crud/query-document>`
+- :ref:`query_document_golang`
 - :doc:`Retrieve Data </fundamentals/crud/read-operations/retrieve>`
 - :doc:`Sort Results </fundamentals/crud/read-operations/sort>`
 - :doc:`Skip Returned Results </fundamentals/crud/read-operations/skip>`
diff --git a/source/fundamentals/crud/read-operations/project.txt b/source/fundamentals/crud/read-operations/project.txt
@@ -163,7 +163,7 @@ Additional Information
 For more information about the operations mentioned, see the following
 guides:
 
-- :doc:`Specify a Query </fundamentals/crud/query-document>`
+- :ref:`query_document_golang`
 - :doc:`Retrieve Data </fundamentals/crud/read-operations/retrieve>`
 - :doc:`Compound Operations </fundamentals/crud/compound-operations>`
 
diff --git a/source/fundamentals/crud/read-operations/query-document.txt b/source/fundamentals/crud/read-operations/query-document.txt
diff --git a/source/fundamentals/crud/read-operations/retrieve.txt b/source/fundamentals/crud/read-operations/retrieve.txt
@@ -272,7 +272,7 @@ examples:
 For more information about the operations mentioned, see the following
 guides:
 
-- :doc:`Specify a Query </fundamentals/crud/query-document>`
+- :ref:`query_document_golang`
 - :ref:`<cursor-golang>`
 - :doc:`Skip Returned Results </fundamentals/crud/read-operations/skip>`
 - :doc:`Sort Results </fundamentals/crud/read-operations/sort>`
diff --git a/source/fundamentals/crud/read-operations/skip.txt b/source/fundamentals/crud/read-operations/skip.txt
@@ -117,7 +117,7 @@ Additional Information
 For more information about the operations mentioned, see the following
 guides:
 
-- :doc:`Specify a Query </fundamentals/crud/query-document>`
+- :ref:`query_document_golang`
 - :doc:`Retrieve Data </fundamentals/crud/read-operations/retrieve>`
 - :doc:`Sort Results </fundamentals/crud/read-operations/sort>`
 
diff --git a/source/fundamentals/crud/read-operations/sort.txt b/source/fundamentals/crud/read-operations/sort.txt
@@ -199,7 +199,7 @@ Additional Information
 For more information about the operations mentioned, see the following
 guides:
 
-- :doc:`Specify a Query </fundamentals/crud/query-document>`
+- :ref:`query_document_golang`
 - :doc:`Retrieve Data </fundamentals/crud/read-operations/retrieve>`
 - :doc:`Compound Operations </fundamentals/crud/compound-operations>`
 
diff --git a/source/fundamentals/crud/read-operations/text.txt b/source/fundamentals/crud/read-operations/text.txt
@@ -279,7 +279,7 @@ Additional Information
 For more information on the operations mentioned, see the following
 guides:
 
-- :doc:`Specify a Query </fundamentals/crud/query-document>`
+- :ref:`query_document_golang`
 - :doc:`Sort Results </fundamentals/crud/read-operations/sort>`
 - :doc:`Specify Which Fields to Return </fundamentals/crud/read-operations/project>`
 - :manual:`Text Indexes </core/index-text/>`
diff --git a/source/fundamentals/crud/write-operations/change-a-document.txt b/source/fundamentals/crud/write-operations/change-a-document.txt
@@ -295,7 +295,7 @@ following usage examples:
 For more information about the operations mentioned, see the following
 guides:
 
-- :doc:`Specify a Query </fundamentals/crud/query-document>`
+- :ref:`query_document_golang`
 - :doc:`Insert or Update in a Single Operation </fundamentals/crud/write-operations/upsert>`
 - :doc:`Compound Operations </fundamentals/crud/compound-operations>`
 - :manual:`Update Operators </reference/operator/update/#update-operators>`
diff --git a/source/fundamentals/crud/write-operations/delete.txt b/source/fundamentals/crud/write-operations/delete.txt
@@ -128,7 +128,7 @@ examples:
 For more information on performing the operations mentioned, see the
 following guides:
 
-- :doc:`Specify a Query </fundamentals/crud/query-document>`
+- :ref:`query_document_golang`
 
 For information about how the driver uses Context, see our guide on
 :doc:`Context </fundamentals/context>`.
diff --git a/source/fundamentals/crud/write-operations/insert.txt b/source/fundamentals/crud/write-operations/insert.txt
@@ -268,7 +268,7 @@ examples:
 For more information on performing the operations mentioned, see the
 following guides:
 
-- :doc:`Specify a Query </fundamentals/crud/query-document>`
+- :ref:`query_document_golang`
 
 .. - :doc:`Bulk Operations </fundamentals/crud/write-operations/bulk>`
 
diff --git a/source/fundamentals/crud/write-operations/upsert.txt b/source/fundamentals/crud/write-operations/upsert.txt
@@ -96,7 +96,7 @@ Additional Information
 For more information about the operations mentioned, see the following
 guides:
 
-- :doc:`Specify a Query </fundamentals/crud/query-document>`
+- :ref:`query_document_golang`
 - :doc:`Change a Document </fundamentals/crud/write-operations/change-a-document>`
 - :doc:`Compound Operations </fundamentals/crud/compound-operations>`
 
diff --git a/source/fundamentals/monitoring.txt b/source/fundamentals/monitoring.txt
@@ -4,4 +4,4 @@ Monitoring
 
 .. default-domain:: mongodb
 
-Monitoring with the MongoDB Go driver.
+Monitoring with the {+driver-long+}.
diff --git a/source/fundamentals/time-series.txt b/source/fundamentals/time-series.txt
@@ -0,0 +1,134 @@
+=======================
+Time Series Collections
+=======================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn about **time series collections** in
+MongoDB, and how to interact with them in the {+driver-long+}.
+
+Time series collections efficiently store sequences of measurements over
+a period of time. The collection consists of time series data with the
+following information:
+
+- Data collected over time
+- Metadata that describes the measurement
+- Date 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()`` function:
+
+- The name of the new collection to create
+- The ``TimeSeriesOptions`` object specifying at least the time field
+
+Example
+~~~~~~~
+
+The following example creates the ``spring_weather.march2022`` time series
+collection with the ``temperature`` as the time field:
+
+.. literalinclude:: /includes/fundamentals/code-snippets/timeSeries.go
+   :start-after: begin create ts coll
+   :end-before: end create ts coll
+   :emphasize-lines: 2, 5
+   :language: go
+   :dedent:
+
+To check if you created the collection, send the ``"listCollections"``
+command to the ``RunCommand()`` function:
+
+.. io-code-block::
+   :caption: Testing whether we created a time series collection.
+   :copyable: true
+
+   .. input:: /includes/fundamentals/code-snippets/timeSeriesRunCommand.go
+      :language: go
+      :linenos:
+      :emphasize-lines: 1, 4
+
+   .. output:: 
+      :linenos:
+      :emphasize-lines: 9, 11, 15
+
+      {  
+         ...
+         "cursor": {
+              "firstBatch": [
+                  {
+                      "info": {
+                          "readOnly": false
+                      },
+                      "name": "march2022",
+                      "options": {
+                          "timeseries": {
+                              ...
+                          }
+                      },
+                      "type": "timeseries"
+                  },
+          ...
+       }
+
+Query a Time Series Collection
+------------------------------
+
+To query a time series collection, use the same conventions as you
+would for :ref:`retrieving <retrieve-golang>` and aggregating data.
+
+Additional Information
+----------------------
+
+For more information on the operations mentioned, see the following
+guides:
+
+- :ref:`manual-timeseries-collection`
+- :ref:`manual-timeseries-collection-limitations`
+- :ref:`run-command-usage-example`
+- :ref:`retrieve-golang`
+
+.. TODO: db and collections, run command fundamentals page, aggregation page
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+For more information on any of the functions or types discussed in this
+guide, see the following API Documentation:
+
+- `TimeSeriesOptions <{+api+}/mongo/options#TimeSeriesOptions>`__
+- `SetTimeField() <{+api+}/mongo/options#TimeSeriesOptions.SetTimeField>`__
+- `CreateCollection() <{+api+}/mongo#Database.CreateCollection>`__
+- `SetTimeSeriesOptions() <{+api+}/mongo/options#CreateCollectionOptions.SetTimeSeriesOptions>`__
+- `RunCommand() <{+api+}/mongo#Database.RunCommand>`__
diff --git a/source/includes/fundamentals-sections.rst b/source/includes/fundamentals-sections.rst
@@ -6,6 +6,7 @@ Fundamentals section:
 - :doc:`Authenticate with MongoDB </fundamentals/auth>`
 - :doc:`Read from and Write to MongoDB </fundamentals/crud>`
 - :doc:`Work with BSON </fundamentals/bson>`
+- :doc:`Use a Time Series Collection </fundamentals/time-series>`
 
 .. - :doc:`Specify an API Version </fundamentals/versioned-api>`
 .. - :doc:`Use the Driver's Data Formats </fundamentals/data-formats>`
diff --git a/source/includes/fundamentals/code-snippets/timeSeries.go b/source/includes/fundamentals/code-snippets/timeSeries.go
@@ -0,0 +1,57 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"log"
+	"os"
+
+	"go.mongodb.org/mongo-driver/bson"
+	"go.mongodb.org/mongo-driver/mongo"
+	"go.mongodb.org/mongo-driver/mongo/options"
+)
+
+func main() {
+	var uri string
+	if uri = os.Getenv("MONGODB_URI"); uri == "" {
+		log.Fatal("You must set your 'MONGODB_URI' environmental variable. See\n\t https://docs.mongodb.com/drivers/go/current/usage-examples/")
+	}
+
+	client, err := mongo.Connect(context.TODO(), options.Client().ApplyURI(uri))
+
+	if err != nil {
+		panic(err)
+	}
+	defer func() {
+		if err = client.Disconnect(context.TODO()); err != nil {
+			panic(err)
+		}
+	}()
+
+	client.Database("spring_weather").Collection("temperature").Drop(context.TODO())
+
+	// begin create ts coll
+	db := client.Database("spring_weather")
+	tso := options.TimeSeries().SetTimeField("temperature")
+	opts := options.CreateCollection().SetTimeSeriesOptions(tso)
+
+	db.CreateCollection(context.TODO(), "march2022", opts)
+	// end create ts coll
+
+	// begin check ts coll
+	command := bson.D{{"listCollections", 1}}
+	var result bson.M
+	
+	commandErr := db.RunCommand(context.TODO(), command).Decode(&result)
+	if commandErr != nil {
+		panic(commandErr)
+	}
+
+	output, outputErr := json.MarshalIndent(result, "", "    ")
+	if outputErr != nil {
+		panic(outputErr)
+	}
+	fmt.Printf("%s\n", output)
+	// end check ts coll
+}
diff --git a/source/includes/fundamentals/code-snippets/timeSeriesRunCommand.go b/source/includes/fundamentals/code-snippets/timeSeriesRunCommand.go
@@ -0,0 +1,13 @@
+command := bson.D{{"listCollections", 1}}
+var result bson.M
+	
+commandErr := db.RunCommand(context.TODO(), command).Decode(&result)
+if commandErr != nil {
+	panic(commandErr)
+}
+
+output, outputErr := json.MarshalIndent(result, "", "    ")
+if outputErr != nil {
+	panic(outputErr)
+}
+fmt.Printf("%s\n", output)
diff --git a/source/includes/language-compatibility-table-go.rst b/source/includes/language-compatibility-table-go.rst
@@ -1 +1 @@
-The MongoDB Go driver requires Go 1.10 or later.
+The {+driver-long+} requires Go 1.10 or later.
diff --git a/source/index.txt b/source/index.txt
diff --git a/source/usage-examples.txt b/source/usage-examples.txt
diff --git a/source/usage-examples/command.txt b/source/usage-examples/command.txt

Original file line number	Diff line number	Diff line change
`@@ -13,6 +13,7 @@ intersphinx = [`
`13`	`13`	`]`
`14`	`14`
`15`	`15`	`[constants]`
	`16`	`+driver-long = "MongoDB Go Driver"`
`16`	`17`	`docs-branch = "master" # always set this to the docs branch (i.e. master, 1.7, 1.8, etc.)`
`17`	`18`	`version = "v1.8.4" # always set this to the driver branch (i.e. v1.7.0, v1.8.0, etc.)`
`18`	`19`	`example = "https://raw.githubusercontent.com/mongodb/docs-golang/{+docs-branch+}/source/includes/usage-examples/code-snippets"`