Apache IoTDB: Industrial Time-Series Database Guide

What Apache IoTDB is, and who this guide is for

The IoTDB documentation describes it as a low-cost, high-performance IoT-native time-series database. It came out of industrial use and is now an Apache Software Foundation project, written in Java, with the core licensed under the Apache License 2.0. Its target problems are listed plainly in the introduction: very many devices, high sampling frequencies, frequent out-of-order data and high storage cost.

This guide is for engineers designing data platforms for plants, utilities and building portfolios, where the natural unit is a device (an air-handling unit, a chiller, a meter) with a set of measurement points. If you first need the general idea of a time-series database, read the time-series database overview. On 27 October 2026 the download page listed 2.0.11 and 1.3.7 as current releases; 2.0.11 was released on 11 September 2026.

The project's commercial support page says that, "As every Apache project, so is Apache IoTDB generally available and usable by anyone free of charge." Commercial support is offered by third parties listed on the project site, including Timecho, whose listed contact is a project committer. This guide covers the Apache edition only.

Licence. The code is under the Apache License 2.0; the text is in the repository as LICENSE, followed by notices for bundled third-party code. Section 2 of the licence grants "a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work", subject to the licence's conditions, such as giving recipients a copy of the licence. Products sold by third parties on top of IoTDB carry their own terms. Not legal advice: this paragraph quotes the licence and the project site; read the licence and take advice for your situation.

Two data models: tree and table

IoTDB 2.x supports two SQL dialects, which it calls the tree model and the table model. Both can coexist in the same cluster, but they are isolated from each other by default, and you choose one per connection (for example -sql_dialect table on the CLI or sql_dialect=table in the JDBC URL).

• Tree model. Each measurement point is a path such as root.bms.hq.ahu01.supply_air_temp. The second-to-last level is the device. The documentation positions it for monitoring scenarios such as DCS and SCADA, where points map one-to-one to tags in a control system. Paths can be created as data arrives, and low-cardinality levels should come first so common prefixes compress well.
• Table model. One table per type of device. Every table has a TIME column; TAG columns identify the device (site, building, asset ID) and together act as its key; ATTRIBUTE columns hold static descriptions such as model or maintenance contract and can be updated; FIELD columns hold the measured values. This model is aimed at analysis and at migrating from other databases.

A tree-to-table view lets existing tree data be queried with table SQL. Our editorial view: for a new building or plant project, the table model is closer to the way analysts usually think (one table of AHUs, one of chillers), while the tree model is closer to the point list exported from a BMS or SCADA system.

CREATE DATABASE bms;
USE bms;

CREATE TABLE ahu (
    time            TIMESTAMP TIME,
    building        STRING TAG,
    ahu_id          STRING TAG,
    model           STRING ATTRIBUTE,
    supply_air_temp FLOAT FIELD,
    fan_speed       FLOAT FIELD
) WITH (TTL=31536000000);

INSERT INTO ahu(building, ahu_id, model, time, supply_air_temp, fan_speed)
VALUES ('hq', 'ahu-01', 'AX-40', '2026-10-27 08:00:00', 13.2, 61.0);

CREATE DATABASE root.bms;
CREATE TIMESERIES root.bms.hq.ahu01.supply_air_temp WITH DATATYPE=FLOAT, ENCODING=GORILLA;
INSERT INTO root.bms.hq.ahu01(timestamp, supply_air_temp) VALUES (1793088000000, 13.2);
SELECT supply_air_temp FROM root.bms.hq.ahu01;

Architecture: ConfigNodes, DataNodes and regions

An IoTDB deployment runs up to three kinds of process:

• ConfigNode: holds cluster membership, configuration, users and permissions, metadata and partition information, and schedules distributed operations and load balancing. ConfigNodes replicate each other fully.
• DataNode: serves client requests, stores data and runs queries.
• AINode (optional): registers machine-learning models and runs inference from SQL, including built-in forecasting and anomaly-detection algorithms.

Data and metadata are split into regions. A SchemaRegion holds the metadata for a set of devices; a DataRegion holds the data for a set of devices over a time range. IoTDB partitions by series (a hash into a fixed number of series partitions, 1000 by default) and by time (a time partition interval, seven days by default), and assigns the resulting partitions to replicated region groups.

Standalone and cluster. A standalone instance is one ConfigNode and one DataNode (1C1D), which the documentation recommends for resource-limited or edge servers where high availability is not critical; it cannot tolerate a node failure. A cluster is three ConfigNodes and at least three DataNodes (3C3D), with recommended replication of 3 for schema and 2 for data. Release 2.0.11 introduced an Edge edition for low-memory devices: its release notes say it caps ConfigNode and DataNode memory at 512 MB, targets about 10,000 measurements at 1 Hz, and in this first version relies on JVM and default configuration adjustments, with a fused ConfigNode and DataNode as a possible future direction. The README on the repository's main branch already describes an Edge distribution that merges both into one JVM, so check what the release you download actually ships.

