Create a time series table

Create a time series table and configure data and metadata time-to-live (TTL), time series identifiers, data field primary keys, analytical stores, and Lastpoint indexes with Tablestore SDK for Java.

Prerequisites

Install the Tablestore SDK for Java and initialize a time series client.

Description

Call createTimeseriesTable to create a time series table that stores time series data and metadata. The time series table name must be unique among data tables and time series tables in the instance.

public CreateTimeseriesTableResponse createTimeseriesTable(CreateTimeseriesTableRequest request)

The following example creates example_timeseries_table. By default, the time series data TTL is -1, which means that the data does not expire, and no analytical store is created.

TimeseriesClient timeseriesClient = client.asTimeseriesClient();

String tableName = "example_timeseries_table";
TimeseriesTableMeta tableMeta = new TimeseriesTableMeta(tableName);
CreateTimeseriesTableRequest request = new CreateTimeseriesTableRequest(tableMeta);

timeseriesClient.createTimeseriesTable(request);

Parameters

CreateTimeseriesTableRequest contains the following parameters.

Name	Type	Description
timeseriesTableMeta (required)	`TimeseriesTableMeta`	The time series table schema.
analyticalStores (optional)	`List<TimeseriesAnalyticalStore>`	The custom analytical stores. Default value: an empty list. You can create at most one analytical store when you create a time series table.
enableAnalyticalStore (optional)	`boolean`	Specifies whether to create the default analytical store. Default value: `false`. If `analyticalStores` is not configured and this parameter is set to `true`, an analytical store named `default_analytical_store` is created. Its default TTL is `-1`, and its synchronization mode is `SYNC_TYPE_FULL`. If `analyticalStores` is configured, a custom analytical store is created.
lastpointIndexes (optional)	`List<CreateTimeseriesTableRequest.LastpointIndex>`	The Lastpoint indexes to create together with the time series table. Default value: an empty list. You can create at most one Lastpoint index when you create a time series table. A time series table can have up to 10 Lastpoint indexes and analytical stores in total.

Time series table schema

timeseriesTableMeta is of the TimeseriesTableMeta type and contains the following parameters.

Name	Type	Description
timeseriesTableName (required)	`String`	The time series table name. It must be unique among data tables and time series tables in the instance.
timeseriesTableOptions (optional)	`TimeseriesTableOptions`	The time series data TTL settings. Default settings are used if this parameter is not configured.
timeseriesMetaOptions (optional)	`TimeseriesMetaOptions`	The time series metadata settings, including metadata TTL and attribute update settings.
timeseriesKeys (optional)	`List<String>`	The fields that form a custom time series identifier. You can specify up to six fields. By default, a time series identifier consists of the metric name, data source, and tags. For more information, see Customize time series identifiers and data field primary keys.
fieldPrimaryKeys (optional)	`List<PrimaryKeySchema>`	The data fields to use as primary keys. You can specify up to four fields to store multiple rows that have the same time series identifier and timestamp. For more information, see Customize time series identifiers and data field primary keys.

Time series data retention

timeseriesTableMeta.timeseriesTableOptions is of the TimeseriesTableOptions type and contains the following parameter.

Name	Type	Description
timeToLive (optional)	`int`	The time series data TTL in seconds. Default value: `-1`. Set the value to `-1` or an integer of at least 86,400. A value of `-1` means that the data does not expire. Tablestore automatically deletes expired data. After the table is created, you can update the time series table configurations to change the TTL.

Time series metadata

timeseriesTableMeta.timeseriesMetaOptions is of the TimeseriesMetaOptions type and contains the following parameters.

Name	Type	Description
metaTimeToLive (optional)	`int`	The time series metadata TTL in seconds. Set the value to `-1` or an integer of at least 604,800. A value of `-1` means that the metadata does not expire. The value cannot be less than `timeToLive`. If `timeToLive` is `-1`, this parameter must also be `-1`. If you configure a finite TTL, set `allowUpdateAttributes` to `false`.
allowUpdateAttributes (optional)	`boolean`	Specifies whether metadata attribute columns can be updated. If `metaTimeToLive` is finite, this parameter must be set to `false`.

Data field primary keys

Each element in timeseriesTableMeta.fieldPrimaryKeys[] is of the PrimaryKeySchema type and contains the following parameters.

Name	Type	Description
name (required)	`String`	The data field name to use as a primary key.
type (required)	`PrimaryKeyType`	The data field type. Valid values: `INTEGER` and `STRING`.

Analytical store

Each element in analyticalStores[] is of the TimeseriesAnalyticalStore type and contains the following parameters.

