Lindorm:Interfaces

Examples of database management and table management

You can perform DDL operations to create, delete, and query databases or tables. The following command can be used to set the schema constraint policy to weak constraint:

// 1. Query existing databases.
String showDatabase = "show databases";
Result result = lindormTSDBClient.execute(showDatabase);
System.out.println("before create, db list: " +  result.getRows().stream().map(e -> (String) e.get(0)).collect(Collectors.toList()));

// 2. Create a database. In this example, a database named demo is created.
String createDatabase = "create database demo";
result = lindormTSDBClient.execute(createDatabase);
System.out.println("create database:" + result.isSuccessful());

// 3. Query existing databases.
result = lindormTSDBClient.execute(showDatabase);
System.out.println("after create, db list: " +  result.getRows().stream().map(e -> (String) e.get(0)).collect(Collectors.toList()));

String database = "demo";

// 4. Query all existing tables.
String showTables = "show tables";
result = lindormTSDBClient.execute(database, showTables);
System.out.println("before create, table list: " +  result.getRows().stream().map(e -> (String) e.get(0)).collect(Collectors.toList()));

// 5. Create a table.
String createTable = "CREATE TABLE sensor (device_id VARCHAR TAG,region VARCHAR TAG,time BIGINT,temperature DOUBLE,humidity DOUBLE,PRIMARY KEY(device_id))";
result = lindormTSDBClient.execute(database, createTable);
System.out.println("create table: " + result.isSuccessful());

// 6. Query existing tables to check whether the table sensor is created.
result = lindormTSDBClient.execute(database, showTables);
System.out.println("after create, table list: " +  result.getRows().stream().map(e -> (String) e.get(0)).collect(Collectors.toList()));

// 7. Query the detailed information about a table.
String describeTable = "describe table sensor";
result = lindormTSDBClient.execute(database, describeTable);
System.out.println("------------ describe table -------------------");
List<String> columns = result.getColumns();
System.out.println("columns: " + columns);
List<String> metadata = result.getMetadata();
System.out.println("metadata: " + metadata);
List<List<Object>> rows = result.getRows();
for (int i = 0, size = rows.size(); i < size; i++) {
    List<Object> row = rows.get(i);
    System.out.println("column #" + i + " : " + row);
}

System.out.println("------------ describe table -------------------");
// 8. Delete a table.
String dropTable = "drop table sensor";
result = lindormTSDBClient.execute(database, dropTable);
System.out.println("drop table: " + result.isSuccessful());

// 9. Query existing tables to check whether the table is deleted.
result = lindormTSDBClient.execute(database, showTables);
System.out.println("after drop, table list: " +  result.getRows().stream().map(e -> (String) e.get(0)).collect(Collectors.toList()));

// 10. Delete a database.
String dropDatabase = "drop database demo";
result = lindormTSDBClient.execute(dropDatabase);
System.out.println("drop database:" + result.isSuccessful());

// 11. Query existing databases to check whether the database is deleted.
result = lindormTSDBClient.execute(showDatabase);
System.out.println("after drop, db list : " +  result.getRows().stream().map(e -> (String) e.get(0)).collect(Collectors.toList()));

Sample results:

before create, db list: [default]
create database:true
after create, db list: [default, demo]
before create, table list: []
create table: true
after create, table list: [sensor]
------------ describe table -------------------
columns: [columnName, typeName, columnKind]
metadata: [VARCHAR, VARCHAR, VARCHAR]
column #0 : [device_id, VARCHAR, TAG]
column #1 : [region, VARCHAR, TAG]
column #2 : [time, TIMESTAMP, TIMESTAMP]
column #3 : [temperature, DOUBLE, FIELD]
column #4 : [humidity, DOUBLE, FIELD]
------------ describe table -------------------
drop table: true
after drop, table list: []
drop database:true
after drop, db list : [default]

Write operation records

LindormTSDB SDK uses a Record object to store the information about a row that is to be written into a table. You must specify the table name, timestamp, tags, field names, and field values in a Record object. The timestamp and tags are used to create indexes.

