Write Time Series Data via TSDB SDK Point Objects - Time Series Database

The Time Series Database (TSDB) Java SDK uses the Point class to represent a single data point. To write data, build one or more Point objects and submit them using asynchronous or synchronous mode.

Build a Point object

A Point requires a metric name, at least one tag key-value pair, a value, and a timestamp. Three timestamp formats are supported.

Data schema used in the examples below:

Field	Type	Description
`metric`	string	The measurement name, e.g., `test1`
`tagk1`	tag	Example tag key 1
`tagk2`	tag	Example tag key 2
`tagk3`	tag	Example tag key 3
`value`	double	The measured value
`timestamp`	long or Date	Point in time of the measurement

Important

Every Point must include at least one tag key-value pair.

Seconds timestamp

// Convert milliseconds to seconds.
int timestamp = (int)(System.currentTimeMillis() / 1000);

Point point = Point.metric("test1")
                   .tag("tagk1", "tagv1")
                   .tag("tagk2", "tagv2")
                   .tag("tagk3", "tagv3")
                   .timestamp(timestamp).value(123.456)
                   .build();

Milliseconds timestamp with a HashMap

Use a HashMap to pass multiple tags when the number of tags is dynamic or large.

long timestamp = System.currentTimeMillis();

Map<String, String> tags = new HashMap<String, String>();
tags.put("tagk1", "tagv1");
tags.put("tagk2", "tagv2");

Point point = Point.metric("test1")
                   .tag(tags)
                   .value(timestamp, 123.456)
                   .build();

java.util.Date

Point point = Point.metric("test1")
                   .tag("tagk1", "tagv1")
                   .value(new Date(), 123.456)
                   .build();

Choose a write mode

TSDB supports two write modes:

Mode	Method	Batching	Best for
Asynchronous (recommended)	`tsdb.put(point)`	Automatic	Most use cases
Synchronous	`tsdb.putSync(points)`	Manual	When you need to inspect write results inline

Use asynchronous mode unless you have a specific reason to inspect per-batch results synchronously.

Write data asynchronously

In asynchronous mode, construct a Point and call tsdb.put(). The client automatically batches data points before submitting them.

Point point = Point.metric("test1")
                   .tag("tagk1", "tagv1")
                   .value(timestamp, Math.random())
                   .build();

tsdb.put(point);

Configure a callback interface

To inspect write results in asynchronous mode, configure a callback interface before connecting. The callback tracks successes and failures per batch.

All examples below use the single-value data model. For multi-value data points, replace the callback interface with the corresponding MultiField variant (see Callback interfaces).

final AtomicLong processedCount = new AtomicLong();

BatchPutCallback cb = new BatchPutCallback() {

    @Override
    public void response(String address, List<Point> input, Result output) {
        long total = processedCount.addAndGet(input.size());
        System.out.println("Written: " + input.size() + ", total processed: " + total);
    }

    @Override
    public void failed(String address, List<Point> input, Exception ex) {
        ex.printStackTrace();
        long total = processedCount.addAndGet(input.size());
        System.out.println("Failed: " + input.size() + ", total processed: " + total);
    }
};

TSDBConfig config = TSDBConfig
                        .address("example.hitsdb.com", 8242)
                        .listenBatchPut(cb)    // Register the callback.
                        .config();

tsdb = TSDBClientFactory.connect(config);

When each callback method is triggered:

Method	Triggered when
`response()`	The server accepts and processes the request. The response content varies by callback type.
`failed()`	The server rejects the request — invalid data, traffic throttling, authentication failure, or other errors.

Important

Always implement the failed() method. The default implementation is a no-op void method, so failures are silently ignored if you omit it.

Important

Do not run time-consuming operations inside callback methods. Offload heavy work to separate worker threads.

Callback interfaces

Select the callback interface that matches the write response detail you need.

Single-value data model:

Callback interface	Write mode	Equivalent API
`BatchPutCallback`	Simple	`POST /api/put`
`BatchPutSummaryCallback`	Statistical	`POST /api/put?summary=true`
`BatchPutDetailsCallback`	Detailed	`POST /api/put?details=true`
`BatchPutIgnoreErrorsCallback`	Fault-tolerant	`POST /api/put?ignoreErrors=true`

Multi-value data model:

Callback interface	Write mode	Equivalent API
`MultiFieldbatchPutCallback`	Simple	`POST /api/put`
`MultiFieldbatchPutSummaryCallback`	Statistical	`POST /api/put?summary=true`
`MultiFieldbatchPutDetailsCallback`	Detailed	`POST /api/put?details=true`
`MultiFieldbatchPutIgnoreErrorsCallback`	Fault-tolerant	`POST /api/put?ignoreErrors=true`

For details on response content per write mode, see Write modes and responses.

Write data synchronously

In synchronous mode, build a list of data points manually and call tsdb.putSync().

List<Point> points = new ArrayList<Point>();

for (int i = 0; i < 500; i++) {
    long timestamp = System.currentTimeMillis();
    Point point = Point.metric("test1")
                       .tag("tagk1", "tagv1")
                       .value(timestamp, Math.random())
                       .build();
    points.add(point);
}

tsdb.putSync(points);

Best practices for synchronous writes

Add 500–1,000 data points per batch. Fewer points per call reduces throughput; too many increases memory pressure.
Submit batches from multiple threads concurrently to maximize write throughput.

Synchronous response types

Configure the response type based on what your application needs to verify after each write.

Response type	Code	Equivalent API	Content
Empty object	`Result result = tsdb.putSync(ps);`	`POST /api/put`	No payload
Summary	`SummaryResult summaryResult = tsdb.putSync(ps, SummaryResult.class);`	`POST /api/put?summary=true`	Written count, failed count
Details	`DetailsResult detailsResult = tsdb.putSync(ps, DetailsResult.class);`	`POST /api/put?details=true`	Written count, failed count, failure reasons