Cache mechanism overview
TDengine uses a layered cache design, providing dedicated caching strategies for different data access scenarios:
| Cache type | Primary function | Use case |
|---|---|---|
| Write cache | Caches the most recently written data | High-frequency writes, real-time queries |
| Read cache | Caches hot query data | Repeated queries, latest data reads |
| Metadata cache | Caches table structures and Tag information | Frequent metadata access |
| File system cache | Uses operating system-level caching | Data file access acceleration |
This multi-level cache architecture ensures that TDengine maintains strong performance when handling large-scale time-series data.
Write cache mechanism
How write cache works
The TDengine write cache uses a time-driven strategy, prioritizing the most recently written data in memory. This design is based on a core characteristic of time-series data: the newest data is accessed most frequently.
Key characteristics of the write cache:
- Memory-resident: Newly written data is first stored in the memory buffer.
- Time-ordered: Data is organized by timestamp for fast retrieval.
- Batch flush: Data is written to disk in batches when specific conditions are met.
Key write cache parameters
Write cache performance is configured through the following parameters:
CREATE DATABASE mydb
BUFFER 256 <em>-- Write cache size per vnode, in MB</em>
PAGES 256 <em>-- Number of metadata cache pages</em>
PAGESIZE 4; <em>-- Size per page, in KB</em>
Key parameter reference:
| Parameter | Default | Description |
|---|---|---|
| BUFFER | 256 | Write cache size per vnode (MB), range 1-16384 |
| VGROUPS | 2 | Number of vgroups in the database; affects concurrent write capacity |
The vgroups mechanism
TDengine uses vgroups (virtual node groups) to horizontally scale write capacity:
CREATE DATABASE high_throughput_db
VGROUPS 10 <em>-- Create 10 vgroups</em>
BUFFER 512; <em>-- Allocate 512 MB write cache per vgroup</em>
Best practice recommendations:
- Increase VGROUPS for high-throughput write scenarios.
- Adjust BUFFER based on data retention period and write frequency.
- Ensure the server has enough memory to support all vgroups’ cache requirements.
Read cache mechanism
The cachemodel parameter
TDengine’s read cache is controlled by the cachemodel parameter, which supports three cache modes:
<em>-- Mode 1: Cache only the latest row of data</em>
cachemodel 'last_row'
<em>-- Mode 2: Cache the latest non-NULL value per column</em>
cachemodel 'last_value'
<em>-- Mode 3: Cache both the latest row and the latest non-NULL value per column</em>
cachemodel 'both'
Comparing the three cache modes
| Mode | Description | Use case | Memory usage |
|---|---|---|---|
| none | Disables the read cache | Primarily historical data analysis | Lowest |
| last_row | Caches the latest row of each Subtable | Real-time monitoring, latest-state queries | Medium |
| last_value | Caches the latest non-NULL value per column | Retrieving the latest value of each metric | Medium |
| both | Caches both of the above simultaneously | Mixed query scenarios | Higher |
Read cache configuration examples
CREATE DATABASE iot_db
CACHEMODEL 'both' <em>-- Enable full read cache</em>
CACHESIZE 50; <em>-- Cache size per vnode (MB)</em>
ALTER DATABASE iot_db CACHEMODEL 'last_value';
Configuration guidance:
- Use
last_roworbothmode for real-time monitoring scenarios. - Set to
nonefor databases focused on historical analysis to conserve memory. - Adjust CACHESIZE based on the number of Subtables and columns.
Metadata cache mechanism
Purpose of the metadata cache
The metadata cache stores table structures, Tag information, Supertable definitions, and other metadata. It uses a B+Tree data structure for efficient metadata retrieval.
Metadata cache parameters
CREATE DATABASE metadata_db
PAGES 256 <em>-- Number of metadata cache pages</em>
PAGESIZE 4; <em>-- Size per page (KB)</em>
Parameter details:
- PAGES: Controls the number of metadata cache pages. Each page stores a certain number of metadata entries.
- PAGESIZE: Affects the amount of data per I/O operation.
Metadata cache tuning recommendations
CREATE DATABASE large_scale_db
PAGES 1024 <em>-- Increase page count to cache more metadata</em>
PAGESIZE 16; <em>-- Increase page size to reduce I/O operations</em>
Key tuning points:
- Increase PAGES when the Subtable count exceeds the million level.
- For table structures with many Tag columns, consider increasing PAGESIZE.
- Monitor the metadata cache hit rate and adjust parameters as needed.
File system cache and WAL
WAL (Write-Ahead Log) mechanism
TDengine uses WAL (Write-Ahead Logging) to ensure data reliability while using file system caching for performance.
Key WAL parameters
CREATE DATABASE reliable_db
WAL_LEVEL 2 <em>-- WAL level</em>
WAL_FSYNC_PERIOD 3000; <em>-- WAL flush interval, in milliseconds</em>
WAL level reference:
| WAL_LEVEL | Description | Data safety | Write performance |
|---|---|---|---|
| 1 | Writes to WAL without fsync | Lower | Highest |
| 2 | Writes to WAL with periodic fsync | Medium | Medium |
WAL configuration examples
High-reliability configuration (finance-grade):
CREATE DATABASE finance_db
WAL_LEVEL 2
WAL_FSYNC_PERIOD 1000; <em>-- Flush every second</em>
High-performance configuration (logging):
CREATE DATABASE log_db
WAL_LEVEL 1
WAL_FSYNC_PERIOD 3000; <em>-- Relies on OS-level flushing</em>
Balancing performance and reliability
Recommended configurations by scenario
Scenario 1: High-frequency writes and real-time queries
CREATE DATABASE realtime_db
VGROUPS 20, BUFFER 512, CACHEMODEL 'both', CACHESIZE 100, WAL_LEVEL 1;
Scenario 2: High reliability requirements
CREATE DATABASE critical_db
VGROUPS 4, BUFFER 256, CACHEMODEL 'last_row', WAL_LEVEL 2, WAL_FSYNC_PERIOD 1000;
Scenario 3: Large-scale historical data
CREATE DATABASE history_db
VGROUPS 10, BUFFER 128, CACHEMODEL 'none', PAGES 512, WAL_LEVEL 1;
Cache configuration checklist
When deploying TDengine, review the following checklist for cache configuration:
- Evaluate data write frequency and peak throughput.
- Analyze query patterns (real-time queries vs. historical analysis).
- Calculate available memory resources.
- Determine the required data reliability level.
- Select the appropriate
cachemodelfor the use case. - Configure a reasonable number of vgroups.
- Set appropriate WAL parameters.
Practical takeaways
TDengine balances high performance and high reliability through its multi-level cache mechanism. The write cache ensures fast access to the newest data, the read cache improves hot query performance, the metadata cache accelerates table structure lookups, and the WAL mechanism safeguards data integrity.
By configuring these cache parameters appropriately, developers can improve TDengine’s performance across different application scenarios. The recommendations in this article provide a starting point for building efficient, reliable time-series data platforms with TDengine.