Storage: TsFile, encoding, compression and TTL

TsFile. IoTDB writes its data to Apache TsFile, a separate Apache project that defines a columnar file format for industrial time-series data, with indexes on devices, sensors and time. Because TsFile is an open format with its own libraries, files can also be read by other tools such as Spark, which helps when historical data moves into a lakehouse.

Encoding then compression. Each series is first encoded according to its type, then compressed. The defaults are TS_2DIFF for integers and timestamps, GORILLA for FLOAT and DOUBLE, RLE for booleans and PLAIN for text, with DICTIONARY available for low-cardinality text. The documentation warns that TS_2DIFF and RLE keep only two decimal places for floats by default. Compression options are uncompressed, SNAPPY, LZ4 (the default), GZIP, ZSTD and LZMA2.

TTL. Retention is a TTL in milliseconds, set on a database (the default for its tables) or on an individual table, and it is checked against the data timestamp, not the write time. Expired data stops being readable at once, but is physically removed later during compaction, so disk space is freed with a delay. The default TTL is infinite.

Writes and updates. In the table model, writing a row with an existing timestamp for the same device updates the values, so a gateway that replays a buffer does not create duplicate rows. Attribute values are changed with UPDATE, which suits facts such as a replaced sensor model.

Querying: downsampling with date_bin

The table model uses SQL with time-series functions. Downsampling uses date_bin in GROUP BY, and functions such as LAST and LAST_BY return the latest value per device. The documentation lists over 100 built-in aggregation and time-series functions, and release 2.0.10 added set operations and common table expressions to the table model.

SELECT date_bin(1h, time) AS hour_time, ahu_id, AVG(supply_air_temp) AS avg_sat
FROM ahu
WHERE time >= 2026-10-27 00:00:00 AND time < 2026-10-28 00:00:00
GROUP BY 1, ahu_id;

The same bucketing in plain PostgreSQL

PostgreSQL 14 and later has its own date_bin, so the shape of the query carries over if you prototype on PostgreSQL first or keep a PostgreSQL copy of recent data. Here the tags become ordinary key columns. This ran on PostgreSQL 18.6 with 15-minute buckets.

CREATE TABLE ahu_readings (
    ts            timestamptz NOT NULL,
    building      text        NOT NULL,
    ahu_id        text        NOT NULL,
    supply_air_c  real,
    fan_speed_pct real,
    PRIMARY KEY (building, ahu_id, ts)
);

INSERT INTO ahu_readings VALUES
    ('2026-10-27 08:00+00', 'hq', 'ahu-01', 13.2, 61),
    ('2026-10-27 08:05+00', 'hq', 'ahu-01', 13.6, 63),
    ('2026-10-27 08:20+00', 'hq', 'ahu-01', 14.4, 70),
    ('2026-10-27 08:35+00', 'hq', 'ahu-01', 14.0, 68),
    ('2026-10-27 08:10+00', 'hq', 'ahu-02', 12.8, 55),
    ('2026-10-27 08:25+00', 'hq', 'ahu-02', 13.0, 57);

SELECT date_bin('15 minutes', ts, TIMESTAMPTZ '2026-10-27 00:00+00') AS bucket,
       building, ahu_id,
       round(avg(supply_air_c)::numeric, 2) AS avg_supply_air_c,
       max(fan_speed_pct) AS max_fan_pct
FROM ahu_readings
WHERE ts >= '2026-10-27 08:00+00' AND ts < '2026-10-27 09:00+00'
GROUP BY 1, building, ahu_id
ORDER BY ahu_id, bucket;

         bucket         | building | ahu_id | avg_supply_air_c | max_fan_pct
------------------------+----------+--------+------------------+-------------
 2026-10-27 08:00:00+00 | hq       | ahu-01 |            13.40 |          63
 2026-10-27 08:15:00+00 | hq       | ahu-01 |            14.40 |          70
 2026-10-27 08:30:00+00 | hq       | ahu-01 |            14.00 |          68
 2026-10-27 08:00:00+00 | hq       | ahu-02 |            12.80 |          55
 2026-10-27 08:15:00+00 | hq       | ahu-02 |            13.00 |          57

Getting data in: native APIs, MQTT and edge-to-cloud sync

• Native sessions and JDBC. Client libraries exist for Java, Python, C++, Go, C# and, since 2.0.11, Node.js; batch inserts through these sessions are the main high-volume path. JDBC suits reporting tools.
• Built-in MQTT. The server includes its own MQTT broker module (disabled by default, port 1883 when enabled). In the table model it accepts a line-protocol payload in which the first topic segment names the database and the measurement names the table. Devices can publish straight into IoTDB without a separate broker.
• Data sync (pipes). A pipe has a source, an optional processor and a sink, declared in SQL, and can copy new data (and optionally schema, TTL and permissions) from one IoTDB instance to another. This is how an edge 1C1D instance in a plant room can forward data to a central cluster.
• Kafka and stream processors. The ecosystem section documents a Kafka integration, and the introduction lists integrations with Hadoop, Spark, Grafana and ThingsBoard.

