Overview of methods for writing data to LindormTSDB - Lindorm

LindormTSDB supports six methods for writing data: LindormTSDB SDK for Java, the InfluxDB® line protocol, standard SQL statements, API operations provided by Time Series Database (TSDB), the Prometheus remote write interface, and Apache Flink. Choose a method based on your tech stack and existing infrastructure.

Choose a write method

Scenario	Recommended method
New project, Java application	LindormTSDB SDK for Java
New project, non-Java application	InfluxDB® line protocol
SQL-based application	Standard SQL (JDBC Driver or HTTP SQL API)
Existing TSDB application	TSDB API operations
Prometheus monitoring	Prometheus remote write
Apache Flink application	Apache Flink

Use LindormTSDB SDK for Java

LindormTSDB SDK for Java is built for Java applications. For a complete tutorial, see Use LindormTSDB SDK for Java to connect to and use LindormTSDB.

The SDK supports:

Asynchronous writes: Data is written without blocking your application while waiting for synchronization.
Automatic batch writes: Records are batched automatically, reducing development effort and improving throughput.
Connection pool reuse: Connections are pooled and reused, preventing connection exhaustion under high load.
Automatic retry: Failed requests are retried automatically—no retry logic required in your code.
Efficient encoding: A custom encoding protocol handles data serialization and deserialization efficiently.
Thread safety: All SDK methods are thread-safe, so you can share a single client instance across threads.
Schema constraint policies: Supports three policies—strong constraint, weak constraint, and no constraint.

Example

The following example creates a database and table, writes 10 records asynchronously, and handles the result.

To get the endpoint, see View endpoints.

// Specify the endpoint of LindormTSDB.
String url = "http://ld-bp17j28j2y7pm****-proxy-tsdb-pub.lindorm.rds.aliyuncs.com:8242";

// Create a LindormTSDB client. The client is thread-safe and can be shared across threads.
ClientOptions options = ClientOptions.newBuilder(url).build();
LindormTSDBClient lindormTSDBClient = LindormTSDBFactory.connect(options);

// Create a database and a table.
lindormTSDBClient.execute("CREATE DATABASE demo");
lindormTSDBClient.execute("demo", "CREATE TABLE sensor (device_id VARCHAR TAG, region VARCHAR TAG, time BIGINT, temperature DOUBLE, humidity DOUBLE, PRIMARY KEY(device_id))");

// Build 10 records and write them asynchronously.
int numRecords = 10;
List<Record> records = new ArrayList<>(numRecords);
long currentTime = System.currentTimeMillis();
for (int i = 0; i < numRecords; i++) {
    Record record = Record
        .table("sensor")
        .time(currentTime + i * 1000)
        .tag("device_id", "F07A1260")
        .tag("region", "north-cn")
        .addField("temperature", 12.1 + i)
        .addField("humidity", 45.0 + i)
        .build();
    records.add(record);
}
CompletableFuture<WriteResult> future = lindormTSDBClient.write("demo", records);

// Handle the asynchronous write result.
future.whenComplete((r, ex) -> {
    if (ex != null) {
        System.out.println("Failed to write.");
        if (ex instanceof LindormTSDBException) {
            LindormTSDBException e = (LindormTSDBException) ex;
            System.out.println("Caught a LindormTSDBException: request reached LindormTSDB but was rejected.");
            System.out.println("Error Code: " + e.getCode());
            System.out.println("SQL State:  " + e.getSqlstate());
            System.out.println("Error Message: " + e.getMessage());
        } else {
            ex.printStackTrace();
        }
    } else {
        System.out.println("Write successfully.");
    }
});
System.out.println(future.join());

Use the InfluxDB® line protocol

The InfluxDB® line protocol is recommended for non-Java applications. The default schema constraint policy is weak constraint. For configuration details, see Write data by using the InfluxDB line protocol.

Important

LindormTSDB converts all timestamps to millisecond precision when writing via the line protocol. Data with sub-millisecond precision will lose precision.

Example

curl -X POST \
  'http://ld-bp1489gr5t*****-proxy-tsdb.lindorm.rds.aliyuncs.com:8242/api/v2/write?precision=ms&db=default' \
  -d '
sensor7,device_id=F07A1260,region=north-cn temperature=12.1,humidity=45 1619076780000
sensor7,device_id=F07A1260,region=north-cn temperature=13.2,humidity=47 1619076790000
sensor7,device_id=F07A1260,region=north-cn temperature=10.6,humidity=46 1619076800000
sensor7,device_id=F07A1260,region=north-cn temperature=18.1,humidity=44 1619076780000
sensor7,device_id=F07A1260,region=north-cn temperature=19.7,humidity=44 1619076790000
'

Use standard SQL statements

Two methods are available for writing data with SQL:

Method	Use when	Description	Reference
JDBC Driver	Java applications	Requires implementing connection pool management in your code, or using Druid to manage the pool	Java JDBC Driver
HTTP SQL API	Non-Java applications	Write data using SQL over HTTP-based API calls	Use the HTTP-based SQL API of LindormTSDB

Use TSDB API operations

LindormTSDB is compatible with TSDB API operations. If your application already uses TSDB, you can point it at LindormTSDB without changing the write logic.

Method	Endpoint	Default schema constraint	Notes	References
Write multi-value data	`/api/mput`	No constraint	Time series tables are not created automatically; SQL queries are not available unless you create tables manually or switch to weak constraint. See Select a schema constraint policy.	API: Write multi-value data points / SDK: Use the Lindorm SDK to write multi-value data
Write single-value data	`/api/put`	No constraint	Compatible with OpenTSDB. Not recommended for new workloads on LindormTSDB.	API: Write data / SDK: Write data

Use Prometheus remote write

LindormTSDB can serve as remote storage for Prometheus. After writing data via the remote write interface, query it using PromQL. For setup instructions, see Use Prometheus to connect to and use LindormTSDB.

Use Apache Flink

Write data to LindormTSDB from Flink using the Sink connector, which integrates LindormTSDB SDK for Java. For details, see Use Flink to write data to LindormTSDB.