Principle:Apache Druid Visual Query Execution

Knowledge Sources	Apache Druid
Domains	Visual_Exploration, Query_Processing
Last Updated	2026-02-10 00:00 GMT

Overview

A SQL query generation and execution principle that transforms visual exploration parameters into optimized Druid SQL queries with column hints for visualization rendering.

Description

Visual Query Execution is the engine that converts configured dimensions, measures, filters, and time buckets into executable SQL queries. It handles:

• Query generation: Building SELECT, FROM, WHERE, GROUP BY, ORDER BY, and LIMIT clauses from visual parameters
• Macro expansion: Rewriting custom macros like AGGREGATE() into standard SQL aggregation expressions
• Time comparison: Generating JOIN-based or filtered queries for comparing time periods (current vs. previous day/week/month)
• Column hints: Providing metadata (formatting, grouping, comparison) for visualization modules

The query builder supports three strategies:

• Non-compare: Simple GROUP BY query for standard visualizations
• Filtered compare: Uses FILTER(WHERE ...) for period-over-period in non-time dimensions
• Join compare: Uses self-JOIN for period-over-period with time dimensions

Usage

Use this principle when visualization parameters change (filter update, dimension/measure change, time bucket change). The generated query is executed via POST /druid/v2/sql and results are rendered by the active visualization module.

Theoretical Basis

Visual query execution follows a parameterized query compilation pattern:

Parameters → SQL Query + Column Hints

Non-compare query:
  SELECT dims..., measures...
  FROM source
  WHERE filters
  GROUP BY dims...
  ORDER BY orderBy
  LIMIT maxRows

Compare query (join):
  SELECT current.dims, current.measures, previous.measures
  FROM (current_query) AS t1
  JOIN (shifted_query) AS t2
  ON t1.dims = t2.dims

Macro expansion:
  AGGREGATE(measure) → SUM("measure") / COUNT(*) / APPROX_COUNT_DISTINCT(...)

Related Pages

Implemented By

• Implementation:Apache_Druid_MakeTableQueryAndHints