edit-icon download-icon

Write data

Last Updated: Jul 09, 2018

HiTSDB SDK uses the Point class, which represents a point in time. A Point object represents data at a time point in a sequence of a time points (a timeline).

Build the Point

Point (time point) can be built using any of several methods. This section provides examples of three such methods.

Note: You need at least one tag key-value pair to build a Point.

Example 1

Build a time point. Time is represented by a timestamp in seconds, and specify the Metric and multiple Tags of the Point data.

  1. // Use ‘seconds’ for the timestamp
  2. int timestamp = (int)(System.currentTimeMillis()/1000);
  3. // Build the Point
  4. Point point = Point.metric("test1")
  5. .tag("tagk1", "tagv1")
  6. .tag("tagk2", "tagv2")
  7. .tag("tagk3", "tagv3")
  8. .timestamp(timestamp).value(123.456)
  9. .build();

Example 2

Build a time point. Time is represented by a timestamp in milliseconds, and specify Map key-value pairs for the Metric and Tag of the Point data.

  1. // Use ‘milliseconds’ for the timestamp
  2. long timestamp = System.currentTimeMillis();
  3. // Use HashMap to represent Tags
  4. Map<String,String> tagsMap = new HashMap<String,String>();
  5. tagsMap.put("tagk1", "tagv1");
  6. tagsMap.put("tagk2", "tagv2");
  7. // Build the Point
  8. Point point = Point.metric("test1")
  9. .tag(tagsMap)
  10. .value(timestamp,123.456)
  11. .build();

Example 3

Build a time point. Use java.util.Date to represent time.

  1. // Use java.util.Date to represent time.
  2. Point point = Point.metric("test1")
  3. .tag("tagk1", "tagv1")
  4. .value(new Date,123.456)
  5. .build();


Write data

HiTSDB-Client provides two ways of putting data: synchronous block and asynchronous non-block.

Synchronous block data putting

Consider building 500 Points and submitting them to HiTSDB.

Sample code

  1. List<Point> points = new ArrayList<Point>();
  2. Build the Points
  3. for(int i = 0; i<500; i++) {
  4. long timestamp = System.currentTimeMillis();
  5. Point point = Point.metric("test1")
  6. .tag("tagk1", "tagv1")
  7. .value(timestamp, Math.random())
  8. .build();
  9. // Manually package data
  10. points.add(point);
  11. }
  12. // Manually package and submit data
  13. tsdb.putSync(points)

Note: The Synchronous put method typically requires manually packaging data points into a batch.

Synchronous put response object

You can choose returned data format and content to suit your needs.

  • Returns a null object with no content. Calling POST /api/put.

    1. Result result = tsdb.putSync(ps);
  • Overview of returns and submissions. Includes the quantity of successes and of returns. Calling POST /api/put?summary=true.

    1. SummaryResult summaryResult = tsdb.putSync(ps,SummaryResult.class);
  • Overview of returns and submissions. Includes the quantity of successes and of returns, and causes of failures. Calling POST /api/put?details=true.

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

Asynchronous non-block data putting

Asynchronous non-block data putting is simple if a Point exists. The client helps you submit data in batch, eliminating the need to manually package data.

If you have no special requirements, asynchronous non-block putting is recommended.

Sample code

  1. // Build the Points
  2. Point point = Point.metric("test1")
  3. .tag("tagk1", "tagv1")
  4. .value(timestamp, Math.random())
  5. .build();
  6. // Directly submit data
  7. tsdb.put(point);

Callback settings of asynchronous non-block data putting

When using asynchronous non-block, set up a callback interface to receive the response of the Put interface.

Sample code

  1. final AtomicLong num = new AtomicLong();
  2. // Callback object
  3. BatchPutCallback cb = new BatchPutCallback() {
  4. @Override
  5. public void response(String address, List<Point> input, Result output) {
  6. long afterNum = num.addAndGet(input.size());
  7. System.out.println("Processing succeeded" + input.size() + ", processed" + afterNum);
  8. }
  9. @Override
  10. public void failed(String address, List<Point> input, Exception ex) {
  11. ex.printStackTrace();
  12. long afterNum = num.addAndGet(input.size());
  13. System.out.println("Processing failed" + input.size() + ", processed" + afterNum);
  14. }
  15. };
  16. HiTSDBConfig config = HiTSDBConfig
  17. .address("example.hitsdb.com", 8242)
  18. .listenBatchPut(cb) // Set up the callback interface
  19. .config();
  20. tsdb = HiTSDBClientFactory.connect(config);

HiTSDB Client provides the following PutCallback interfaces:

  • BatchPutCallback, or call POST /api/put
  • BatchPutSummaryCallback, or call POST /api/put?summary=true
  • BatchPutDetailsCallback, or call POST /api/put?details=true

You can select returned data and content as needed by setting appropriate BatchPutCallback type.

Note: Do not include time-consuming operations in callback methods. If you must run such operations, include them in another work thread.

Thank you! We've received your feedback.