Building a data processing application with a time-series database (TSDB) is easier when the workflow is broken into concrete decisions: connection method, data model, write path, query design, real-time processing, subscription, caching, and optional extensions.
Step 1: choose a connection method
The first step is picking how your application connects to the TSDB. TSDBs offer several connectors, including JDBC, RESTful APIs, and language-specific native drivers. Your choice depends on the project’s technology stack, performance requirements, and deployment environment.
For example, a Java project can use the TSDB’s JDBC connector, which supports the standard Parameter Binding (STMT) interface and provides an efficient write mode. If the project requires high write throughput, the JDBC connector’s high-performance write path can raise throughput when configured for the workload.
Step 2: design the data model
After establishing the connection, define the data model based on the application scenario. The core tasks are creating databases, Supertables, and Subtables, and clearly separating static Tags from Metrics.
A TSDB data model follows these principles:
- Decide whether to create one or multiple databases based on data characteristics
- Distinguish static Tags from Metrics and define the correct Supertable
- Create a Subtable for each data collection point
Example SQL:
CREATE STABLE IF NOT EXISTS power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (groupId INT, location BINARY(24))Step 3: choose a write method
TSDBs support two write methods. Choose based on your business scenario:
- Standard SQL writes: use INSERT statements to write data row by row or in batches. Suitable when data formats are fixed.
- Schemaless mode writes: write data directly without creating tables first. The TSDB automatically parses the data and creates the corresponding table structure.
For most IoT scenarios, standard SQL writes paired with automatic table creation syntax is an efficient approach:
INSERT INTO power.d1001 USING power.meters TAGS(2,'California.SanFrancisco') VALUES (NOW + 1a, 10.30000, 219, 0.31000)Step 4: write SQL queries
After writing data, construct SQL queries based on business requirements. The TSDB supports SQL syntax and provides window functions and time-dimension query capabilities. These features help teams use the database’s strengths in time-series data analysis.
Step 5: enable Stream Processing
If your application needs lightweight real-time statistical analysis, use the TSDB’s Stream Processing feature. Stream Processing performs real-time aggregation as data is written to the TSDB. It fits scenarios such as monitoring metric calculations and sliding window statistics, without requiring an additional stream processing framework.
Step 6: configure Data Subscription
If you need to consume real-time inserted data, use the Data Subscription (TMQ) feature. The TSDB provides subscription and consumption interfaces similar to message queue products, with support for Consumer Group management and automatic offset commits. In many cases, a big data platform built on the TSDB does not need to integrate a separate message queue product. This simplifies application design and reduces operational costs.
Step 7: use the Cache function
If your application needs the latest status of each data collection point, use the Cache function (Last-Cache). This feature caches the most recent data of each Subtable. Queries can hit the cache without scanning the storage layer, reducing response time for latest-value access. It is well suited for scenarios like device status monitoring dashboards.
Supplement: extending capabilities with UDFs
When built-in functions do not meet business needs, you can use User-Defined Functions (UDFs). The TSDB supports writing UDFs in both C and Python. Once registered, UDFs can be called directly in SQL, providing flexible extension for specialized computation scenarios.
Summary
From connection method selection to data model design, from write strategies to query optimization, and onward to Stream Processing, Data Subscription, and Cache, the TSDB provides a complete development toolchain. Following these seven steps gives developers a practical path for building a stable time-series data processing application. TDengine TSDB covers the core database workflow from connection and modeling to writing, querying, Stream Processing, Data Subscription, Cache, and UDF-based extension.
