Principle:Apache Druid SQL Task Submission

Knowledge Sources	Apache Druid Druid SQL Statements API
Domains	Data_Ingestion, SQL_Ingestion, Task_Management
Last Updated	2026-02-10 00:00 GMT

Overview

A task dispatch principle that submits INSERT/REPLACE SQL statements to the Multi-Stage Query (MSQ) engine for asynchronous execution.

Description

SQL Task Submission takes a complete SQL ingestion query and submits it to the Druid SQL Statements API (POST /druid/v2/sql/statements). Unlike the classic batch task API, the MSQ engine:

• Executes SQL natively (no JSON spec conversion needed)
• Runs as a multi-stage distributed query (similar to MapReduce)
• Returns an Execution object with task stages, progress, and timing information
• Supports asynchronous execution with polling for completion

The submission automatically sets executionMode: 'async' in the query context to enable background execution.

Usage

Use this principle when the SQL ingestion query is finalized and the user clicks "Run" or "Submit". It is the execution trigger for all SQL-based ingestion workflows.

Theoretical Basis

SQL task submission follows an async dispatch pattern:

Request:
  POST /druid/v2/sql/statements
  { query: "INSERT INTO ...", context: { executionMode: 'async' }, resultFormat: 'array', header: true }

Response:
  { queryId: "task-id", state: "RUNNING" }

The queryId is then used for polling:
  GET /druid/v2/sql/statements/{queryId}?detail=true

Related Pages

Implemented By

• Implementation:Apache_Druid_SubmitTaskQuery