Implementation:Apache Druid ExplainDialog

Knowledge Sources	Apache_Druid
Domains	Web_Console, Query_Workbench
Last Updated	2026-02-10 10:00 GMT

Overview

ExplainDialog is a React dialog component that displays the EXPLAIN plan for a SQL query using the Druid SQL or MSQ engine.

Description

The dialog wraps the current query in an EXPLAIN PLAN statement and sends it to the appropriate Druid API endpoint based on the engine type (sql-native, sql-msq-dart, or sql-msq-task). It parses the returned plan JSON using json-bigint-native and displays the native query plan in an AceEditor with hjson syntax highlighting. For multi-query plans, it renders a vertical tabbed interface. Each query explanation includes the native query JSON, column mappings and signature, and an optional button to open the native query in the workbench editor. Loading and error states are handled with Loader and inline error message components.

Usage

Used in the workbench view when a user clicks the "Explain" action to understand the native query plan that Druid will generate for their SQL query.

Code Reference

Source Location

• Repository: Apache Druid
• File: web-console/src/views/workbench-view/explain-dialog/explain-dialog.tsx
• Lines: 1-203

Signature

export interface QueryContextEngine extends QueryWithContext {
  engine: DruidEngine;
}

export interface ExplainDialogProps {
  queryWithContext: QueryContextEngine;
  mandatoryQueryContext?: Record<string, any>;
  onClose: () => void;
  openQueryLabel: string | undefined;
  onOpenQuery: (queryString: string) => void;
}

export const ExplainDialog = React.memo(function ExplainDialog(
  props: ExplainDialogProps,
): JSX.Element;

Import

import { ExplainDialog } from 'web-console/src/views/workbench-view/explain-dialog/explain-dialog';

I/O Contract

Inputs

Name	Type	Required	Description
queryWithContext	QueryContextEngine	Yes	The query string, context, wrap limit, and engine to explain
mandatoryQueryContext	Record<string, any>	No	Additional context keys merged into the explain request
onClose	() => void	Yes	Callback to close the dialog
openQueryLabel	string or undefined	No	Label for the button to open the native query; hidden when undefined
onOpenQuery	(queryString: string) => void	Yes	Callback to open the native query JSON in the workbench editor

Outputs

Name	Type	Description
JSX.Element	Dialog	A BlueprintJS Dialog with AceEditor showing the EXPLAIN plan, column signature, and optional open-query button

Usage Examples

Opening the explain dialog for an MSQ query

<ExplainDialog
  queryWithContext={{
    queryString: 'SELECT * FROM wikipedia',
    queryContext: {},
    engine: 'sql-msq-task',
  }}
  onClose={() => setShowExplain(false)}
  openQueryLabel="Open native query"
  onOpenQuery={(nativeQueryJson) => openNewTab(nativeQueryJson)}
/>

Related Pages

• Environment:Apache_Druid_Web_Console_Development