Create time series tables by using Tablestore SDK for Java - Tablestore

You can call the CreateTimeseriesTable operation to create a time series table. When you create a time series table, you can specify the time to live (TTL) of data in the time series table, configuration information of time series metadata, custom time series identifiers, and custom data fields as the primary key columns of the time series table. You can also create a Lastpoint index and an analytical store. The analytical store can be used to quickly analyze time series data. The Lastpoint index can be used to quickly retrieve data of the latest point in time in time series in the time series table.

Prerequisites

An instance for the TimeSeries model is created. For more information, see Create an instance for the TimeSeries model.
Important
To use the analytical store or Lastpoint index feature, you must create an instance for the TimeSeries model in a region that supports the analytical store or Lastpoint index feature.
A client is initialized. For more information, see Initialize a Tablestore client.

Usage notes

The name of the time series table that you create cannot be the same as the name of an existing data table.
Note
You can call the ListTimeseriesTable operation to query the names of time series tables in an instance. For more information, see Query the names of time series tables.
You can create only one analytical store for a time series table.
The total number of Lastpoint indexes and analytical stores that you create for a time series table cannot exceed 10.
You can specify up to four data fields as the primary key columns of a time series table.
You can specify up to six fields as the fields of custom time series identifiers of a time series table.

Operation

public class CreateTimeseriesTableRequest implements Request {
    /**The schema information of the time series table.*/
    private TimeseriesTableMeta timeseriesTableMeta;
    /**The analytical store information.*/
    private List<TimeseriesAnalyticalStore> analyticalStores = new ArrayList<TimeseriesAnalyticalStore>();
    /**Whether to enable the analytical store feature.*/
    private boolean enableAnalyticalStore = true;
}

Parameters

Parameter	Description
TimeseriesTableMeta	The configurations of the time series table. timeseriesTableName: the name of the time series table. timeseriesMetaOptions: the configurations of the time series metadata. The following parameters are included: metaTimeToLive: the TTL of the time series metadata. Unit: seconds. The value must be -1 or a value that is greater than or equal to 604800. A value of -1 specifies that the metadata never expires. A value of 604800 specifies 7 days. allowUpdateAttributes: specifies whether the property columns of the time series metadata can be modified. You can call the UpdateTimeseriesTable operation to modify the preceding parameters. timeseriesTableOptions: the configurations of the time series table. The following parameter is included: timeToLive: the TTL of the data in the time series table. Unit: seconds. If you do not want the data in the time series table to expire, set this parameter to -1. You can call the UpdateTimeseriesTable operation to modify this parameter. timeseriesKeys: the information of the custom time series identifiers. By default, the time series identifiers consist of the metric name, data source, and tags. For more information, see Specify custom time series identifiers and custom data fields as the primary key columns. This parameter is required when you specify custom time series identifiers. fieldPrimaryKeys: the data fields that are specified as the primary key columns. This parameter allows you to store multiple rows of time series data with the same time series identifiers and timestamp in a time series table. For more information, see Specify custom time series identifiers and custom data fields as the primary key columns. This parameter is required only when you want to store multiple rows of time series data with the same time series identifiers and timestamp in a time series table. lastpointIndexes: the name of the Lastpoint index. For more information, see Lastpoint index.
enableAnalyticalStore	Specifies whether to create the default analytical store. Default value: true, which specifies that the default analytical store is created. After you create an analytical store, you can use the analytical store to store time series data at low costs and query and analyze time series data. For more information, see Analytical store for time series. If you do not want to create an analytical store, set this parameter to false.
analyticalStores	The configurations of the analytical store, which consist of the following items: analyticalStoreName: the name of the analytical store. timeToLive: the TTL of the analytical store. Unit: seconds. You can set timeToLive to -1 or an int32 positive integer that is greater than or equal to 2592000. A value of -1 specifies that data in the analytical store never expires. A value of 2592000 specifies 30 days. syncOption: the data synchronization configuration. The value of this item is fixed to SYNC_TYPE_FULL.

Examples

Create a time series table without an analytical store

The following sample code provides an example on how to create a time series table named test_timeseries_table in which the data never expires:

private static void createTimeseriesTable(TimeseriesClient client) {
    String tableName = "test_timeseries_table";
    TimeseriesTableMeta timeseriesTableMeta = new TimeseriesTableMeta(tableName);
    int timeToLive = -1;
    timeseriesTableMeta.setTimeseriesTableOptions(new TimeseriesTableOptions(timeToLive));
    CreateTimeseriesTableRequest request = new CreateTimeseriesTableRequest(timeseriesTableMeta);
    // Specify that the default analytical store is not created.
    request.setEnableAnalyticalStore(false);    
    client.createTimeseriesTable(request);
}

Create a time series table and an analytical store

When you create a time series table, you can create the default analytical store or a custom analytical store.

Create a time series table and the default analytical store

The following sample code provides an example on how to create a time series table named test_timeseries_table in which the data never expires and the default analytical store at the same time. In this example, the name of the default analytical store is fixed to default_analytical_store and data in the default analytical store never expires.

