Principle:Apache Druid Query Context Configuration

Knowledge Sources	Apache Druid Druid Query Context
Domains	SQL_Querying, Performance_Tuning
Last Updated	2026-02-10 00:00 GMT

Overview

A query behavior configuration pattern that sets execution engine, timezone, cache policy, and other runtime parameters for SQL query execution.

Description

Query Context Configuration controls how a query is executed by setting key-value pairs in the queryContext object. Key configuration dimensions include:

• Engine selection: native (single-node), sql-native (SQL on native engine), sql-msq-task (MSQ distributed), sql-msq-dart (real-time MSQ)
• Timezone: SQL timezone for time functions (e.g., 'America/New_York')
• Cache control: Whether to use cached results (useCache, populateCache)
• Join algorithm: sortMerge or broadcast for SQL joins
• Result destination: taskReport (in-memory) or durableStorage (S3/HDFS)
• Parallelism: maxNumTasks for MSQ execution

The engine selection is the most impactful choice — it determines the execution path (native vs. MSQ) and what query features are available.

Usage

Use this pattern before executing any query to ensure the right execution engine and parameters are selected. The context configuration panel is accessible from the Workbench run panel.

Theoretical Basis

Query context follows a key-value runtime configuration pattern:

QueryContext = {
  sqlTimeZone?: string,
  useApproximateCountDistinct?: boolean,
  useCache?: boolean,
  joinAlgorithm?: 'sortMerge' | 'broadcast',
  selectDestination?: 'taskReport' | 'durableStorage',
  durableShuffleStorage?: boolean,
  maxNumTasks?: number,
}

Context is sent as part of the query payload:
  POST /druid/v2/sql { query: "...", context: { ... } }

Related Pages

Implemented By

• Implementation:Apache_Druid_RunPanel