Document TSDB backfill behaviour

[lcawl]

Summary

Addresses #7252

Generative AI disclosure

1. Did you use a generative AI (GenAI) tool to assist in creating this contribution?

• Yes
• No

2. If you answered "Yes" to the previous question, please specify the tool(s) and model(s) used (e.g., Google Gemini, OpenAI ChatGPT-4, etc.).

Tool(s) and model(s) used: Cursor Grok 4.5, Composer 2.5

[github-actions]

Elastic Docs AI PR menu

Check the box to run an AI review for this pull request.

• Review docs changes (docs-review). Status: not started.

Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team.

[github-actions]

🔍 Preview links for changed docs

• manage-data/data-store/data-streams.md
• manage-data/data-store/data-streams/advanced-topics-tsds.md
• manage-data/data-store/data-streams/load-historical-tsds.md
• manage-data/data-store/data-streams/quickstart-tsds.md
• manage-data/data-store/data-streams/reindex-tsds.md
• manage-data/data-store/data-streams/run-downsampling.md
• manage-data/data-store/data-streams/set-up-tsds.md
• manage-data/data-store/data-streams/time-bound-tsds.md
• manage-data/data-store/data-streams/time-series-data-stream-tsds.md
• manage-data/lifecycle/data-stream.md

[github-actions]

Elastic Docs Style Checker (Vale)

Summary: 1 warning, 4 suggestions found

⚠️ Warnings (1): Fix when the suggestion improves clarity or correctness.

File	Line	Rule	Message
manage-data/data-store/data-streams/time-bound-tsds.md	31	Elastic.DontUse	Don't use 'just'.

💡 Suggestions (4): Optional style improvements. Apply when helpful.

File	Line	Rule	Message
manage-data/data-store/data-streams.md	39	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
manage-data/data-store/data-streams/load-historical-tsds.md	20	Elastic.WordChoice	Consider using 'deactivated, deselected, hidden, turned off, unavailable' instead of 'disabled', unless the term is in the UI.
manage-data/data-store/data-streams/time-bound-tsds.md	93	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
manage-data/lifecycle/data-stream.md	46	Elastic.WordChoice	Consider using 'run, start' instead of 'execute', unless the term is in the UI.

---

The Vale linter checks documentation changes against the Elastic Docs style guide. To use Vale locally or report issues, refer to Elastic style guide for Vale.

[gmarouli]

I think we should reconsider the recommendation on this page. I will run some experiments so we can properly update it.

[gmarouli]

I followed up on it and it can be simplified to the following steps (assuming there are no downsampled, this limitation was there anyway).

1. Enable the loading historical data.
2. Create an index template for the destination data stream, without lifecycle ideally.
3. Create the destination data stream using the create data stream API.
4. Run the reindex operation
5. Add data stream lifecycle

The past index creation will create new indices for the destination data stream. They will not be mapped 1-1 but it's still much better than loading everything in a single backing index.

Furthermore, I think it's important to mention here that if the reason of the reindex, is a major upgrade, the user should use the dedicated API the reindexed in place and not just a reindex operation.

[gmarouli]

Considering this is not available for previous versions, I expect we will list both approaches here right?

[lcawl]

I've updated that page to show those different steps in 8528123.
If that's correct, please let me know and I'll make some more improvements to the layout, test, and add the final missing code example.

[gmarouli]

Great start, I will investigate the two follow up actions I noted:

1. Set-up should also use DLM instead of ILM.
2. Reindexing needs to be reworked.

[gmarouli]

Suggested change

	You can create a {{tsds}} by [indexing a document](use-data-stream.md#add-documents-to-a-data-stream).
	The {{tsds-init}} 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 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).
	To test the following `_bulk` example, update the timestamps to within two hours of your current time.
	This update is required because data added to a {{tsds-init}} must fall within an existing backing index's [accepted time range](/manage-data/data-store/data-streams/time-bound-tsds.md#tsds-accepted-time-range). The first backing index is sized around creation time using `look_back_time` (default two hours) and `look_ahead_time`.
	You can create a {{tsds}} by explicitly using the [create a data stream]({{es-apis}}operation/operation-indices-create-data-stream) API or implicitly by [indexing a document](use-data-stream.md#add-documents-to-a-data-stream).
	The {{tsds-init}} 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, you have two options:
	1. Either turn on the past index creation and explicitly [create a data stream]({{es-apis}}operation/operation-indices-create-data-stream).
	2. Or update the timestamps to within two hours of your current time. This update is required because by default data added to a {{tsds-init}} must fall within an existing backing index's [accepted time range](/manage-data/data-store/data-streams/time-bound-tsds.md#tsds-accepted-time-range). The first backing index is sized around creation time using `look_back_time` (default two hours) and `look_ahead_time`.

[lcawl]

Is it simpler to just add that datastream creation step into the flow? Then we only have to call out the fact that the you have to update the timestamps if you didn't do the "turn on past index creation" step.

[gmarouli]

Should we define what an eligible write window is here too?

[lcawl]

The first occurrence of the term on this page links to the overview where it's explained. I think we'd only repeat it if we can make it really concise. What about this?:

{{es}} creates the past backing indices needed to store past documents as they arrive. The documents must fall within the eligible write window, which is the period of time between "current" and the data stream retention limit, or the first occurrence of a lifecycle action that makes a backing index read-only, whichever occurs first.

[gmarouli]

@lcawl we realised that changing the cluster setting is not accessible to serverless users. So for now let's keep this as a stack feature, and we will add serverless when a user will be able to enable it.