Edit and restructure time series docs #3461

marciw · 2025-10-13T21:43:45Z

(Replaces #3222, which was an ominshambles)

This PR restructures and edits time series data stream docs as part of #1502.

❗ Notes for reviewers:

Changes were approved by Product and Engineering in Edit time series docs for clarity #3222 🙈
The content is "MVP" quality overall. More improvements coming soon via the follow-up issue, including reconciling the time series section with recent similar changes to the general data stream docs
The various applies_to thingies could probably be better; I am committed to maintaining the thinnest of grasps on applies_to metadata

Summary of changes:

Accuracy updates by SME reviewers/contributors
Many edits for clarity, conciseness, and user focus
Mentions of new ES|QL TS command (which was one of the primary motivators for cleaning up this section)
See also Consolidate time series downsampling docs #2274 and Add time series data stream quickstart #2742

github-actions · 2025-10-13T21:46:00Z

🔍 Preview links for changed docs

marciw · 2025-10-13T21:53:39Z

manage-data/data-store/data-streams/tsds-ingest-otlp.md

Note for reviewers: The OTLP page was added in #3360 (written by @felixbarny)

Slated for more improvements in #3179

marciw · 2025-10-13T21:56:41Z

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

Note for reviewers: This is a new page, but the content isn't new. It used to be part of the main/overview page. We decided to split off the content because it's sort of advanced/extra.

Includes a round of techwriterly edits

"Techwriterly" 😄

florent-leborgne · 2025-10-14T08:05:25Z

I really like seeing advanced topics explicitly gathered together 👏

kilfoyle · 2025-10-14T13:52:44Z

manage-data/data-store/data-streams/reindex-tsds.md

-3. Run the reindex operation to completion.
-4. Revert the overridden index settings in the destination index template.
-5. Invoke the `rollover` api to create a new backing index that can receive new documents.
+These high-level steps summarize the process of reindexing a time series data stream. Each step is detailed in later sections.


Suggested change

These high-level steps summarize the process of reindexing a time series data stream. Each step is detailed in later sections.

These high-level steps summarize the process of reindexing a time series data stream. Each step is detailed in a later section.

I assume each step is detailed in a single later section, but please ignore if I've got that wrong.

kilfoyle · 2025-10-14T13:57:24Z

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

+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.

-While optional, we recommend using {{ilm-init}} to automate the management of your TSDS’s backing indices. {{ilm-init}} requires an index lifecycle policy.
+For best results, specify a `max_age` for the `rollover` action in the policy. This nesures 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.


Suggested change

For best results, specify a `max_age` for the `rollover` action in the policy. This nesures 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.

For best results, specify a `max_age` 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.

kilfoyle · 2025-10-14T13:58:55Z

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

+        - Set `"lifecycle": { "enabled": true }`. 
+        - If you created an ILM policy in [step 1](#tsds-ilm-policy), reference it with `index.lifecycle.name`.
+    - **Other settings**  (optional): Additional 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.
+- **Priority:** Set the priority higher than `200`, to avoid [collisions](/manage-data/data-store/templates.md#avoid-index-pattern-collisions) with built-in templates.


Suggested change

- **Priority:** Set the priority higher than `200`, to avoid [collisions](/manage-data/data-store/templates.md#avoid-index-pattern-collisions) with built-in templates.

- **Priority:** Set the priority higher than `200` to avoid [collisions](/manage-data/data-store/templates.md#avoid-index-pattern-collisions) with built-in templates.

kilfoyle · 2025-10-14T14:02:33Z

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

-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 only belong to one time series. A 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 and metric fields, plus an internal `_tsid` metadata field.


Suggested change

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.

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.

kilfoyle

LGTM! 🦕
This looks great @marciw! The new layout is a big improvement.

shainaraskas · 2025-10-14T17:05:03Z

manage-data/data-store/data-streams/tsds-ingest-otlp.md

+applies_to:
+  stack: preview 9.2
+  deployment:
+    self:


is this accurate? the endpoint only works for self-managed deployments? I see references to elastic cloud below but I'm not sure what the relationship is between the note and the page

@theletterf did you happen to check this when reviewing the original PR? #3360

Yes, we specifically want to document that the ES OLTP endpoint is for self-managed only. For Cloud, we link to the Cloud OTLP Endpoint in the important section.

@marciw might be worth explaining a little in the important note the takeaway for self-managed folks

leemthompo

💅 I had to dig very deep for the nittiest of nits :)

leemthompo · 2025-10-15T13:16:39Z

manage-data/data-store/data-streams/query-downsampled-data.md

  stack: ga
  serverless: ga
-navigation_title: "Query downsampled data"
+navigation_title: "Querying"


Can't suggest a change on the H1 itself, but maybe SEO-wise it should be # Querying downsampled data in {{es}}

But probably not even necessary as we have Elasticsearch product metadata 🤷

leemthompo · 2025-10-15T13:17:54Z

manage-data/data-store/data-streams/reindex-tsds.md

+# Reindex a time series data stream [tsds-reindex]

-## Introduction [tsds-reindex-intro]
+Reindexing allows you to copy documents from an old [time series data stream (TSDS)](/manage-data/data-store/data-streams/time-series-data-stream-tsds.md) to a new one. All data streams support reindexing, but time series data streams require special handling due to their time-bound backing indices and strict timestamp acceptance windows.


Suggested change

Reindexing allows you to copy documents from an old [time series data stream (TSDS)](/manage-data/data-store/data-streams/time-series-data-stream-tsds.md) to a new one. All data streams support reindexing, but time series data streams require special handling due to their time-bound backing indices and strict timestamp acceptance windows.

Reindexing allows you to copy documents from an existing [time series data stream (TSDS)](/manage-data/data-store/data-streams/time-series-data-stream-tsds.md) to a new one. All data streams support reindexing, but time series data streams require special handling due to their time-bound backing indices and strict timestamp acceptance windows.

nit: ageist

leemthompo · 2025-10-15T13:20:48Z

manage-data/data-store/data-streams/reindex-tsds.md

+The destination data stream is now ready to accept new documents.

-Note that the initial backing index can still accept documents within the range of timestamps derived from the source data stream. If this is not desired, mark it as [read-only](elasticsearch://reference/elasticsearch/index-settings/index-block.md#index-blocks-read-only) explicitly.
+## Related resources


Edit and restructure time series docs

1a34c33

marciw mentioned this pull request Oct 13, 2025

Edit time series docs for clarity #3222

Closed

2 tasks

github-actions bot deployed to docs-preview October 13, 2025 21:44 View deployment

update PR number in redirects.yml

268915f

github-actions bot deployed to docs-preview October 13, 2025 21:48 View deployment

marciw marked this pull request as ready for review October 13, 2025 21:51

marciw requested review from a team as code owners October 13, 2025 21:51

marciw commented Oct 13, 2025

View reviewed changes

kilfoyle reviewed Oct 14, 2025

View reviewed changes

kilfoyle approved these changes Oct 14, 2025

View reviewed changes

shainaraskas reviewed Oct 14, 2025

View reviewed changes

leemthompo approved these changes Oct 15, 2025

View reviewed changes

	These high-level steps summarize the process of reindexing a time series data stream. Each step is detailed in later sections.
	These high-level steps summarize the process of reindexing a time series data stream. Each step is detailed in a later section.

	For best results, specify a `max_age` for the `rollover` action in the policy. This nesures 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.
	For best results, specify a `max_age` 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.

	- Priority: Set the priority higher than `200`, to avoid [collisions](/manage-data/data-store/templates.md#avoid-index-pattern-collisions) with built-in templates.
	- Priority: Set the priority higher than `200` to avoid [collisions](/manage-data/data-store/templates.md#avoid-index-pattern-collisions) with built-in templates.

	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.
	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.

	Reindexing allows you to copy documents from an old [time series data stream (TSDS)](/manage-data/data-store/data-streams/time-series-data-stream-tsds.md) to a new one. All data streams support reindexing, but time series data streams require special handling due to their time-bound backing indices and strict timestamp acceptance windows.
	Reindexing allows you to copy documents from an existing [time series data stream (TSDS)](/manage-data/data-store/data-streams/time-series-data-stream-tsds.md) to a new one. All data streams support reindexing, but time series data streams require special handling due to their time-bound backing indices and strict timestamp acceptance windows.

Edit and restructure time series docs #3461

Are you sure you want to change the base?

Edit and restructure time series docs #3461

Conversation

marciw commented Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

florent-leborgne commented Oct 14, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kilfoyle left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

leemthompo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

marciw commented Oct 13, 2025 •

edited

Loading

github-actions bot commented Oct 13, 2025 •

edited

Loading