SETTINGS Clause

Add settings at the end of a query to control caching, timezone, and related behavior.

AGGREGATE aggregation.oee AS oee
WHERE time FROM now()-7D TO now()
SETTINGS disable_cache = true, timezone = 'America/New_York'

Separate multiple settings with commas: key = value.

Supported settings

Key	Values	Default	What it does
`backend`	`v1`, `clickhouse`	Platform default	Which query engine runs the query
`disable_cache`	`true`, `false`	Caching on	Skip cache for this query
`disable_cache_all`	`true`, `false`	`false`	Skip cache for this query and all helper queries
`disable_tier1_cache`	`true`, `false`	Caching on	Skip fast (tier 1) cache only
`disable_tier2_cache`	`true`, `false`	Caching on	Skip tier 2 cache only
`ttl`	e.g. `1h`, `30m`, `1D`	Platform default	How long cached results are kept
`always_log_error`	`true`, `false`	`false`	Always write errors to logs (for debugging)
`mutate_cte_with_global_filters`	`true`, `false`	`false`	Apply dashboard filters inside helper queries
`timezone`	e.g. `'America/New_York'`, `'UTC'`	User/org default	Timezone for timestamps in results

Values can be written with or without quotes (true, 'America/New_York').

Examples

Timezone

Show bucket times in a specific timezone:

AGGREGATE avg(metric_group('uuid')) AS avg_value
WHERE time FROM now()-7D TO now()
GROUP BY bucket 1h AS hour
SETTINGS timezone = 'America/New_York'

Disable caching

Use when results look stale or while debugging:

AGGREGATE aggregation.oee AS oee
WHERE time FROM now()-30D TO now()
SETTINGS disable_cache = true

For dashboards with helper queries, use disable_cache_all = true to refresh everything.

Dashboard filters inside helpers

WITH summary AS (
    AGGREGATE aggregation.oee AS oee
    WHERE time FROM now()-7D TO now()
    GROUP BY line.name AS linename
)
AGGREGATE summary.oee AS oee
FROM summary
SETTINGS mutate_cte_with_global_filters = true

When this is true, factory/line filters from a dashboard are applied inside the helper query. Non-helper queries always receive dashboard filters automatically.

Notes

Settings on a helper query apply to that helper only.
Settings on the outer query apply to the main result.
disable_cache_all on the outer query also applies to nested helpers and union all arms.