ApsaraDB for Lindorm (Lindorm) provides the time series engine service that is called Lindorm TSDB. This topic describes how to use the Lindorm TSDB SDK to connect to and use a Lindorm time series database.

Obtain the SDK

You can use one of the following methods to obtain the SDK:
  • Add the Maven dependency
    If you use Maven to create a project, open the pom.xml file, and add the hitsdb-client dependency between the <dependencies> tag pair. The following code provides an example:
    <dependency>
         <groupId>com.aliyun</groupId>
         <artifactId>hitsdb-client</artifactId>
         <version>{version}</version>
    </dependency>
    Note In the sample code, {version} specifies the version number of the SDK. We recommend that you use the latest version.
  • Download the SDK package
    If you do not use Maven or cannot access the Maven warehouse, you can download the SDK package and add the package to your project. To download and add the SDK package to your project, perform the following steps:
    1. Download the following JAR files to build your development environment:
    2. Download the JAR file of the SDK for Java provided by Lindorm TSDB. We recommend that you download the SDK of the latest version.
    3. Add these JAR files to your project. Then, you can use the Lindorm TSDB SDK to connect to and use a Lindorm time series database.

Create a Lindorm TSDB client and connect it to a Lindorm time series database

Before you can use the SDK to connect to Lindorm TSDB, you must create a Lindorm TSDB client. Lindorm TSDB clients provide secure threads. This section describes how to create a TSDB object from the TSDB class. The TSDB object is used as a Lindorm TSDB client.

The TSDB class is an operation class of Lindorm TSDB clients. The objects that are created from the TSDB class are used to write data to, read data from, and perform other operations on time series databases. The following two classes are used to create a TSDB object:
  • TSDBConfig: It is used to configure the basic information for the Lindorm TSDB client.
  • TSDBClientFactory: It is used to encapsulate the Lindorm TSDB client.
Use the TSDBConfig class to configure the client and then use the configuration as the parameter of the connect method of the TSDBClientFactory class to create a TSDB object.
Note Before you create a TSDB object, you must create a TSDBConfig object.
The following sample code shows how to create a Lindorm TSDB client:
// Configure the TSDBConfig parameters and create a TSDBConfig instance. 
TSDBConfig config = TSDBConfig.address("example.tsdb.com",8242).config();  // Replace example.tsdb.com with the domain name or IP address of the time series database of your Lindorm instance. Replace 8242 with the port of the Lindorm time series database of your Lindorm instance. You can log on to the Lindorm console to obtain the domain name and the port of the time series database of your Lindorm instance. 
// Use TSDBClientFactory to create a TSDB object. 
TSDB tsdb = TSDBClientFactory.connect(config);

Use a Lindorm time series database

This section provides examples on how to use the Lindorm TSDB client to write data to and query data from a Lindorm time series database.

Write data

This section describes how to use the SDK to write data into a Lindorm time series database. Before you write data, make sure that you have created a Lindorm TSDB client. The Point class is used to specify the data that you want to write into a time series. You can use the put method of the Lindorm TSDB client to write data points to your Lindorm time series database. The following code provides an example:
// Write a data point per second. 
package com.aliyun.hitsdb.client.example;
import java.io.IOException;
import com.aliyun.hitsdb.client.TSDB;
import com.aliyun.hitsdb.client.TSDBClientFactory;
import com.aliyun.hitsdb.client.TSDBConfig;
import com.aliyun.hitsdb.client.value.request.Point;

public class TestWrite {    
    public static void main(String[] args) throws InterruptedException, IOException {        
        // Create a Lindorm TSDB client.         
        TSDBConfig config = TSDBConfig.address("example.hitsdb.com", 8242).config();        
        TSDB tsdb = TSDBClientFactory.connect(config);        
        // Build data and write it to the time series database.         
        for (int i = 0; i < 3600; i++) {           
             Point point = Point.metric("test").tag("V", "1.0").value(System.currentTimeMillis(), 123.4567).build(); 
             Thread.sleep(1000);  // Write data once per second.             
            tsdb.put(point);        
        }        
        // Close the client to prevent data loss.         
        System.out.println("Close");        
        tsdb.close();    
    }
}

Query data

This section describes how to use the SDK to read data. Before you read data from your Lindorm time series database, make sure that you have created a Lindorm TSDB client. The Query class of the Lindorm TSDB client is used to query data based on specified query conditions. Before you query data, you must specify query conditions. You can use the query method of the Lindorm TSDB client to query the data that meets the specified query conditions. The following code provides an example:
// Query data of the last hour. 
package com.aliyun.hitsdb.client.example;
import java.io.IOException;
import java.util.List;import com.aliyun.hitsdb.client.TSDB;
import com.aliyun.hitsdb.client.TSDBClientFactory;
import com.aliyun.hitsdb.client.TSDBConfig;
import com.aliyun.hitsdb.client.value.request.Query;
import com.aliyun.hitsdb.client.value.request.SubQuery;
import com.aliyun.hitsdb.client.value.response.QueryResult;
import com.aliyun.hitsdb.client.value.type.Aggregator;

public class TestRead {    
    public static void main(String[] args) throws IOException {        
        // Create a Lindorm TSDB client.         
        TSDBConfig config = TSDBConfig.address("example.hitsdb.com", 8242).config();        
        TSDB tsdb = TSDBClientFactory.connect(config);        
        // Specify query conditions and query data.         
        long now = System.currentTimeMillis();        
        // Query data of the last hour.         
        Query query = Query.timeRange(now - 3600 * 1000, now)                
            .sub(SubQuery.metric("test").aggregator(Aggregator.NONE).tag("V", "1.0").build()).build();        
        // Query data.         
        List<QueryResult> result = tsdb.query(query);        
        // Return the result.         
        System.out.println(result);        
        // Close the client to prevent data loss.         
        tsdb.close();    
    }
}