Apache Druid Support
Trickster accelerates eligible Apache Druid native JSON queries with the Time
Series Delta Proxy Cache (DPC). Configure druid as the backend provider and
point origin_url at a Druid Broker or Router.
backends:
druid1:
provider: druid
origin_url: http://druid-router:8888
cache_name: default
volatile_window: 60s
timeseries_retention_factor: 2048
Native query acceleration
POST /druid/v2 uses delta caching when all of these conditions hold:
queryTypeistimeseries,groupBy, ortopN.intervalscontains exactly one ISO-8601 half-open interval.granularityhas a fixed width:- a simple granularity from
secondthroughday; - a positive
durationgranularity in milliseconds; or - a fixed ISO-8601
periodgranularity in UTC, such asPT15MorP1D.
- a simple granularity from
- The selected context does not request an alternate native response shape.
Trickster removes the interval from the logical cache identity and rewrites
only missing extents into Druid’s [start,end) form. Druid’s end is exclusive,
so the final cached bucket is rendered as extent.End + granularity.
An interval boundary inside a bucket is handled by the backend’s
step_alignment, which defaults to partial for native queries: complete
buckets come from the delta cache, and each edge bucket is Druid’s answer over
the part of it the interval covers, fetched through the Object Proxy Cache for
partial_bucket_ttl and never delta cached. A native query can choose its own
mode, or its own volatile window, with keys in its context map, such as
"trickster-step-align": "drop", which Trickster leaves out of the cache key
and Druid ignores. See Step Alignment and
Per-Query Instructions.
The response model preserves native timeseries, groupBy, and topN JSON
shapes. Grouping dimensions become DataSet tags internally, and per-bucket
positions keep groupBy and topN rows in Druid’s order. A descending: true
query is cached in time order like any other and written newest first, as Druid
writes it. See Response fidelity.
Object-cache fallback
A valid read query that is unsafe for delta merging automatically uses the Object Proxy Cache (OPC) with a one-minute fallback TTL when Druid does not provide explicit freshness headers. This includes:
- other native query types such as
scan,search,segmentMetadata,datasourceMetadata, andtimeBoundary; - multiple intervals;
all,none,week,month,quarter, andyearsimple granularities;- calendar-width periods or period granularities in a non-UTC time zone;
- timeseries
limit, which keeps only the first rows of the whole result; - groupBy limits or dimension-first result ordering; and
- response-changing contexts such as
bySegment,serializeDateTimeAsLong, timeseriesgrandTotal, or groupByresultAsArray.
The following native context keys are transport controls and are omitted from
the cache identity: queryId, sqlQueryId, priority, timeout, and
queryDeadline. They remain unchanged in the request sent to Druid. Semantic
context keys, including skipEmptyBuckets, remain part of the cache identity.
Druid SQL acceleration
POST /druid/v2/sql uses the same delta cache for a deliberately conservative
subset of Druid SQL. The request must be a JSON object using either the default
or explicit resultFormat: "object", or resultFormat: "array" with
header: true. The statement must be a single-table SELECT that has:
- one
TIME_FLOOR(__time, <fixed UTC period>)bucket expression with an explicit alias; - a
GROUP BYcontaining that bucket and every selected dimension; and - a complete lower/upper time range on
__time(unaligned edges follow the backend’sstep_alignment,dropby default for SQL; partial edge buckets are never delta cached). A SQL comment such as-- trickster-step-align:partialchooses the query’s own mode, and wins over the same key in the request’scontext.
The shared CockroachDB SQL analyzer canonicalizes the statement and renders
each missing extent while preserving the original JSON context on the wire.
Literal MILLIS_TO_TIMESTAMP(...) bounds generated by the Grafana Druid plugin
are supported. Object rows and header-plus-array rows are converted to the
standard Trickster DataSet internally and emitted in their requested shape
after cache merging. Other valid SELECT statements and response formats
remain safe OPC fallbacks; non-read statements, SQL task requests, and malformed
requests are proxied.
Response fidelity
A response built from the cache is written the way Druid writes it:
- Numbers, objects and arrays are written exactly as Druid wrote them, so a
double keeps its form, such as
5319.0or9.999999999999999E22. - Strings and keys are escaped the way Druid’s JSON writer escapes them.
- Each row’s members are in Druid’s order. For
timeseriesandgroupByresults, that is the order of Druid’s Java hash maps. - Native responses end without a newline, and SQL responses end with one.
- SQL rows without an
ORDER BYfollow Druid’s order: by theGROUP BYcolumns, with the time bucket first unless theGROUP BYends with it. - Rows that tie on an
ORDER BYalso follow Druid’s order. - Nulls sort lowest, as in Druid: first when ascending and last when descending.
Two things can still differ from the response Druid builds for the same request, and both also vary between Druid’s own responses:
- topN key order. Druid orders a topN row’s keys differently depending on whether its segment cache served the row, so one query can come back with either order. Trickster writes the dimension, then the aggregations, then the post-aggregations.
- Floating-point sums. Druid adds a bucket’s values in an order that
depends on the query’s interval. So the last digits of a
doubleSumorfloatSumcan differ between two Druid queries that cover the same bucket. A cached bucket keeps the value from the query that fetched it.
Route policy
| Route | Method | Policy |
|---|---|---|
/druid/v2 | POST | DPC when eligible, otherwise OPC or proxy |
/druid/v2/sql | POST | DPC for eligible SQL, otherwise OPC or proxy |
/druid/v2/sql/task | POST | Proxy only |
/druid/v2/datasources... | GET | OPC |
/status/health | GET | Health probe; expects true |
| all other routes | any | Proxy only |
SQL ingestion and management endpoints, ALB time-series merging,
scan/search delta caching, and Fast Forward are not supported. Fast Forward
is disabled for every Druid backend. A 60-second volatile_window is used when
the backend does not configure one, so recently ingested buckets can be
refreshed before segments settle.
Observability
trickster_druid_query_analysis_totalcounts classifications by backend, cache mode (delta,object, orproxy), and stable reason code.trickster_druid_query_rewrite_failures_totalcounts failed missing-extent rewrites by backend and fixed failure category.
Neither metric includes query text, datasource names, or request IDs.