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
    backfill_tolerance: 60s
    timeseries_retention_factor: 2048

Native query acceleration

POST /druid/v2 uses delta caching when all of these conditions hold:

• queryType is timeseries, groupBy, or topN.
• intervals contains exactly one ISO-8601 half-open interval.
• Both interval boundaries align with the selected granularity and origin.
• granularity has a fixed width:
  • a simple granularity from second through day;
  • a positive duration granularity in milliseconds; or
  • a fixed ISO-8601 period granularity in UTC, such as PT15M or P1D.
• 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.

The response model preserves native timeseries, groupBy, and topN JSON shapes. Grouping dimensions become DataSet tags internally. Hidden typed values and per-bucket positions preserve non-string dimensions and native row/ranking order when a response passes through the cache.

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, and timeBoundary;
• multiple intervals;
• interval boundaries that do not align with the selected granularity;
• all, none, week, month, quarter, and year simple granularities;
• calendar-width periods or period granularities in a non-UTC time zone;
• groupBy limits or dimension-first result ordering; and
• response-changing contexts such as bySegment, serializeDateTimeAsLong, timeseries grandTotal, or groupBy resultAsArray.

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 BY containing that bucket and every selected dimension; and
• a complete lower/upper time range on __time (unaligned edges are rounded inward, so partial edge buckets are not cached).

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.

Route policy

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 backfill tolerance is used when the backend does not configure one, so recently ingested buckets can be refreshed before segments settle.

Observability

• trickster_druid_query_analysis_total counts classifications by backend, cache mode (delta, object, or proxy), and stable reason code.
• trickster_druid_query_rewrite_failures_total counts failed missing-extent rewrites by backend and fixed failure category.

Neither metric includes query text, datasource names, or request IDs.