From e1d280610fd111484c816df7fa4c67874b61112c Mon Sep 17 00:00:00 2001
From: ltran-mdb2 <143426234+ltran-mdb2@users.noreply.github.com>
Date: Wed, 7 Feb 2024 12:22:43 -0500
Subject: [PATCH] DOCS 16485 query time series meta fields (#5542)

* DOCS-16485 time-series metafield query

* DOCS-16485 updating example

* DOCS-16485 updating example

* DOCS-16485 updating example

* DOCS-16485 updating title

* DOCS-16485 copy edits

* DOCS-16485 tech edits:

* DOCS-16485 updating limitations page

* DOCS-16485 moving example to limitations page

* DOCS-16485 moving example to best practices page and off limitations page

* DOCS-16485 fixing wording

* DOCS-16485 copy edits

* DOCS-16485 copy edits
---
 .../timeseries/timeseries-best-practices.txt  | 52 ++++++++++++++++++-
 .../core/timeseries/timeseries-procedures.txt |  3 ++
 2 files changed, 54 insertions(+), 1 deletion(-)

diff --git a/source/core/timeseries/timeseries-best-practices.txt b/source/core/timeseries/timeseries-best-practices.txt
index 82c38a8dd2d..d69b698f58e 100644
--- a/source/core/timeseries/timeseries-best-practices.txt
+++ b/source/core/timeseries/timeseries-best-practices.txt
@@ -261,4 +261,54 @@ To improve query performance, :ref:`create one or more secondary indexes
 <timeseries-add-secondary-index>` on your ``timeField`` and
 ``metaField`` to support common query  patterns. In versions 6.3 and
 higher, MongoDB creates a secondary index on the ``timeField`` and
-``metaField`` automatically.
\ No newline at end of file
+``metaField`` automatically.
+
+Query metaFields on Sub-Fields
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+MongoDB reorders the metaFields of time-series collections, which may
+cause servers to store data in a different field order than
+applications. If metaFields are objects, queries on entire metaFields
+may produce inconsistent results because metaField order may vary
+between servers and applications. To optimize queries on time-series
+metaFields, query timeseries metaFields on scalar sub-fields rather than
+entire metaFields. 
+
+The following example creates a time series collection:
+
+.. code-block:: javascript
+
+   db.weather.insertMany( [
+      {
+         "metaField": { "sensorId": 5578, "type": "temperature" },
+         "timestamp": ISODate( "2021-05-18T00:00:00.000Z" ),
+         "temp": 12
+      },
+      {
+         "metaField": { "sensorId": 5578, "type": "temperature" },
+         "timestamp": ISODate( "2021-05-18T04:00:00.000Z" ),
+         "temp": 11
+      }
+   ] )
+
+The following query on the ``sensorId`` and ``type`` scalar sub-fields
+returns the first document that matches the query criteria: 
+
+.. code-block:: javascript
+
+   db.weather.findOne( {
+      "metaField.sensorId": 5578,
+      "metaField.type": "temperature"
+   } )
+
+Example output:
+
+.. code-block:: javascript
+   :copyable: false
+
+   {
+     _id: ObjectId("6572371964eb5ad43054d572"),
+     metaField: { sensorId: 5578, type: 'temperature' },
+     timestamp: ISODate( "2021-05-18T00:00:00.000Z" ),
+     temp: 12
+   }
diff --git a/source/core/timeseries/timeseries-procedures.txt b/source/core/timeseries/timeseries-procedures.txt
index 6690c8aea1f..f1a29e75938 100644
--- a/source/core/timeseries/timeseries-procedures.txt
+++ b/source/core/timeseries/timeseries-procedures.txt
@@ -262,6 +262,9 @@ Example output:
       _id: ObjectId("62f11bbf1e52f124b84479ad")
    }
 
+For more information on time series queries, see
+:ref:`tsc-best-practice-optimize-query-performance`.
+
 Run Aggregations on a Time Series Collection
 --------------------------------------------