Name	Type	Description
analyticalStoreName (required)	`String`	The analytical store name.
timeToLive (optional)	`int`	The analytical store TTL in seconds. Default value: `-1`. Set the value to `-1` or an `int32` integer of at least 2,592,000. A value of `-1` means that the data does not expire.
syncOption (optional)	`AnalyticalStoreSyncType`	The data synchronization mode. Default value: `SYNC_TYPE_FULL`. When you create a time series table, only `SYNC_TYPE_FULL`, which specifies full synchronization, is supported.

Lastpoint index

Each element in lastpointIndexes[] is of the CreateTimeseriesTableRequest.LastpointIndex type and contains the following parameter.

Name	Type	Description
indexName (required)	`String`	The Lastpoint index name. For more information, see Lastpoint indexes.

Examples

Configure the metadata TTL

The following example sets the time series data TTL to 7 days, the metadata TTL to 14 days, and disables metadata attribute updates.

String tableName = "example_timeseries_table";
TimeseriesTableOptions tableOptions = new TimeseriesTableOptions(604800);
TimeseriesTableMeta tableMeta = new TimeseriesTableMeta(tableName, tableOptions);

TimeseriesMetaOptions metaOptions = new TimeseriesMetaOptions();
metaOptions.setMetaTimeToLive(1209600);
metaOptions.setAllowUpdateAttributes(false);
tableMeta.setTimeseriesMetaOptions(metaOptions);

CreateTimeseriesTableRequest request = new CreateTimeseriesTableRequest(tableMeta);
timeseriesClient.createTimeseriesTable(request);

Customize time series identifiers and data field primary keys

Important

Custom time series identifiers and data field primary keys require Tablestore SDK for Java 5.17.1 or later. We recommend that you use the latest SDK version. Before you use these features, make sure that the region of the instance supports them.

The following example uses pk1 and pk2 as the time series identifier and uses field1 and field2 as data field primary keys.

String tableName = "example_timeseries_table";
TimeseriesTableMeta tableMeta = new TimeseriesTableMeta(tableName);
tableMeta.addTimeseriesKey("pk1");
tableMeta.addTimeseriesKey("pk2");
tableMeta.addFieldPrimaryKey("field1", PrimaryKeyType.INTEGER);
tableMeta.addFieldPrimaryKey("field2", PrimaryKeyType.STRING);

CreateTimeseriesTableRequest request = new CreateTimeseriesTableRequest(tableMeta);
timeseriesClient.createTimeseriesTable(request);

Create a Lastpoint index

Important

Lastpoint indexes require Tablestore SDK for Java 5.17.1 or later. We recommend that you use the latest SDK version. To use this feature, create a time series model instance in a supported region. For supported regions, see Lastpoint indexes.

The following example creates example_lastpoint_index together with the time series table.

String tableName = "example_timeseries_table";
TimeseriesTableMeta tableMeta = new TimeseriesTableMeta(tableName);
CreateTimeseriesTableRequest request = new CreateTimeseriesTableRequest(tableMeta);
request.addLastpointIndex(
        new CreateTimeseriesTableRequest.LastpointIndex("example_lastpoint_index"));

timeseriesClient.createTimeseriesTable(request);

Create an analytical store

An analytical store provides cost-effective storage and analysis for time series data. To use this feature, create a time series model instance in a supported region. For supported regions and feature details, see Analytical store.

Default analytical store

Set enableAnalyticalStore to true to create the default analytical store named default_analytical_store.

String tableName = "example_timeseries_table";
TimeseriesTableMeta tableMeta = new TimeseriesTableMeta(tableName);
CreateTimeseriesTableRequest request = new CreateTimeseriesTableRequest(tableMeta);
request.setEnableAnalyticalStore(true);

timeseriesClient.createTimeseriesTable(request);

Custom analytical store

The following example creates example_analytical_store together with the time series table. Data in the analytical store does not expire, and full synchronization is used.

String tableName = "example_timeseries_table";
TimeseriesTableMeta tableMeta = new TimeseriesTableMeta(tableName);
CreateTimeseriesTableRequest request = new CreateTimeseriesTableRequest(tableMeta);

TimeseriesAnalyticalStore analyticalStore =
        new TimeseriesAnalyticalStore("example_analytical_store");
analyticalStore.setTimeToLive(-1);
analyticalStore.setSyncOption(AnalyticalStoreSyncType.SYNC_TYPE_FULL);
request.setAnalyticalStores(Collections.singletonList(analyticalStore));

timeseriesClient.createTimeseriesTable(request);

References

After you create a time series table, write time series data to the table.
After you write data, read time series data from the table.