All Products
Search
Document Center

Write data

Last Updated: Aug 25, 2021

In Time Series Database (TSDB) SDK, the Point class specifies a point in time. A Point object is a data point at a point in time in a time series (also known as timeline).

In TSDB SDK, the Point class specifies a point in time. A Point object is a data point at a point in time in a time series (also known as timeline).

Construct a Point object

You can use different methods to construct a Point object in different formats. This topic describes three methods of how to construct a Point object and provides an example for each of the methods.

Notice

To construct a Point object, you must specify at least one tag key-value pair.

Example 1

When you construct a Point object, use a timestamp measured in seconds to specify the time of the data point and specify the metric and tags for the data point.

// Use a timestamp measured in seconds.
int timestamp = (int)(System.currentTimeMillis()/1000);

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

Example 2

When you construct a Point object, use a timestamp measured in milliseconds to specify the time of the data point, specify the metric, and then use a HashMap to specify tags for the data point.

// Use a timestamp measured in milliseconds.
long timestamp = System.currentTimeMillis();

// Use a HashMap to specify tags.
Map<String,String> tagsMap = new HashMap<String,String>();
tagsMap.put("tagk1", "tagv1");
tagsMap.put("tagk2", "tagv2");

// Construct a Point object.
Point point = Point.metric("test1")
                    .tag(tagsMap)
                   .value(timestamp,123.456)
                   .build();

Example 3

When you construct a Point object, Use java.util.Date to specify the time of the data point.

// Use java.util.Date to specify the time of the data point to be constructed. 
Point point = Point.metric("test1")
                    .tag("tagk1", "tagv1")
                   .value(new Date,123.456)
                   .build();

Write data

A TSDB client provides two data write modes: the synchronous mode and the asynchronous mode.

Synchronous mode

For example, you need to construct 500 data points and submit these data points to TSDB.

Sample code

List<Point> points = new ArrayList<Point>();
// Construct data points.
for(int i = 0; i<500; i++) {
    long timestamp = System.currentTimeMillis();
    Point point = Point.metric("test1")
                   .tag("tagk1", "tagv1")
                   .value(timestamp, Math.random())
                   .build();
    // Manually add the points into a list.
    points.add(point);
}

// Submit the list.
tsdb.putSync(points)
Notice

In most cases, to ensure high performance of synchronous writes, you need to manually add the constructed data points into a list. We recommend that you add 500 to 1,000 data points into each list. We recommend that you use multiple threads to concurrently submit the data points.

Responses of synchronous writes

You can specify the information included in responses based on your business requirements.

  • If you want the system to return an empty object for your request, use the following configuration. This way, the result returned is the same as the result of calling POST /api/put.

    Result result = tsdb.putSync(ps);
  • If you want the system to return a summary for your request, use the following configuration. This way, the result returned is the same as the result of calling POST/api/put?summary=true. The summary contains only the number of data points that were written and the number of data points that failed to be written.

    SummaryResult summaryResult = tsdb.putSync(ps,SummaryResult.class);
  • If you want the system to return a summary for your request, use the following configuration. This way, the result returned is the same as the result of calling POST/api/put?details=true. The summary contains only the number of data points that were written, the number of data points that failed to be written, and the causes of the write failures.

    DetailsResult detailsResult = tsdb.putSync(ps,DetailsResult.class);

Asynchronous mode

Asynchronous writes are simpler than synchronous writes. You need only to construct data points and then submit these data points. The TSDB client automatically add the data points into a list before the data points are submitted.

If you have no special requirements, we recommend that you write data in asynchronous mode.

Sample code

// Construct data points.
Point point = Point.metric("test1")
                   .tag("tagk1", "tagv1")
                   .value(timestamp, Math.random())
                   .build();
// Submit data points.
tsdb.put(point);

Callback settings for the asynchronous mode

If you write data in asynchronous mode and want to obtain the response of calling an PUT operation, configure a callback interface.

Sample code

final AtomicLong num = new AtomicLong();

// Construct a callback object.
BatchPutCallback cb = new BatchPutCallback() {

    @Override
    public void response(String address, List<Point> input, Result output) {
        long afterNum = num.addAndGet(input.size());
        System.out.println("Successful" + input.size() + ", Processed" + afterNum);
    }

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

};

TSDBConfig config = TSDBConfig
                        .address("example.hitsdb.com", 8242)
                        .listenBatchPut(cb)    // Configure a callback interface.
                        .config();

tsdb = TSDBClientFactory.connect(config);

The TSDB client provides the following four callback interfaces:

  • BatchPutCallback: If you write data in simple mode, use this interface. The API operation is POST /api/put.

  • BatchPutSummaryCallback: If you write data in statistical mode, use this interface. The API operation is POST /api/put?summary=true

  • BatchPutDetailsCallback: If you write data in detailed mode, use this interface. The API operation is POST /api/put?details=true

  • BatchPutIgnoreErrorsCallback: If you write data in fault-tolerant mode, use this interface. The API operation is POST /api/put?ignoreErrors=true

Configure a callback interface based on your business requirements. For more information about the write modes and application scenarios, see Write modes and responses.

Notice

  1. When you configure a callback method, do not specify time-consuming operations in the callback method. If you need to perform time-consuming operations, perform the operations on other worker threads.

  2. The response() method and the failed() method are called in different situations:

    • If your request is valid and is processed by the server, the response() method is called. The responses vary by the type of the callback object.

    • If your request is rejected by the server because the request contains invalid messages, triggers traffic throttling, fails the authentication, or is identified as invalid due to other reasons, the failed() method is called.

    We recommend that you implement the failed() method when you implement the callback interface. If the failed() method is not implemented, the default failed() method is called. The default failed() method is a void method.

  3. In the sample code for the callback interfaces provided in this topic, the single-value data model is used to write data. The methods of writing multi-value data points are similar to the methods of writing single-value data points. The difference is that you must replace the callback interface with the corresponding callback interface provided in the following list:

    • MultiFieldbatchPutCallback

    • MultiFieldbatchPutSummaryCallback

    • MultiFieldbatchPutDetailsCallback

    • MultiFieldbatchPutIgnoreErrorsCallback