Skip to content

Document index.dimensions-based routing #3229

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 3 commits into from
Closed

Document index.dimensions-based routing #3229

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a00a352
Document index.dimensions-based routing
felixbarny Sep 30, 2025
86e5bd3
Apply suggestions from code review
felixbarny Sep 30, 2025
65fc86e
Clarify routing strategies for TSDS backing indices in documentation
felixbarny Sep 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 16 additions & 2 deletions manage-data/data-store/data-streams/time-series-data-stream-tsds.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -198,12 +198,26 @@

### Dimension-based routing [dimension-based-routing]

Within each TSDS backing index, {{es}} uses the [`index.routing_path`](elasticsearch://reference/elasticsearch/index-settings/time-series.md#index-routing-path) index setting to route documents with the same dimensions to the same shards.
Within each TSDS backing index, {{es}} uses one of the following strategies to route documents with the same dimensions to the same shards.

When you create the matching index template for a TSDS, you must specify one or more dimensions in the `index.routing_path` setting. Each document in a TSDS must contain one or more dimensions that match the `index.routing_path` setting.
1. Based on the internally managed `index.dimensions` index setting (preferred). Available as of stack version 9.2.
2. Based on the [`index.routing_path`](elasticsearch://reference/elasticsearch/index-settings/time-series.md#index-routing-path) index setting (as a fallback).

The `index.dimensions`-based strategy uses a list of dimension paths that's automatically kept up-to-date and is not user-configurable.
When active, the routing decision will be made based on all dimension fields, instead of only those defined statically via the `index.routing_path` setting.
This strategy is only available on data streams with no dynamic templates setting `time_series_dimension: true`.
It is used by default if applicable and improves the ingest performance as dimensions only need to be processed once for the purposes of routing and creating the `_tsid` field.

This strategy can be disabled by setting [`index.index_dimensions_tsid_strategy_enabled`](elasticsearch://reference/elasticsearch/index-settings/time-series.md#index-dimensions-tsid-strategy-enabled) to `false`,

Check failure on line 211 in manage-data/data-store/data-streams/time-series-data-stream-tsds.md

View workflow job for this annotation

GitHub Actions / preview / build 

'reference/elasticsearch/index-settings/time-series.md' has no anchor named: '#index-dimensions-tsid-strategy-enabled'.
or by manually setting `index.routing_path`.

To use the `index.routing_path`-based strategy,
you must specify one or more dimensions in the `index.routing_path` setting. Each document in a TSDS must contain one or more dimensions that match the `index.routing_path` setting.

The `index.routing_path` setting accepts wildcard patterns (for example `dim.*`) and can dynamically match new fields. However, {{es}} will reject any mapping updates that add scripted, runtime, or non-dimension fields that match the `index.routing_path` value.

The following applies to both strategies:

[Pass-through](elasticsearch://reference/elasticsearch/mapping-reference/passthrough.md#passthrough-dimensions) fields may be configured as dimension containers. In this case, their sub-fields get included to the routing path automatically.

TSDS documents don’t support a custom `_routing` value. Similarly, you can’t require a `_routing` value in mappings for a TSDS.
Expand Down
Loading