InfluxDB Explained: Architecture and IoT Applications

What InfluxDB is, and who this is for

InfluxDB is a database built only for timestamped data: metrics, events and sensor readings. Unlike TimescaleDB, which adds time-series features to PostgreSQL, it is a separate server with its own write format, storage engine and query languages. InfluxData describes InfluxDB 3 Core as a database built to collect, process, transform, and store event and time series data, and lists monitoring sensor data first among its use cases.

This guide is for engineers designing IoT, building-management or equipment-monitoring systems who keep meeting InfluxDB in tutorials and need to know which version they are looking at. The general concepts are in the time-series database overview.

The data model: table (measurement), tags, fields and timestamp

Every InfluxDB point has four parts:

• Table, called a measurement in 1.x and 2.x: a group of similar points, for example ahu or energy_meter.
• Tags: key-value pairs of strings that describe the source, such as site, building and ahu_id. Use tags for anything you filter or group by.
• Fields: the measured values (float, integer, unsigned integer, string or boolean), such as supply_temp or fan_speed_pct. At least one field is required.
• Timestamp: Unix time, nanosecond precision by default. If you omit it, the server uses its own clock, which records arrival time rather than measurement time.

Data lives in a database (a bucket in 2.x and in InfluxDB Cloud). In InfluxDB 3, tags and fields are stored as columns of the table, and a point is identified by table, tag set and timestamp. Writing a second point with the same identity merges the field sets; when both writes set the same field, the documentation warns that InfluxDB 3 Core does not guarantee which value is kept. Do not rely on overwrites to correct readings.

Line protocol

Line protocol is the text format every InfluxDB version accepts for writes: one point per line, table and tags separated by commas, a space, the fields, a space and an optional timestamp. It is whitespace-sensitive, tag values cannot be empty, and integer fields carry an i suffix. The same format is accepted by other products, including QuestDB, which makes it a common interchange format for collectors.

# <table>[,<tag_key>=<tag_value>...] <field_key>=<field_value>[,...] [<timestamp>]

ahu,site=hq,building=b1,ahu_id=AHU-01 supply_temp=18.4,return_temp=22.1,fan_speed_pct=65i 1793088000000000000
ahu,site=hq,building=b1,ahu_id=AHU-02 supply_temp=17.9,return_temp=21.8,fan_speed_pct=58i 1793088000000000000
zone_co2,site=hq,building=b1,zone=L3-OPEN ppm=742i 1793088000000000000

InfluxDB versions: 1.x, 2.x and 3 (Core, Enterprise and cloud)

InfluxData's documentation describes InfluxDB 3 as the current generation and the recommended platform for new time series workloads. The older versions remain documented and maintained, so check which one a tutorial targets before copying its queries.

InfluxDB 3 is a rewrite in Rust on Apache Arrow, DataFusion and Parquet. Core persists data as Parquet files on object storage or local disk, includes an embedded Python processing engine for plugins and triggers, and accepts writes through the 1.x and 2.x write APIs as well as its own. The documentation positions Core for real-time monitoring and recent data, and Enterprise for historical analysis, high availability and read replicas.

SQL, InfluxQL and Flux

SQL in InfluxDB 3 is the Apache DataFusion dialect, with time functions such as DATE_BIN. InfluxQL is the SQL-like language from 1.x, kept in InfluxDB 3 for compatibility. Flux is the functional language introduced with 2.x; InfluxData states that Flux is in maintenance mode, is not supported in InfluxDB 3, and recommends InfluxQL to future-proof code. Our editorial view: given that statement, start new projects on SQL or InfluxQL rather than Flux.

SELECT DATE_BIN(INTERVAL '15 minutes', time) AS time,
       ahu_id,
       avg(supply_temp) AS avg_supply_temp,
       max(supply_temp) AS max_supply_temp
FROM ahu
WHERE time >= now() - INTERVAL '1 day'
GROUP BY 1, ahu_id
ORDER BY 1, ahu_id;

SELECT MEAN(supply_temp), MAX(supply_temp)
FROM ahu
WHERE time >= now() - 1d
GROUP BY time(15m), ahu_id

IoT architecture: Telegraf, MQTT and the database

Telegraf is InfluxData's collection agent: a single Go binary whose input plugins collect metrics from systems, services, databases and IoT sensors, with processor and aggregator plugins in the middle and output plugins that write to InfluxDB and other destinations. Its MQTT Consumer input plugin subscribes to topics on an MQTT broker, which makes a typical building pipeline:

1. BMS controllers and IoT sensors (BACnet, Modbus, wireless sensors) are read by an edge gateway every 1 to 60 seconds.
2. The gateway publishes readings to an MQTT broker, which moves messages but does not store them for querying.
3. Telegraf subscribes, parses the payload, adds tags such as site and building, batches the points and writes line protocol to InfluxDB.
4. Dashboards and alarm rules query InfluxDB; a CMMS integration reads conditions (for example a filter differential pressure above its limit for an hour) and raises a work order in the CMMS's own relational database.
5. For year-on-year and portfolio analytics, data is exported to a warehouse or lakehouse; InfluxDB 3 stores Parquet files, and its plugin library includes an InfluxDB to Iceberg plugin.

Where many independent consumers need the same stream, put Kafka between the gateways and the database: Kafka keeps a replayable log, Telegraf or another consumer writes to InfluxDB, and other consumers feed analytics. The database is still the only component that answers time-range queries.

Retention and storage

Retention in InfluxDB is set per database (per bucket in 2.x, per retention policy in 1.x). In InfluxDB 3 Core data does not expire by default; you set a retention period when creating the database, from one hour upwards, in hours, days, weeks, months or years. Points older than the retention period stop being queryable and are deleted later by a background service.

