Address comments and suggestions from reviewers

Author: marciw

manage-data/data-store/data-streams/set-up-tsds.md

@@ -19,85 +19,13 @@ This page shows you how to set up a [time series data stream](/manage-data/data-
 - Make sure you have the following permissions:
     - [Cluster privileges](elasticsearch://reference/elasticsearch/security-privileges.md#privileges-list-cluster)
         - `manage_index_templates` for creating a template to base the TSDS on
-        - `manage_ilm` (Stack only) if you're using [index lifecycle management](#tsds-ilm-policy)
     - [Index privileges](elasticsearch://reference/elasticsearch/security-privileges.md#privileges-list-indices) 
         - `create_doc` and `create_index` for creating or converting a TSDS
         - `manage` to [roll over](#convert-existing-data-stream-to-tsds) a TSDS
 
 ## Set up a TSDS
 
 :::::{stepper}
-::::{step} Create an index lifecycle policy (optional) 
-:anchor: tsds-ilm-policy
-
-```{applies_to}
-stack: ga
-serverless: unavailable
-```
-In most cases, you can use a data stream lifecycle to manage your time series data stream. If you're using [data tiers](/manage-data/lifecycle/data-tiers.md) in {{stack}}, you can use index lifecycle management (ILM).
-
-:::{dropdown} Create an ILM policy
-
-If you're using {{stack}}, {{ilm-init}} can help you manage a time series data stream's backing indices. {{ilm-init}} requires an index lifecycle policy.
-
-For best results, specify a `max_age` criteria for the `rollover` action in the policy. This ensures the [`@timestamp` ranges](/manage-data/data-store/data-streams/time-bound-tsds.md) for the backing indices are consistent. For example, setting a `max_age` of `1d` for the `rollover` action ensures your backing indices consistently contain one day's worth of data.
-
-**Example:**
-
-```console
-PUT _ilm/policy/my-weather-sensor-lifecycle-policy
-{
-  "policy": {
-    "phases": {
-      "hot": {
-        "actions": {
-          "rollover": {
-            "max_age": "1d",
-            "max_primary_shard_size": "50gb"
-          }
-        }
-      },
-      "warm": {
-        "min_age": "30d",
-        "actions": {
-          "shrink": {
-            "number_of_shards": 1
-          },
-          "forcemerge": {
-            "max_num_segments": 1
-          }
-        }
-      },
-      "cold": {
-        "min_age": "60d",
-        "actions": {
-          "searchable_snapshot": {
-            "snapshot_repository": "found-snapshots"
-          }
-        }
-      },
-      "frozen": {
-        "min_age": "90d",
-        "actions": {
-          "searchable_snapshot": {
-            "snapshot_repository": "found-snapshots"
-          }
-        }
-      },
-      "delete": {
-        "min_age": "735d",
-        "actions": {
-          "delete": {}
-        }
-      }
-    }
-  }
-}
-```
-:::
-
-::::
-
 ::::{step} Create an index template 
 :anchor: create-tsds-index-template
 
@@ -106,9 +34,10 @@ The structure of a time series data stream is defined by an index template. Crea
 - **Index patterns:** One or more wildcard patterns matching the name of your TSDS, such as `weather-sernsors-*`. For best results, use the [data stream naming scheme](/reference/fleet/data-streams.md#data-streams-naming-scheme).
 - **Data stream object:** The template must include `"data_stream": {}`.
 - **Time series mode:** Set `index.mode: time_series`.
-- **Field mappings:** Define at least one `keyword` dimension field and typically one or more metric fields:
-    - To define a dimension, set `time_series_dimension` to `true`. Dimension fields like `counter` only increase over time. For more details, refer to [Dimensions](/manage-data/data-store/data-streams/time-series-data-stream-tsds.md#time-series-dimension).
-    - To define a metric, use the `time_series_metric` mapping parameter. Metric fields like `gauge` can increase or decrease over time. For more details, refer to [Metrics](/manage-data/data-store/data-streams/time-series-data-stream-tsds.md#time-series-metric).
+- **Field mappings:** Define at least one dimension field and typically one or more metric fields:
+    - To define a dimension, set `time_series_dimension` to `true`. For more details, refer to [Dimensions](/manage-data/data-store/data-streams/time-series-data-stream-tsds.md#time-series-dimension). 
+        - To define dimensions dynamically, you can use a pass-through object. For details, refer to [Defining sub-fields as time series dimensions](elasticsearch://reference/elasticsearch/mapping-reference/passthrough.md#passthrough-dimensions).
+    - To define a metric, use the `time_series_metric` mapping parameter. For more details, refer to [Metrics](/manage-data/data-store/data-streams/time-series-data-stream-tsds.md#time-series-metric).
     - (Optional) Define a `date` or `date_nanos` mapping for the `@timestamp` field. If you don't specify a mapping, {{es}} maps `@timestamp` as a `date` field with default options.
     * (Optional) Other index settings, such as [`index.number_of_replicas`](elasticsearch://reference/elasticsearch/index-settings/index-modules.md#dynamic-index-number-of-replicas), for the data stream's backing indices.
 - A priority higher than `200`, to avoid [collisions](/manage-data/data-store/templates.md#avoid-index-pattern-collisions) with built-in templates.
@@ -173,7 +102,7 @@ If you're using component templates with a time series data stream, check the fo
 After creating the index template, you can create a time series data stream by [indexing a document](use-data-stream.md#add-documents-to-a-data-stream). The TSDS is created automatically when you index the first document, as long as the index name matches the index template pattern. You can use a bulk API request or a POST request.
 
 :::{important}
-To test the following `_bulk` example, update the timestamps to within three hours of your current time. Data added to a TSDS must fit the [accepted time range](/manage-data/data-store/data-streams/time-bound-tsds.md#tsds-accepted-time-range).
+To test the following `_bulk` example, update the timestamps to within two hours of your current time. Data added to a TSDS must fit the [accepted time range](/manage-data/data-store/data-streams/time-bound-tsds.md#tsds-accepted-time-range).
 :::
 
 ```console
@@ -231,7 +160,7 @@ GET metrics-prod/_search
 
 You can convert an existing regular data stream to a TSDS. Follow these steps:
 
-1. Update your existing index template to include time series settings. Also update your index lifecycle policy (if any) and component templates (if any). 
+1. Update your existing index template and component templates (if any) to include time series settings. 
 2. Use the [rollover API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-rollover) to manually roll over the existing data stream's write index, to apply the changes you made in step 1:
 
 ```console
@@ -246,9 +175,11 @@ After the rollover, new backing indices will have time series functionality. Exi
 
 To control access to a TSDS, use [index privileges](elasticsearch://reference/elasticsearch/security-privileges.md#privileges-list-indices). Privileges set on a TSDS also apply to the backing indices.
 
-For an example, refer to [Data stream privileges](../../../deploy-manage/users-roles/cluster-or-deployment-auth/granting-privileges-for-data-streams-aliases.md#data-stream-privileges).
+For an example, refer to [Data stream privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/granting-privileges-for-data-streams-aliases.md#data-stream-privileges).
+
+### Set up lifecycle management
 
-% TODO Common patterns for time series data streams
+In most cases, you can use a [data stream lifecycle](/manage-data/lifecycle/data-stream.md) to manage your time series data stream. If you're using [data tiers](/manage-data/lifecycle/data-tiers.md) in {{stack}}, you can use [index lifecycle management](/manage-data/lifecycle/index-lifecycle-management.md).
 
 ## Next steps [set-up-tsds-whats-next]
 

manage-data/data-store/data-streams/time-bound-tsds.md

@@ -44,13 +44,13 @@ GET _data_stream/my-tsds
 ```
 
 ::::{tip}
-These {{ilm-init}} actions mark the source index as read-only or prevent writes for performance reasons:
+The following actions affect the writable time range of a TSDS, either because they make a backing index read-only or remove it:
  - [Delete](elasticsearch://reference/elasticsearch/index-lifecycle-actions/ilm-delete.md) 
  - [Downsample](elasticsearch://reference/elasticsearch/index-lifecycle-actions/ilm-downsample.md) 
  - [Force merge](elasticsearch://reference/elasticsearch/index-lifecycle-actions/ilm-forcemerge.md) 
  - [Read only](elasticsearch://reference/elasticsearch/index-lifecycle-actions/ilm-readonly.md)
  - [Searchable snapshot](elasticsearch://reference/elasticsearch/index-lifecycle-actions/ilm-searchable-snapshot.md) 
- - [Shrink](elasticsearch://reference/elasticsearch/index-lifecycle-actions/ilm-shrink.md) 
+ - [Shrink](elasticsearch://reference/elasticsearch/index-lifecycle-actions/ilm-shrink.md), which might then revert the read-only status at the end of the action
 
  {{ilm-cap}} will **not** proceed with executing these actions until [`index.time_series.end_time`](elasticsearch://reference/elasticsearch/index-settings/time-series.md#index-time-series-end-time) has passed.
 ::::

manage-data/data-store/data-streams/time-series-data-stream-tsds.md

@@ -19,7 +19,7 @@ Before setting up a time series data stream, make sure you're familiar with gene
 
 ## When to use a time series data stream [when-to-use-tsds]
 
-_Metrics_ consist of data point–timestamp pairs, identified by [dimension fields]() that can be used in aggregation queries. Both a regular data stream and a time series data stream can store metrics data. 
+_Metrics_ consist of data point–timestamp pairs, identified by [dimension fields](#time-series-dimension) that can be used in aggregation queries. Both a regular data stream and a time series data stream can store metrics data. 
 
 Choose a time series data stream if you typically add metrics data to {{es}} in near real-time and in `@timestamp` order. For other timestamped data, such as logs or traces, use a [logs data stream](logs-data-stream.md) or [regular data stream](/manage-data/data-store/data-streams.md).
 
@@ -38,11 +38,9 @@ A time series is a sequence of observations for a specific entity. Together, the
 :title: Time series of weather sensor readings plotted as a graph
 :::
 
-In a TSDS, each {{es}} document represents an observation, or data point, in a specific time series. Although a TSDS can contain multiple time series, a document can belong to only one time series. A single time series can't span multiple data streams.
-
 ### Time series fields
 
-Compared to a regular data stream, a TSDS uses some additional fields specific to time series:  dimension fields (required) and metric fields (optional but usually defined), plus an internal `_tsid` metadata field.
+Compared to a regular data stream, a TSDS uses some additional fields specific to time series:  dimension fields and metric fields, plus an internal `_tsid` metadata field.
 
 #### Dimensions [time-series-dimension]
 
@@ -63,62 +61,56 @@ To mark a field as a dimension, set the Boolean `time_series_dimension` mapping
 * [`unsigned_long`](elasticsearch://reference/elasticsearch/mapping-reference/number.md)
 * [`boolean`](elasticsearch://reference/elasticsearch/mapping-reference/boolean.md)
 
-:::{dropdown} Advanced field types
 To work with a flattened field, use the `time_series_dimensions` parameter to configure an array of fields as dimensions. For details, refer to [`flattened`](elasticsearch://reference/elasticsearch/mapping-reference/flattened.md#flattened-params).
 
 You can also simplify dimension definitions by using [pass-through](elasticsearch://reference/elasticsearch/mapping-reference/passthrough.md#passthrough-dimensions) fields.
-:::
 
 #### Metrics [time-series-metric]
 
-Metrics are numeric measurements that change over time. Documents in a TSDS contain one or more metric fields. 
+Metrics are numeric measurements that change over time. Documents in a TSDS typically contain one or more metric fields. 
 
 :::{tip}
 Metrics are expected to change (even if rarely or slowly), while dimensions generally remain constant.
 :::
 
 To mark a field as a metric, use the `time_series_metric` mapping parameter. This parameter ensures data is stored in an optimal way for time series analysis. The following field types support the `time_series_metric` parameter:
 
-* [`aggregate_metric_double`](elasticsearch://reference/elasticsearch/mapping-reference/aggregate-metric-double.md)
 * All [numeric field types](elasticsearch://reference/elasticsearch/mapping-reference/number.md)
+* [`aggregate_metric_double`](elasticsearch://reference/elasticsearch/mapping-reference/aggregate-metric-double.md), for internal use during downsampling (rarely user-populated)
 
 The valid values for `time_series_metric` are `counter` and `gauge`:
 
 `counter`
-:   A cumulative metric that only monotonically increases or resets to `0` (zero). For example, a count of errors or completed tasks. 
+:   A cumulative metric that only monotonically increases or resets to `0` (zero). For example, a count of errors or completed tasks that resets when a serving process restarts. 
 
 `gauge`
 :   A metric that represents a single numeric that can arbitrarily increase or decrease. For example, a temperature or available disk space. 
 
 #### `_tsid` metadata field [tsid]
 
-The `_tsid` is an automatically generated object containing the document’s dimensions. It's intended for internal {{es}} use, so in most cases you won't need to work with it.
-
-- You **can't** query or update the internal `_tsid` field.
-- You **can** use the `_tsid` in aggregations.
-- To retrieve the value of `_tsid`, use the fields parameter in a search. The `_tsid` is not included in get document responses.
-- The format of the `_tsid` field is subject to change. 
+The `_tsid` is an automatically generated object containing the document’s dimensions. It's intended for internal {{es}} use, so in most cases you won't need to work with it. The format of the `_tsid` field is subject to change. 
 
 ### Differences from a regular data stream [differences-from-regular-data-stream]
 
 A time series data stream works like a regular data stream, with some key differences:
 
 * **Time series index mode:** The matching index template for a TSDS must include a `data_stream` object with `index.mode` set to `time_series`. This option enables most TSDS-related functionality.
-* **Required fields:** In a TSDS, each document contains:
+* **Fields:** In a TSDS, each document contains:
   * A `@timestamp` field
   * One or more [dimension fields](#time-series-dimension), set with `time_series_dimension: true`  
-  * One or more [metric fields](#time-series-metric) (not strictly required, but typical for a TSDS)
-* **Document IDs:** Time series documents use two IDs: 
-    * An internal [`_tsid`](#tsid) metadata field, generated by {{es}} for each document in a TSDS and used for sorting and compression
-    * The document `_id`, a generated hash of the document's dimensions and `@timestamp` (custom `_id` values are not supported)
+  * One or more [metric fields](#time-series-metric)
+  * An auto-generated document `_id` (custom `_id` values are not supported)
 * **Backing indices:** A TSDS uses [time-bound indices](/manage-data/data-store/data-streams/time-bound-tsds.md) to store data from the same time period in the same backing index.
-* **Dimension-based routing:** The matching index template for a TSDS must contain the `index.routing_path` index setting, which specifies dimensions for routing documents to shards.
+* **Dimension-based routing:** The routing logic uses dimension fields to map data to shards, improving storage efficiency and query performance.
 * **Sorting:** A TSDS uses internal [index sorting](elasticsearch://reference/elasticsearch/index-settings/sorting.md) to order shard segments by `_tsid` and `@timestamp`, for better compression. Time series data streams do not use `index.sort.*` settings.
-* **Synthetic source:** A TSDS uses [synthetic `_source`](elasticsearch://reference/elasticsearch/mapping-reference/mapping-source-field.md#synthetic-source), which has some [restrictions](elasticsearch://reference/elasticsearch/mapping-reference/mapping-source-field.md#synthetic-source-restrictions) and [modifications](elasticsearch://reference/elasticsearch/mapping-reference/mapping-source-field.md#synthetic-source-modifications).
 
 ## Query time series data
+```{applies_to}
+stack: preview
+serverless: preview
+```
 
-You can use the {{esql}} [`TS` command](elasticsearch://reference/query-languages/esql/commands/ts.md) to query time series data streams. The `TS` command is optimized for time series data. It also enables the use of aggregation functions that efficiently process metrics per time series, before aggregating results.
+You can use the {{esql}} [`TS` command](elasticsearch://reference/query-languages/esql/commands/ts.md) (in technical preview) to query time series data streams. The `TS` command is optimized for time series data. It also enables the use of aggregation functions that efficiently process metrics per time series, before aggregating results.
 
 
 ## Next steps [tsds-whats-next]