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).
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.
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)
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.
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.
The
response()
method and thefailed()
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 defaultfailed()
method is called. The default failed() method is a void method.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