By default, LindormTSDB SDK verifies the validity of characters when you create a Record object. You can specify the parameter 'false' in the build() method.

Record record = Record
    // The name of the table.
    .table("sensor")
    // The timestamp that is accurate to milliseconds.
    .time(currentTime)
    // The tags.
    .tag("device_id", "F07A1260")
    .tag("region", "north-cn")
    // The field names and field values.
    .addField("temperature", 12.1)
    .addField("humidity", 45.0)
    .build();

Interfaces that use the CompletableFuture object to process write results

• Submit only one write operation record each time.

// Write to the default database. 
CompletableFuture<WriteResult> future = lindormTSDBClient.write(record);

// Write data to a specified database.
String database = "demo";
CompletableFuture<WriteResult> future = lindormTSDBClient.write(database, record);

• Submit multiple write operation records in a batch. We recommend that you use this method. You can use this method to reduce lock contention issues that occur in the pending tasks in the asynchronous queue when you use LindormTSDB SDK to submit tasks.

List<Record> records;
// Write data to the default database.
CompletableFuture<WriteResult> future = lindormTSDBClient.write(records);

// Write data to a specified database.
String database = "demo";
CompletableFuture<WriteResult> future = lindormTSDBClient.write(database, records);

• Process the result returned by the CompletableFuture<WriteResult> object. The following code block shows an example. You can call other methods of the CompletableFuture object based on your business requirements.

CompletableFuture<WriteResult> future = lindormTSDBClient.write(records);
// Process asynchronous write results.
future.whenComplete((r, ex) -> {
    if (ex != null) { // A submission exception occurs. In most cases, the exception is returned because a write operation fails.
        System.out.println("Failed to write.");
        Throwable throwable = ExceptionUtils.getRootCause(ex);
        if (throwable instanceof LindormTSDBException) {
            LindormTSDBException e = (LindormTSDBException) throwable;
            System.out.println("Caught an LindormTSDBException, which means your request made it to Lindorm TSDB, "
                               + "but was rejected with an error response for some reason.");
            System.out.println("Error Code: " + e.getCode());
            System.out.println("SQL State:  " + e.getSqlstate());
            System.out.println("Error Message: " + e.getMessage());
        }  else {
            throwable.printStackTrace();
        }
    } else  { // The write operation is successful.
        if (r.isSuccessful()) {
            System.out.println("Write successfully.");
        } else {
            System.out.println("Write failure.");
        }
    }
});

Interfaces that use callback functions to process asynchronous write results

• The following code block shows a write callback. The result parameter in the onCompletion method indicates the write result, the records parameter indicates the write operation record that corresponds to the callback, and the e parameter indicates the exception that is thrown when a write operation failure occurs.

public interface Callback {
    void onCompletion(WriteResult result, List<Record> records, Throwable e);
}

The following example shows how to use a callback to process write results:

Callback callback =  new Callback() {
    @Override
    public void onCompletion(WriteResult result, List<Record> list,
                             Throwable throwable) {
        if (throwable != null) { // Write operation failure.
            if (throwable instanceof LindormTSDBException) {
                LindormTSDBException ex = (LindormTSDBException) throwable;
                System.out.println("errorCode: " + ex.getCode());
                System.out.println("sqlstate: " + ex.getSqlstate());
                System.out.println("message: " + ex.getMessage());
            } else {
                // Other errors.
                throwable.printStackTrace();
            }
        } else {
            if (result.isSuccessful()) {
                System.out.println("Write successfully.");
            } else {
                System.out.println("Write failure.");
            }
        }
    }
};

• Submit only one write operation record each time.

// Write data to the default database. 
lindormTSDBClient.write(record, callback);

// Write data to a specified database.
String database = "demo";
lindormTSDBClient.write(database, record, callback);

• Submit multiple write operation records in a batch. We recommend that you use this method. You can use this method to reduce lock contention issues that occur in the pending tasks in the asynchronous queue when you use LindormTSDB SDK to submit tasks.

List<Record> records;
// Write data to the default database.
lindormTSDBClient.write(records, callback);

// Write data to a specified database.
String database = "demo";
lindormTSDBClient.write(database, records, callback);