Link Search Menu Expand Document Documentation Menu
Documentation

Workload group settings

Introduced 3.7

OpenSearch operation is normally controlled by cluster-wide defaults and per-request parameters. In a multi-tenant cluster, you may need to apply different limits to different tenants. Without workload group settings, you can either lower the defaults for everyone, which restricts tenants that operate within limits, or trust every client to send the correct request parameters, which is difficult to enforce.

Workload group settings solve this problem by letting you attach group-specific configuration directly to a workload group. When a request is routed to a group, the group’s settings are applied automatically, letting you define guardrails per tenant:

  • Apply stricter limits to resource-intensive or unverified tenants while keeping generous defaults for others, all without modifying cluster settings.
  • Limits are bound to the workload group, so they apply to every request routed to the group regardless of which client sent it. No client-side configuration is required.
  • A workload group can optionally take precedence over lenient request-level values, protecting the cluster from uncontrolled queries without rejecting them entirely.
  • All guardrails for a tenant are located in one place alongside the group’s resource_limits and resiliency_mode.

Supported settings

You can configure settings in the settings object of a workload group. All settings are optional. Only the settings you explicitly define on a workload group are enforced; any setting you omit defaults to the corresponding request parameter or cluster default. Each workload group setting accepts the same value range as the underlying request parameter or cluster setting it maps to.

The following table lists the supported workload group settings.

Setting Type Description Equivalent request parameter Equivalent cluster setting
search.default_search_timeout Time unit The maximum amount of time a shard can spend on query execution. When a shard exceeds this timeout, it stops collecting hits and returns its current results to the coordinating node, which may produce partial results. timeout search.default_search_timeout
search.cancel_after_time_interval Time unit The maximum amount of time the entire search request can run at the coordinating node level. When the interval is reached, the request and all associated tasks are canceled and the client receives an error rather than partial results. cancel_after_time_interval search.cancel_after_time_interval
search.max_concurrent_shard_requests Integer The maximum number of concurrent shard-level requests a single search may issue per node. Limits search fan-out. max_concurrent_shard_requests –
search.batched_reduce_size Integer The number of shard results combined into one batch on the coordinating node before the final reduction step. Lower values reduce coordinator memory usage when a search spans many shards. batched_reduce_size –
search.max_buckets Integer The maximum number of aggregation buckets allowed in a single response. Guards against excessive memory use from large aggregations. – search.max_buckets
override_request_values Boolean Whether the workload group’s settings take precedence over values supplied on the request. Default is false. See Setting precedence. – –

Setting precedence

When a setting is defined on a workload group, OpenSearch resolves the effective value at request time using the following precedence rules:

  • A workload group setting always takes precedence over the corresponding cluster setting when both are defined.
  • By default, an explicit value supplied on a request takes precedence over the workload group’s setting. You can reverse this behavior by setting override_request_values to true.

The following table summarizes how the effective value is resolved.

override_request_values Precedence (highest to lowest)
false (Default) Request parameter > Workload group setting > Cluster setting
true Workload group setting > Request parameter > Cluster setting

Creating a workload group containing settings

Add a settings object alongside the existing workload group fields:

PUT _wlm/workload_group
{
  "name": "analytics",
  "resiliency_mode": "enforced",
  "resource_limits": {
    "cpu": 0.4,
    "memory": 0.2
  },
  "settings": {
    "search.default_search_timeout": "30s",
    "search.cancel_after_time_interval": "1m",
    "search.max_concurrent_shard_requests": 5,
    "search.batched_reduce_size": 512,
    "search.max_buckets": 10000
  }
}

Updating workload group settings

You can update individual settings without affecting the other settings.

For example, to change only the search timeout for the analytics workload group:

PUT _wlm/workload_group/analytics
{
  "settings": {
    "search.default_search_timeout": "1m"
  }
}

To remove a single setting, set its value to null:

PUT _wlm/workload_group/analytics
{
  "settings": {
    "search.batched_reduce_size": null
  }
}

To clear all settings, send an empty settings object:

PUT _wlm/workload_group/analytics
{
  "settings": {}
}

Retrieving workload group settings

To retrieve workload group settings, use the Workload Group API:

GET _wlm/workload_group/analytics

Deleting workload group settings

Settings are removed when the workload group is deleted. To remove individual settings without deleting the group, see Updating workload group settings.

350 characters left

Have a question? .

Want to contribute? or .