1. Basic writing methods
1.1 Single-row writing
Single-row writing is the simplest write method. Consider a smart meter with device ID d1001 that collected data on October 3, 2018 at 14:38:05: current 10.3A, voltage 219V, phase 0.31. The following three INSERT variations produce the same result: specifying all columns with VALUES, omitting the column list, or using a timestamp at the database’s configured precision.
1.2 Batch writing
Writing multiple rows in a single INSERT statement substantially improves throughput. Batch writing reduces network round trips, a common source of write latency.
1.3 Multi-table writing
TDengine supports writing to multiple tables in a single statement. For example, you can write three rows each to tables d1001, d1002, and d1003 in one operation.
2. Advanced writing techniques
2.1 Writing to specific columns
You can write data to a subset of columns. Columns not included in the INSERT are automatically filled with NULL. The timestamp column must always be present and its value cannot be null.
2.2 Automatic table creation on write
Use the USING keyword to enable automatic table creation. If the target Subtable does not exist, TDengine creates it automatically before writing data. If it already exists, data is written directly. A single statement can write to multiple tables with automatic creation.
2.3 Writing through a Supertable
You can write directly to a Supertable. A Supertable is a schema template and does not store data itself; the written data is stored in the corresponding Subtables. Specify the tbname column to route data to the correct Subtable.
3. Data updates and deletion
3.1 Data updates
Writing a row with a timestamp that already exists updates that record. The new values replace the old ones.
3.2 Data deletion
Use DELETE FROM meters [WHERE condition] to remove data. Deleted data cannot be recovered, so run a SELECT with the same condition first to verify the affected rows.
4. Zero-code data ingestion
TDengine integrates with a broad range of third-party tools: monitoring collectors (Telegraf, collectd, StatsD), message queues (EMQX, HiveMQ, Kafka), and monitoring systems (Prometheus). Users import data through simple configuration, with no code required.
TDengine Enterprise also provides connectors for MQTT, OPC, AVEVA PI System, Wonderware, MySQL, and Oracle. By configuring connection details on the TDengine side, you can write data at high throughput without writing a single line of code.
5. Write performance optimization
5.1 Prefer batch writing
Use batch writing whenever possible. A batch size of 1,000 to 5,000 rows per INSERT is recommended. Fewer network round trips means higher throughput.
5.2 Use automatic table creation
Automatic table creation simplifies application logic. It avoids frequent table-existence checks and reduces DDL overhead.
5.3 Timestamp handling
Use numeric timestamps to reduce parsing overhead. Keep timezone usage consistent across your pipeline. Avoid out-of-order writes.
5.4 Table design
Design your Metric columns carefully to avoid an excessive number of columns per table. Keep Tag values reasonably short. Choose database configuration parameters that match your data characteristics.
6. Compression ratio
Query the INS_DISK_USAGE system table to check database compression ratio and disk space:
SELECT * FROM INFORMATION_SCHEMA.INS_DISK_USAGE WHERE db_name = 'db_name';
Use SHOW TABLE DISTRIBUTED table_name to view per-table compression ratios and distribution.
Summary
Efficient data writing is the foundation for getting value from a time-series database. TDengine provides a complete range of writing methods: from single-row to batch, from manual table creation to automatic table creation, and from SQL-based writing to zero-code integration. Choosing the right writing strategy helps applications get consistent performance from the time-series database.