private static void createTimeseriesTable(TimeseriesClient client) {
    String tableName = "test_timeseries_table";
    TimeseriesTableMeta timeseriesTableMeta = new TimeseriesTableMeta(tableName);
    int timeToLive = -1;
    timeseriesTableMeta.setTimeseriesTableOptions(new TimeseriesTableOptions(timeToLive));
    CreateTimeseriesTableRequest request = new CreateTimeseriesTableRequest(timeseriesTableMeta);
    
    client.createTimeseriesTable(request);
}

Create a time series table and a custom analytical store

The following sample code provides an example on how to create a time series table named test_timeseries_table in which the data never expires and a custom analytical store at the same time. In this example, the name of the custom analytical store is test_analytical_store and data in the custom analytical store never expires.

private static void createTimeseriesTable(TimeseriesClient client) {
    // Specify the name and TTL of the time series table.
    String tableName = "test_timeseries_table";
    TimeseriesTableMeta timeseriesTableMeta = new TimeseriesTableMeta(tableName);
    int timeToLive = -1;
    timeseriesTableMeta.setTimeseriesTableOptions(new TimeseriesTableOptions(timeToLive));
    CreateTimeseriesTableRequest request = new CreateTimeseriesTableRequest(timeseriesTableMeta);

    // Specify the custom analytical store configurations.
    List<TimeseriesAnalyticalStore> analyticalStores = new ArrayList<TimeseriesAnalyticalStore>();
    analyticalStores.add(new TimeseriesAnalyticalStore("test_analytical_store"));
    request.setAnalyticalStores(analyticalStores);

    client.createTimeseriesTable(request);
}

Specify custom time series identifiers and custom data fields as the primary key columns of a time series table

Important

Tablestore SDK for Java V5.17.1 or later allows you to specify custom time series identifiers and custom data fields as the primary key columns of a time series table. When you specify custom time series identifiers and custom data fields as the primary key columns of a time series table, make sure that you use a correct version of Tablestore SDK for Java. For more information, see Version history of Tablestore SDK for Java.

The following sample code provides an example on how to create a time series table in which the time series identifiers consist of pk1 and pk2 and the field1 (Integer), field2 (String), and field3 (Binary) data fields are specified as the primary key columns:

private static void createTimeseriesTable(TimeseriesClient client) {
    String tableName = "test_timeseries_table";
    TimeseriesTableMeta timeseriesTableMeta = new TimeseriesTableMeta(tableName);
    timeseriesTableMeta.addTimeseriesKey("pk1");
    timeseriesTableMeta.addTimeseriesKey("pk2");
    timeseriesTableMeta.addFieldPrimaryKey("field1", PrimaryKeyType.INTEGER);
    timeseriesTableMeta.addFieldPrimaryKey("field2", PrimaryKeyType.STRING);
    timeseriesTableMeta.addFieldPrimaryKey("field3", PrimaryKeyType.BINARY);
    int timeToLive = -1;
    timeseriesTableMeta.setTimeseriesTableOptions(new TimeseriesTableOptions(timeToLive));
    CreateTimeseriesTableRequest request = new CreateTimeseriesTableRequest(timeseriesTableMeta);
    client.createTimeseriesTable(request);
}

Create a time series table and a Lastpoint index

Important

Tablestore SDK for Java V5.17.1 or later supports the Lastpoint index feature. When you use the Lastpoint index feature, make sure that you use a correct version of Tablestore SDK for Java. For more information, see Version history of Tablestore SDK for Java.

The following sample code provides an example on how to create a time series table and a Lastpoint index named index1 for the time series table at the same time:

private static void createTimeseriesTable(TimeseriesClient client) {
    String tableName = "test_timeseries_table";
    TimeseriesTableMeta timeseriesTableMeta = new TimeseriesTableMeta(tableName);
    int timeToLive = -1;
    timeseriesTableMeta.setTimeseriesTableOptions(new TimeseriesTableOptions(timeToLive));
    CreateTimeseriesTableRequest request = new CreateTimeseriesTableRequest(timeseriesTableMeta);
    request.addLastpointIndex(new CreateTimeseriesTableRequest.LastpointIndex("index1"));
    client.createTimeseriesTable(request);
}

References

After you create a time series table, you can write time series data to the table and read time series data from the table. For more information, see Write time series data and Query time series data.
If you want to store time series data at low costs and quickly query and analyze time series data, you can create an analytical store for a time series table. For more information, see Create an analytical store.
For information about how to modify the TTL of data in a time series table, see Modify the configurations of a time series table.
For information about how to query the names of all time series tables in an instance, see Query the names of time series tables.
For information about how to query the information about a time series table, see Query information of a time series table.
For information about how to delete a time series table that you no longer require, see Delete a time series table.
To back up time series data in Tablestore in a cost-effective manner or export time series data as files to local devices, you can use the Data Integration service of DataWorks to synchronize time series data from Tablestore to Object Storage Service (OSS) for storage or download. For more information, see Synchronize data from Tablestore to OSS.
For information about how to connect Tablestore to Grafana to visualize time series data, see Connect Tablestore to Grafana.
If you use Realtime Compute for Apache Flink to compute and analyze data, you can use Tablestore time series tables to store the results. For more information, see Tutorial (TimeSeries model).