Per-Query Time Series Instructions

A query can change how Trickster caches and serves it with directives written in its own comments, so a query’s author can adjust it without changing the backend’s configuration. For example, in PromQL:

sum(rate(http_requests_total[5m])) # trickster-step-align:drop
  • Directives are read from comments only. The same text inside a string literal, or anywhere else in the query, is not a directive.
  • Several directives can share one comment, separated by spaces. When a directive appears more than once, the last one wins, and an invalid value is ignored.
  • Directives change how a query is cached and served, never what a complete bucket holds, so they are not part of the cache key: the same query with and without them shares one cache entry.
  • The query is sent to the origin as written; the origin ignores the comment.
  • Directives apply to queries Trickster caches as time series. A query served from the object cache, or proxied, is unaffected.

Directives

DirectiveValuesEffect
trickster-step-aligntruncate, drop, partial, partial_start, partial_end, offSelects the query’s step alignment mode, overriding the backend’s. A mode the query doesn’t support falls back to its default, counted in trickster_step_alignment_fallbacks_total.
trickster-volatile-windowwhole seconds, or a duration such as 90s or 5mReplaces the backend’s volatile_window for this query.
trickster-fast-forwardoffTurns Fast Forward off for this Prometheus query. A trickster-step-align directive in the same query takes precedence.

Under an ALB that applies a step alignment mode to its pool, a trickster-step-align directive wins when every pool member supports the mode it names; otherwise the ALB’s mode applies.

Comment Syntax by Backend

Backend and query languageComments
Prometheus, GreptimeDB PromQL, VictoriaMetrics MetricsQL# ... to the end of the line
InfluxQL-- ... to the end of the line, /* ... */
Flux// ... to the end of the line
InfluxDB SQL, Flight SQL, PostgreSQL, TimescaleDB, Druid SQL, GreptimeDB SQL and PostgreSQL-- ... to the end of the line, /* ... */
MySQL, GreptimeDB MySQL-- ... (with a space or tab after the dashes), # ..., /* ... */
ClickHouse-- ... to the end of the line, /* ... */
Druid native queriesthe query’s context map, keyed by the directive’s full name
Graphite, InfluxDB Prometheus remote readnone

Notes:

  • ClickHouse accepts # comments too, but Trickster’s ClickHouse SQL parser doesn’t, so a statement using one is served from the object cache, or proxied, and its directives don’t apply.

  • A PostgreSQL escape string (E'...') is a string literal, so directive text inside one is not a directive.

  • A Druid native query has no comments, so it carries directives as context keys, which Trickster leaves out of the cache key and Druid ignores:

    "context": { "trickster-step-align": "partial_end", "trickster-volatile-window": "2m" }
    

    A Druid SQL query can use both. For the same directive, its SQL comment wins over its context.

Last modified October 27, 2026: bump docs for v2.2 (891dcc4)