Implementation:Apache Druid SubmitTaskQuery
| Knowledge Sources | |
|---|---|
| Domains | Data_Ingestion, SQL_Ingestion, Task_Management |
| Last Updated | 2026-02-10 00:00 GMT |
Overview
Concrete async function for submitting SQL queries to the Druid Multi-Stage Query engine via the SQL Statements API.
Description
The submitTaskQuery function POSTs an SQL query (INSERT/REPLACE/SELECT) to /druid/v2/sql/statements with executionMode: 'async' automatically set. It constructs a JSON payload with the query, merged context, and result format headers. The function returns an Execution object containing the task ID and initial status, or an IntermediateQueryState if the task is still initializing.
On submission, the function optionally calls onSubmitted with the task ID and sets up cancellation handling via cancelTaskExecutionOnCancel.
Usage
Call this function when submitting any SQL query for MSQ execution. It is used by both the SQL data loader (for INSERT/REPLACE) and the Workbench (for SELECT queries in MSQ mode).
Code Reference
Source Location
- Repository: Apache Druid
- File: web-console/src/helpers/execution/sql-task-execution.ts
- Lines: L46-L122
Signature
export interface SubmitTaskQueryOptions {
query: string | Record<string, any>;
context?: QueryContext;
baseQueryContext?: QueryContext;
prefixLines?: number;
signal?: AbortSignal;
preserveOnTermination?: boolean;
onSubmitted?: (id: string) => void;
}
export async function submitTaskQuery(
options: SubmitTaskQueryOptions,
): Promise<Execution | IntermediateQueryState<Execution>>
Import
import { submitTaskQuery } from '../../helpers/execution/sql-task-execution';
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| query | string or Record | Yes | SQL query string or pre-built query object |
| context | QueryContext | No | Execution context overrides (maxNumTasks, etc.) |
| baseQueryContext | QueryContext | No | Base context merged under query-specific context |
| prefixLines | number | No | Line offset for error reporting in multi-line editors |
| signal | AbortSignal | No | Cancellation signal for aborting the request |
| preserveOnTermination | boolean | No | Whether to keep the task running on abort |
| onSubmitted | callback | No | Called with the task ID after successful submission |
Outputs
| Name | Type | Description |
|---|---|---|
| Execution | Execution | Task execution object with id, status, stages, and query info |
| IntermediateQueryState | IntermediateQueryState<Execution> | Wrapper indicating the task is still initializing |
Usage Examples
Submit an INSERT Query
import { submitTaskQuery } from '../../helpers/execution/sql-task-execution';
const result = await submitTaskQuery({
query: `
INSERT INTO "my_events"
SELECT TIME_PARSE("ts") AS __time, "user", "action"
FROM TABLE(EXTERN('{"type":"s3","uris":["s3://bucket/data.json"]}', '{"type":"json"}'))
PARTITIONED BY DAY
`,
context: { maxNumTasks: 4 },
onSubmitted: (id) => console.log('Task submitted:', id),
});
if (result instanceof Execution) {
console.log('Task ID:', result.id);
console.log('Status:', result.status);
}