# apache/iotdb architecture

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

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

## Overview

IoTDB is a time-series database for collecting, storing, and analyzing industrial IoT data. A representative user workflow is sending data through a client or ingestion interface, querying it through an API, and receiving formatted results. The tree also exposes MQTT ingestion, Grafana-facing REST modules, plugin APIs, and AI inference/model management. Sampled internals support query execution tracking, file-read references, spilling, and temporary query files. Many product capabilities are documented, but their wiring is not established by the supplied excerpts; omitted connections should not be read as absent.

Main entry points: [`external-service-impl/rest/src/main/java/org/apache/iotdb/rest/protocol/v2/impl/RestApiServiceImpl.java`](https://github.com/apache/iotdb/blob/master/external-service-impl/rest/src/main/java/org/apache/iotdb/rest/protocol/v2/impl/RestApiServiceImpl.java) (REST API), [`external-service-impl/mqtt/src/main/java/org/apache/iotdb/mqtt/MPPPublishHandler.java`](https://github.com/apache/iotdb/blob/master/external-service-impl/mqtt/src/main/java/org/apache/iotdb/mqtt/MPPPublishHandler.java) (MQTT Publisher), [`iotdb-core/ainode/iotdb/ainode/core/manager/inference_manager.py`](https://github.com/apache/iotdb/blob/master/iotdb-core/ainode/iotdb/ainode/core/manager/inference_manager.py) (Inference Manager), [`external-service-impl/mqtt/src/main/java/org/apache/iotdb/mqtt/MQTTService.java`](https://github.com/apache/iotdb/blob/master/external-service-impl/mqtt/src/main/java/org/apache/iotdb/mqtt/MQTTService.java) (MQTT Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Client Interfaces"]
  node_rest["REST API"]
  node_restquery["Query Results"]
  node_grafana["Grafana API"]
  node_mqtt["MQTT Service<br/>[MQTTService.java]"]
  node_publish["MQTT Publisher"]
  node_formatter["Payload Formatting"]
end

subgraph group_query["Query Runtime"]
  node_engine["Fragment Execution"]
  node_queryfiles["Query File Tracking"]
  node_spill["Device Spill"]
  node_tempfiles["Temporary Query Files"]
end

subgraph group_extensions["Extensions"]
  node_pipe["Pipe Plugin API<br/>[PipePlugin.java]"]
  node_trigger["Trigger API<br/>[Trigger.java]"]
  node_udf["Function APIs<br/>[UDF.java]"]
end

subgraph group_ai["AI Inference"]
  node_inference["Inference Manager"]
  node_models[("Model Storage<br/>[model_storage.py]")]
end

node_client(("Database Client"))
node_modelclient(("Inference Client"))
node_querycaller(("Query Request"))

node_client -->|"sends requests"| node_rest
node_rest -->|"serves query results"| node_restquery
node_client -.->|"queries"| node_grafana
node_mqtt -->|"handles publishing"| node_publish
node_publish -->|"formats payloads"| node_formatter
node_querycaller -->|"dispatches fragments"| node_engine
node_querycaller -->|"tracks file reads"| node_queryfiles
node_querycaller -->|"reads spill data"| node_spill
node_querycaller -->|"uses temporary files"| node_tempfiles
node_modelclient -->|"requests inference"| node_inference
node_inference -->|"loads model info"| node_models

click node_rest "https://github.com/apache/iotdb/blob/master/external-service-impl/rest/src/main/java/org/apache/iotdb/rest/protocol/v2/impl/RestApiServiceImpl.java"
click node_restquery "https://github.com/apache/iotdb/blob/master/external-service-impl/rest/src/main/java/org/apache/iotdb/rest/protocol/v2/handler/QueryDataSetHandler.java"
click node_grafana "https://github.com/apache/iotdb/blob/master/external-service-impl/rest/src/main/java/org/apache/iotdb/rest/protocol/v2/impl/GrafanaApiServiceImpl.java"
click node_mqtt "https://github.com/apache/iotdb/blob/master/external-service-impl/mqtt/src/main/java/org/apache/iotdb/mqtt/MQTTService.java"
click node_publish "https://github.com/apache/iotdb/blob/master/external-service-impl/mqtt/src/main/java/org/apache/iotdb/mqtt/MPPPublishHandler.java"
click node_formatter "https://github.com/apache/iotdb/blob/master/external-service-impl/mqtt/src/main/java/org/apache/iotdb/mqtt/PayloadFormatManager.java"
click node_pipe "https://github.com/apache/iotdb/blob/master/iotdb-api/pipe-api/src/main/java/org/apache/iotdb/pipe/api/PipePlugin.java"
click node_trigger "https://github.com/apache/iotdb/blob/master/iotdb-api/trigger-api/src/main/java/org/apache/iotdb/trigger/api/Trigger.java"
click node_udf "https://github.com/apache/iotdb/blob/master/iotdb-api/udf-api/src/main/java/org/apache/iotdb/udf/api/UDF.java"
click node_engine "https://github.com/apache/iotdb/blob/master/iotdb-core/datanode/src/main/java/org/apache/iotdb/db/queryengine/execution/fragment/FragmentInstanceManager.java"
click node_queryfiles "https://github.com/apache/iotdb/blob/master/iotdb-core/datanode/src/main/java/org/apache/iotdb/db/storageengine/dataregion/read/control/QueryFileManager.java"
click node_spill "https://github.com/apache/iotdb/blob/master/iotdb-core/datanode/src/main/java/org/apache/iotdb/db/queryengine/plan/relational/metadata/spill/DeviceEntrySpillManager.java"
click node_tempfiles "https://github.com/apache/iotdb/blob/master/iotdb-core/datanode/src/main/java/org/apache/iotdb/db/service/TemporaryQueryDataFileService.java"
click node_inference "https://github.com/apache/iotdb/blob/master/iotdb-core/ainode/iotdb/ainode/core/manager/inference_manager.py"
click node_models "https://github.com/apache/iotdb/blob/master/iotdb-core/ainode/iotdb/ainode/core/model/model_storage.py"

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_rest,node_restquery,node_grafana,node_mqtt,node_publish,node_formatter,node_modelclient toneBlue
class node_engine,node_queryfiles,node_spill,node_tempfiles,node_client toneAmber
class node_pipe,node_trigger,node_udf,node_querycaller toneMint
class node_inference,node_models toneRose
```

## Components

### Client Interfaces

- [REST API](https://github.com/apache/iotdb/blob/master/external-service-impl/rest/src/main/java/org/apache/iotdb/rest/protocol/v2/impl/RestApiServiceImpl.java): `external-service-impl/rest/src/main/java/org/apache/iotdb/rest/protocol/v2/impl/RestApiServiceImpl.java`
- [Query Results](https://github.com/apache/iotdb/blob/master/external-service-impl/rest/src/main/java/org/apache/iotdb/rest/protocol/v2/handler/QueryDataSetHandler.java): `external-service-impl/rest/src/main/java/org/apache/iotdb/rest/protocol/v2/handler/QueryDataSetHandler.java`
- [Grafana API](https://github.com/apache/iotdb/blob/master/external-service-impl/rest/src/main/java/org/apache/iotdb/rest/protocol/v2/impl/GrafanaApiServiceImpl.java): `external-service-impl/rest/src/main/java/org/apache/iotdb/rest/protocol/v2/impl/GrafanaApiServiceImpl.java`
- [MQTT Service](https://github.com/apache/iotdb/blob/master/external-service-impl/mqtt/src/main/java/org/apache/iotdb/mqtt/MQTTService.java): `external-service-impl/mqtt/src/main/java/org/apache/iotdb/mqtt/MQTTService.java`
- [MQTT Publisher](https://github.com/apache/iotdb/blob/master/external-service-impl/mqtt/src/main/java/org/apache/iotdb/mqtt/MPPPublishHandler.java): `external-service-impl/mqtt/src/main/java/org/apache/iotdb/mqtt/MPPPublishHandler.java`
- [Payload Formatting](https://github.com/apache/iotdb/blob/master/external-service-impl/mqtt/src/main/java/org/apache/iotdb/mqtt/PayloadFormatManager.java): `external-service-impl/mqtt/src/main/java/org/apache/iotdb/mqtt/PayloadFormatManager.java`

### Query Runtime

- [Fragment Execution](https://github.com/apache/iotdb/blob/master/iotdb-core/datanode/src/main/java/org/apache/iotdb/db/queryengine/execution/fragment/FragmentInstanceManager.java): `iotdb-core/datanode/src/main/java/org/apache/iotdb/db/queryengine/execution/fragment/FragmentInstanceManager.java`
- [Query File Tracking](https://github.com/apache/iotdb/blob/master/iotdb-core/datanode/src/main/java/org/apache/iotdb/db/storageengine/dataregion/read/control/QueryFileManager.java): `iotdb-core/datanode/src/main/java/org/apache/iotdb/db/storageengine/dataregion/read/control/QueryFileManager.java`
- [Device Spill](https://github.com/apache/iotdb/blob/master/iotdb-core/datanode/src/main/java/org/apache/iotdb/db/queryengine/plan/relational/metadata/spill/DeviceEntrySpillManager.java): `iotdb-core/datanode/src/main/java/org/apache/iotdb/db/queryengine/plan/relational/metadata/spill/DeviceEntrySpillManager.java`
- [Temporary Query Files](https://github.com/apache/iotdb/blob/master/iotdb-core/datanode/src/main/java/org/apache/iotdb/db/service/TemporaryQueryDataFileService.java): `iotdb-core/datanode/src/main/java/org/apache/iotdb/db/service/TemporaryQueryDataFileService.java`

### Extensions

- [Pipe Plugin API](https://github.com/apache/iotdb/blob/master/iotdb-api/pipe-api/src/main/java/org/apache/iotdb/pipe/api/PipePlugin.java): `iotdb-api/pipe-api/src/main/java/org/apache/iotdb/pipe/api/PipePlugin.java`
- [Trigger API](https://github.com/apache/iotdb/blob/master/iotdb-api/trigger-api/src/main/java/org/apache/iotdb/trigger/api/Trigger.java): `iotdb-api/trigger-api/src/main/java/org/apache/iotdb/trigger/api/Trigger.java`
- [Function APIs](https://github.com/apache/iotdb/blob/master/iotdb-api/udf-api/src/main/java/org/apache/iotdb/udf/api/UDF.java): `iotdb-api/udf-api/src/main/java/org/apache/iotdb/udf/api/UDF.java`

### AI Inference

- [Inference Manager](https://github.com/apache/iotdb/blob/master/iotdb-core/ainode/iotdb/ainode/core/manager/inference_manager.py): `iotdb-core/ainode/iotdb/ainode/core/manager/inference_manager.py`
- [Model Storage](https://github.com/apache/iotdb/blob/master/iotdb-core/ainode/iotdb/ainode/core/model/model_storage.py): `iotdb-core/ainode/iotdb/ainode/core/model/model_storage.py`

### Other components

- **Database Client**
- **Inference Client**
- **Query Request**

## Connections

- Database Client → REST API: sends requests
- REST API → Query Results: serves query results
- Database Client → Grafana API: queries
- MQTT Service → MQTT Publisher: handles publishing
- MQTT Publisher → Payload Formatting: formats payloads
- Query Request → Fragment Execution: dispatches fragments
- Query Request → Query File Tracking: tracks file reads
- Query Request → Device Spill: reads spill data
- Query Request → Temporary Query Files: uses temporary files
- Inference Client → Inference Manager: requests inference
- Inference Manager → Model Storage: loads model info