Our editorial view: the built-in broker is convenient for a single site, but we would not use it as a general message bus. Where several consumers need the same readings (an alarm service, a CMMS, a data lake), keep an independent broker such as an MQTT broker or Apache Kafka in front, as described in Designing an IoT Data Pipeline with Kafka, and let IoTDB be one consumer. The broker moves and buffers messages, IoTDB stores and queries device data, and a warehouse or lakehouse joins long history with asset and maintenance records.

Example: a building portfolio with edge and central nodes

Consider 40 buildings, each with a BMS exposing about 2,000 points (AHU supply-air temperature, chiller kW, zone CO2, meter readings) polled every 30 seconds. The building count, point count, polling interval and the 13-month retention below are illustrative assumptions for the example; choose your own from your point list, reporting and compliance needs, WAN reliability and disk budget. One possible IoTDB design:

• one standalone instance per large site, or per region, receiving readings from the BMS gateway over MQTT or a native client, so a WAN outage does not stop local trending;
• a pipe from each edge instance to a central 3C3D cluster, where portfolio-wide queries and dashboards run;
• table model on the central cluster, with one table per equipment type (ahu, chiller, meter, zone), building and asset_id as tags, and manufacturer and model as attributes;
• raw data kept for, say, 13 months by table TTL, with hourly roll-ups written to separate tables (for example with INSERT INTO ... SELECT) for long-range reporting;
• CMMS work orders kept in the CMMS database, joined to sensor history in a warehouse by asset ID rather than stored in IoTDB.

That portfolio produces 80,000 points every 30 seconds, about 230 million values a day. Estimate storage from a sample of your own data encoded with the chosen encodings rather than from a published ratio; the IoT sensor data storage guide walks through the arithmetic.

Security, sizing and operations

• Default credentials. A new installation has a root user whose default password is root. Change it before the instance is reachable from any network, create per-application users and grant only the paths or tables they need.
• Network and TLS. Keep the client RPC port (6667 by default) and the MQTT port on a private network or VPN. The configuration reference documents enable_thrift_ssl (SSL for RPC communication) and enable_https (SSL for the REST service), both false by default and configured with key_store_path and key_store_pwd. The MQTT service settings we checked (enable_mqtt_service, mqtt_host, mqtt_port and others) include no TLS option, so for MQTT across untrusted links put a broker or proxy you operate in front, or confirm the options for your version.
• Operating system limits. The README asks for at least 65,535 open files and a raised somaxconn, otherwise the server may fail to start or reset connections under load. The 2.0.11 release notes raise the minimum requirement to JDK 17.
• Replication. High availability needs the cluster deployment with data replication of 2 or more; a single edge node needs backups or a sync pipe to another instance.
• Time partitions and TTL. TTL works per data timestamp and space is reclaimed by compaction, so leave disk headroom for compaction and for late data rewriting older partitions.

When not to use Apache IoTDB

• Transactional business data. Work orders, assets, contracts and stock belong in a relational database with constraints and transactions.
• Teams standardised on PostgreSQL. If you want one engine and full PostgreSQL compatibility, TimescaleDB keeps time-series data next to relational tables.
• Metrics monitoring of IT systems. Our editorial view: for Prometheus-style infrastructure metrics and PromQL dashboards, a Prometheus-compatible store such as VictoriaMetrics matches the existing tooling more directly.
• Small, slow data. At an illustrative scale of a few thousand points every 15 minutes, a partitioned PostgreSQL table may be enough without a separate database to operate; confirm with your own volumes and queries.
• Teams without Java operations experience. IoTDB is a JVM service with OS tuning requirements; a managed service may cost less in staff time.

For alternatives built for industrial devices, compare with TDengine, and see the guide to choosing a time-series database.

Frequently asked questions

Sources

• IoTDB user guide: IoTDB Introduction
• IoTDB user guide: Cluster concepts
• IoTDB user guide: Data model and terminology (table)
• IoTDB user guide: Table management
• IoTDB user guide: TTL (table model)
• IoTDB user guide: Data partitioning and load balancing
• IoTDB user guide: Encoding and compression
• IoTDB user guide: MQTT protocol (table model)
• IoTDB user guide: Data sync
• IoTDB user guide: Authority management
• IoTDB user guide: GROUP BY clause (table model)
• IoTDB user guide: Write and update data (table model)
• IoTDB user guide: Release history
• IoTDB user guide: Commercial support
• IoTDB user guide: System configuration (SSL, ports)
• Apache TsFile
• apache/iotdb repository on GitHub (README)
• apache/iotdb repository: LICENSE

Checked 27 October 2026.

How we research these articles: our editorial method. Research-based from official documentation; SQL examples are run on a local database where the page says so. CodeWithSQL earns nothing from the vendors mentioned.