# apache/druid architecture

> Architecture diagram of the GitHub repository apache/druid, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/apache/druid
- Repository: https://github.com/apache/druid

## Overview

Apache Druid is a real-time analytics database for ingesting, managing, and querying data. A principal query path runs from a user or console through query-state handling and SQL planning, then through segment access and query-specific execution to results; gRPC offers a separate query entry point. The README also highlights streaming and batch ingestion and cluster management, but the sampled tree does not expose their central implementations, so those capabilities are represented without speculative wiring. Query-engine and multi-stage details reflect the sampled files; links between unsampled subsystems are omitted.

Main entry points: [`server/src/main/java/org/apache/druid/server/ClientQuerySegmentWalker.java`](https://github.com/apache/druid/blob/master/server/src/main/java/org/apache/druid/server/ClientQuerySegmentWalker.java) (Segment walker), [`sql/src/main/java/org/apache/druid/sql/calcite/planner/QueryHandler.java`](https://github.com/apache/druid/blob/master/sql/src/main/java/org/apache/druid/sql/calcite/planner/QueryHandler.java) (SQL handler), [`multi-stage-query/src/main/java/org/apache/druid/msq/kernel/controller/ControllerQueryKernel.java`](https://github.com/apache/druid/blob/master/multi-stage-query/src/main/java/org/apache/druid/msq/kernel/controller/ControllerQueryKernel.java) (MSQ controller kernel), [`web-console/src/utils/query-manager/query-manager.ts`](https://github.com/apache/druid/blob/master/web-console/src/utils/query-manager/query-manager.ts) (Query manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Query entry"]
  node_console["Web console"]
  node_query_manager["Query manager<br/>[query-manager.ts]"]
  node_grpc["gRPC service<br/>[QueryService.java]"]
  node_results["Query results"]
end

subgraph group_planning["Planning and dispatch"]
  node_sql_handler["SQL handler<br/>[QueryHandler.java]"]
  node_segment_walker["Segment walker"]
end

subgraph group_execution["Query execution"]
  node_groupby["GroupBy engine"]
  node_scan["Scan engine"]
  node_timeseries["Timeseries engine"]
  node_topn["TopN engine"]
  node_msq_kernel["MSQ controller kernel"]
  node_msq_data_handler["MSQ data handler"]
end

subgraph group_operations["Data and cluster"]
  node_ingestion["Streaming and batch ingestion"]
  node_cluster_management["Cluster management"]
end

node_user(("Analyst or client"))

node_user -->|"submits query"| node_console
node_console -->|"runs query"| node_query_manager
node_query_manager -->|"processes query"| node_sql_handler
node_user -->|"submits query"| node_grpc
node_grpc -.->|"delegates query"| node_sql_handler
node_sql_handler -->|"dispatches plan"| node_segment_walker
node_segment_walker -->|"runs query"| node_groupby
node_segment_walker -->|"runs query"| node_scan
node_segment_walker -->|"runs query"| node_timeseries
node_segment_walker -->|"runs query"| node_topn
node_sql_handler -.->|"plans stages"| node_msq_kernel
node_msq_kernel -->|"requests segment data"| node_msq_data_handler
node_groupby -->|"produces rows"| node_results
node_scan -->|"produces rows"| node_results
node_timeseries -->|"produces rows"| node_results
node_topn -->|"produces rows"| node_results
node_msq_kernel -.->|"produces results"| node_results
node_results -->|"updates state"| node_query_manager
node_ingestion -.-> node_cluster_management

click node_console "https://github.com/apache/druid/blob/master/web-console/src/hooks/use-query-manager.ts"
click node_query_manager "https://github.com/apache/druid/blob/master/web-console/src/utils/query-manager/query-manager.ts"
click node_grpc "https://github.com/apache/druid/blob/master/extensions-contrib/grpc-query/src/main/java/org/apache/druid/grpc/server/QueryService.java"
click node_sql_handler "https://github.com/apache/druid/blob/master/sql/src/main/java/org/apache/druid/sql/calcite/planner/QueryHandler.java"
click node_segment_walker "https://github.com/apache/druid/blob/master/server/src/main/java/org/apache/druid/server/ClientQuerySegmentWalker.java"
click node_groupby "https://github.com/apache/druid/blob/master/processing/src/main/java/org/apache/druid/query/groupby/epinephelinae/GroupByQueryEngine.java"
click node_scan "https://github.com/apache/druid/blob/master/processing/src/main/java/org/apache/druid/query/scan/ScanQueryEngine.java"
click node_timeseries "https://github.com/apache/druid/blob/master/processing/src/main/java/org/apache/druid/query/timeseries/TimeseriesQueryEngine.java"
click node_topn "https://github.com/apache/druid/blob/master/processing/src/main/java/org/apache/druid/query/topn/TopNQueryEngine.java"
click node_msq_kernel "https://github.com/apache/druid/blob/master/multi-stage-query/src/main/java/org/apache/druid/msq/kernel/controller/ControllerQueryKernel.java"
click node_msq_data_handler "https://github.com/apache/druid/blob/master/multi-stage-query/src/main/java/org/apache/druid/msq/indexing/IndexerDataServerQueryHandler.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_console,node_query_manager,node_grpc,node_results,node_user toneBlue
class node_sql_handler,node_segment_walker toneAmber
class node_groupby,node_scan,node_timeseries,node_topn,node_msq_kernel,node_msq_data_handler toneMint
class node_ingestion,node_cluster_management toneRose
```

## Components

### Query entry

- [Web console](https://github.com/apache/druid/blob/master/web-console/src/hooks/use-query-manager.ts): `web-console/src/hooks/use-query-manager.ts`
- [Query manager](https://github.com/apache/druid/blob/master/web-console/src/utils/query-manager/query-manager.ts): `web-console/src/utils/query-manager/query-manager.ts`
- [gRPC service](https://github.com/apache/druid/blob/master/extensions-contrib/grpc-query/src/main/java/org/apache/druid/grpc/server/QueryService.java): `extensions-contrib/grpc-query/src/main/java/org/apache/druid/grpc/server/QueryService.java`
- **Query results**

### Planning and dispatch

- [SQL handler](https://github.com/apache/druid/blob/master/sql/src/main/java/org/apache/druid/sql/calcite/planner/QueryHandler.java): `sql/src/main/java/org/apache/druid/sql/calcite/planner/QueryHandler.java`
- [Segment walker](https://github.com/apache/druid/blob/master/server/src/main/java/org/apache/druid/server/ClientQuerySegmentWalker.java): `server/src/main/java/org/apache/druid/server/ClientQuerySegmentWalker.java`

### Query execution

- [GroupBy engine](https://github.com/apache/druid/blob/master/processing/src/main/java/org/apache/druid/query/groupby/epinephelinae/GroupByQueryEngine.java): `processing/src/main/java/org/apache/druid/query/groupby/epinephelinae/GroupByQueryEngine.java`
- [Scan engine](https://github.com/apache/druid/blob/master/processing/src/main/java/org/apache/druid/query/scan/ScanQueryEngine.java): `processing/src/main/java/org/apache/druid/query/scan/ScanQueryEngine.java`
- [Timeseries engine](https://github.com/apache/druid/blob/master/processing/src/main/java/org/apache/druid/query/timeseries/TimeseriesQueryEngine.java): `processing/src/main/java/org/apache/druid/query/timeseries/TimeseriesQueryEngine.java`
- [TopN engine](https://github.com/apache/druid/blob/master/processing/src/main/java/org/apache/druid/query/topn/TopNQueryEngine.java): `processing/src/main/java/org/apache/druid/query/topn/TopNQueryEngine.java`
- [MSQ controller kernel](https://github.com/apache/druid/blob/master/multi-stage-query/src/main/java/org/apache/druid/msq/kernel/controller/ControllerQueryKernel.java): `multi-stage-query/src/main/java/org/apache/druid/msq/kernel/controller/ControllerQueryKernel.java`
- [MSQ data handler](https://github.com/apache/druid/blob/master/multi-stage-query/src/main/java/org/apache/druid/msq/indexing/IndexerDataServerQueryHandler.java): `multi-stage-query/src/main/java/org/apache/druid/msq/indexing/IndexerDataServerQueryHandler.java`

### Data and cluster

- **Streaming and batch ingestion**
- **Cluster management**

### Other components

- **Analyst or client**

## Connections

- Analyst or client → Web console: submits query
- Web console → Query manager: runs query
- Query manager → SQL handler: processes query
- Analyst or client → gRPC service: submits query
- gRPC service → SQL handler: delegates query
- SQL handler → Segment walker: dispatches plan
- Segment walker → GroupBy engine: runs query
- Segment walker → Scan engine: runs query
- Segment walker → Timeseries engine: runs query
- Segment walker → TopN engine: runs query
- SQL handler → MSQ controller kernel: plans stages
- MSQ controller kernel → MSQ data handler: requests segment data
- GroupBy engine → Query results: produces rows
- Scan engine → Query results: produces rows
- Timeseries engine → Query results: produces rows
- TopN engine → Query results: produces rows
- MSQ controller kernel → Query results: produces results
- Query results → Query manager: updates state
- Streaming and batch ingestion → Cluster management