Principle:Apache Druid Query Execution

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

Overview

A multi-engine query dispatch principle that routes SQL and native JSON queries to the appropriate Druid execution engine based on the configured context.

Description

Query Execution is the core dispatch mechanism that takes a composed query and routes it to one of four execution engines:

• sql-msq-task: Multi-Stage Query engine for distributed execution (INSERT/REPLACE, large SELECTs) — POST /druid/v2/sql/statements
• sql-native: Native SQL execution for real-time queries — POST /druid/v2/sql
• native: Raw JSON native queries (Timeseries, TopN, GroupBy, Scan) — POST /druid/v2
• sql-msq-dart: Real-time distributed SQL execution

The dispatch logic detects the query type (SQL string vs JSON object) and engine selection, then calls the appropriate API with error handling that maps Druid errors to editor positions.

Usage

Use this principle when the user triggers query execution via the Run button. The engine selection from the context configuration determines the execution path.

Theoretical Basis

Query execution follows a multi-engine dispatch pattern:

Dispatch logic:
  if engine == 'sql-msq-task':
    submitTaskQuery(query) → POST /druid/v2/sql/statements → Execution (async)
  elif engine == 'sql-native':
    queryDruidSql(query) → POST /druid/v2/sql → QueryResult (sync)
  elif engine == 'native':
    queryDruidRune(query) → POST /druid/v2 → QueryResult (sync)
  elif engine == 'sql-msq-dart':
    submitTaskQuery(query) → POST /druid/v2/sql/statements → Execution (async)

Error mapping:
  DruidError { errorCode, errorMessage, line, column } → editor error highlight

Related Pages

Implemented By

• Implementation:Apache_Druid_QueryTab_ProcessQuery