Write data
High-volume time series workloads require careful write configuration to avoid throughput bottlenecks. This topic explains how to configure batch size, concurrency, write mode, and consumer threads to maximize write performance in TSDB.
Batch writes and concurrency
Submit data points in batches rather than one at a time. Batching reduces network overhead and significantly improves overall throughput.
For best results, run more than 256 concurrent tasks, each submitting more than 400 data points per batch.
By default, the SDK batches 500 data points per asynchronous submission.
Manage SDK instances
Create a single global instance per process. The TSDB SDK is designed to be instantiated once and shared across all write and query operations within the same process.
| Task | Method | Notes |
|---|---|---|
| Write data | putXXX() | Call directly on the global instance |
| Query data | queryXXX() | Call directly on the global instance |
| Shut down | close() | Closes the TSDB connection; call only when destroying the instance |
Calling close() is not required for write or query operations. Call it only when you want to shut down the TSDB connection entirely.Choose between async and sync writes
The SDK supports two write modes. Choose based on your throughput requirements and how your application handles back pressure.
Async writes with put()
put() adds data points to an internal SDK queue. Consumer threads drain the queue and forward batches to the TSDB server. Each batch contains at most the configured number of data points.
Use put() when:
Throughput is the primary concern
Your application can tolerate brief queuing delays
You want the SDK to handle batching automatically
Sync writes with putSync()
putSync() sends data points directly to the TSDB server without queuing. Performance scales with the number of data points submitted in each call.
Use putSync() when:
You need immediate confirmation that data has been received
Your application manages its own queue and calls
putSync()from within a queue consumer
Configure consumer threads
The SDK uses one consumer thread by default for asynchronous writes. If your write transactions per second (TPS) is high and the default throughput is insufficient, increase the number of consumer threads based on your load.