A common pattern for sensor data is two databases: raw readings kept for weeks, and downsampled data kept for years. In InfluxDB 3 the downsampling can run inside the server through the processing engine (the plugin library includes a downsampler), or outside it in a scheduled job.

# Raw readings for 30 days (illustrative: set from how long raw data is needed)
influxdb3 create database --retention-period 30d bms_raw

# Downsampled data with no expiry (the default)
influxdb3 create database bms_hourly

Cardinality and schema design

In InfluxDB 1.x and 2.x (the TSM engine), every unique combination of measurement and tag values is a series, and the series index is held largely in memory. The v2 documentation names high series cardinality as a primary driver of high memory usage and warns against tags with highly variable values such as unique IDs. A tag like reading_id or work_order_id creates a new series for every value.

InfluxDB 3 changes this: its schema guide says the storage engine supports unlimited tag value and series cardinality, and that tag value cardinality no longer affects overall performance. Other limits take over. A table has a maximum number of columns, and every tag and field is a column, so a "one field per BMS point" design on a single table can hit the limit. The guide also advises against wide and sparse schemas and recommends ordering tags by query priority on the first write, because that order fixes the physical column order.

A workable layout for building data: one table per equipment type (ahu, chiller, zone, meter), tags for site, building, floor and asset ID, fields for that equipment type's measurements. Keep the asset register, with descriptions and maintenance history, in a relational database and use the asset ID as the shared key.

Security, sizing and operations

• Authentication: InfluxDB 3 uses tokens. In Core, the token documentation describes admin tokens, each of which grants access to every action on the server, so keep Core on a private network. Enterprise adds resource tokens with permissions on specific databases, which is what lets you give Telegraf a write token and dashboards read tokens, and InfluxData's Enterprise 3.12 announcement says user authentication and RBAC are generally available.
• Network: put InfluxDB behind TLS and keep BMS and OT networks segmented; gateways should push outwards rather than expose the database to field networks.
• High availability: Core is a single node. High availability and read replicas are Enterprise features, and Clustered and the cloud services are the larger-scale options.
• Sizing: estimate points per second (points x readings per minute / 60), multiply by retention, and measure Parquet file sizes on a sample of your own data; compression depends heavily on how values change.
• Licensing cost: Enterprise licences limit the CPU cores per cluster (see the licence section below). Check the licence page before sizing a cluster.

Licences: InfluxDB 3 Core and Enterprise

InfluxDB 3 Core. The influxdb repository README says: "The open source software we build is licensed under the permissive MIT or Apache 2 licenses at the user's choosing." The two texts are in the repository as LICENSE-MIT and LICENSE-APACHE. The MIT text grants permission "to deal in the Software without restriction", subject to the condition that "The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software."

InfluxDB 3 Enterprise. Enterprise is commercial software that runs under a licence file. The licence page lists three types: "Trial: 30-day trial license with full access to InfluxDB 3 Enterprise capabilities.", "At-Home: For at-home hobbyist use with limited access to InfluxDB 3 Enterprise capabilities." and "Commercial: Commercial license with full access to InfluxDB 3 Enterprise capabilities." It states that "Each InfluxDB 3 Enterprise license limits the number of CPUs InfluxDB can use", with a CPU core limit of 2 shown for At-Home, and that "If the InfluxDB 3 Enterprise server stops, it will not restart without a valid, non-expired license." The page's comparison table also has a "Commercial use" row; read it on the page for the licence type you plan to use.

Not legal advice. These are quotations from InfluxData's licence files and documentation, not a conclusion about what your use needs. Read the licence texts and your Enterprise agreement, and take advice for your situation.

When not to use InfluxDB

• Relational or transactional data. Work orders, assets, contracts and bookings need constraints, updates and joins. InfluxDB has no foreign keys and documents that overwrites are not deterministic, so keep that data in a relational database.
• Queries that join readings to business tables. If most reports join sensor data to assets, spaces and work orders, PostgreSQL with or without TimescaleDB keeps it in one SQL engine.
• Historical analytics on Core alone. Core is documented as a recent-data engine; long-range history needs Enterprise, a cloud service, or an export to a warehouse.
• Existing Flux code bases you want to move forward. Flux does not run on InfluxDB 3; plan a rewrite to SQL or InfluxQL.
• Small deployments with an existing PostgreSQL. Our editorial view: at an illustrative few thousand points per minute, a partitioned PostgreSQL table is often enough, and another server adds backup, upgrade and security work; confirm with your own volumes and queries.

For a side-by-side view see TimescaleDB vs InfluxDB; for the wider field, the guide to choosing a time-series database.

Frequently asked questions

Sources

• InfluxData documentation home (product list and versions)
• InfluxDB 3 Core documentation
• InfluxDB 3 Core: Get started
• InfluxDB 3 Enterprise documentation
• InfluxDB 3 Enterprise: Manage your license
• InfluxDB 3 Cloud documentation
• InfluxDB 3 Core: Line protocol reference
• InfluxDB 3 Core: Schema design recommendations
• InfluxDB 3 Core: Data retention
• InfluxDB 3 Core: Create a database
• InfluxDB 3 Core: Aggregate data with SQL
• Flux documentation: The future of Flux
• InfluxDB OSS v2: Resolve high series cardinality
• Telegraf documentation
• Telegraf: MQTT Consumer input plugin
• influxdb repository on GitHub (InfluxDB 3 Core)
• InfluxDB 3 Core: Manage tokens
• InfluxDB 3 Enterprise: Manage tokens
• influxdb releases on GitHub
• influxdb repository: LICENSE-MIT
• influxdb repository: LICENSE-APACHE

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.