After you create a time series table by using Tablestore SDKs, you can write time series data to the time series table, retrieve time series and query time series data from the time series table.
Prerequisites
An instance for the TimeSeries model is created. For more information, see Create an instance for the TimeSeries model.
A TimeseriesClient instance is initialized. For more information, see Initialize an OTSClient instance.
Precautions
The TimeSeries model starts charging fees since May 26, 2022.
The TimeSeries model is available in the following regions: China (Hangzhou), China (Shanghai), China (Beijing), China (Zhangjiakou), China (Shenzhen), Germany (Frankfurt), and Singapore (Singapore).
Operations
Operation | Description |
Creates a time series table. | |
Queries the names of time series tables in the current instance. | |
Queries the information about a time series table. | |
Updates the configurations of a time series table. | |
Deletes a time series table. | |
Writes time series data to a time series table. | |
Queries the data in a time series. | |
Retrieves the metadata of a time series. | |
Updates the metadata of a time series. | |
Deletes the metadata of a time series. |
Tablestore SDKs
You can use the following Tablestore SDKs to get started with the TimeSeries model. This topic uses Tablestore SDK for Java as an example.
Step 1: Create a time series table
Call the CreateTimeseriesTable operation to create a time series table to store time series data.
The following sample code provides an example on how to create a time series table named test_timeseries_table whose 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);
client.createTimeseriesTable(request);
}Step 2: Write time series data
After you create a time series table, call the PutTimeseriesData operation to write multiple time series data records to the time series table at a time.
The following sample code provides an example on how to write multiple rows of time series data to a time series table named test_timeseries_table:
private static void putTimeseriesData(TimeseriesClient client) {
List<TimeseriesRow> rows = new ArrayList<TimeseriesRow>();
for (int i = 0; i < 10; i++) {
Map<String, String> tags = new HashMap<String, String>();
tags.put("region", "hangzhou");
tags.put("os", "Ubuntu16.04");
// Specify the measurement name, data source, and tags of a time series to construct the identifier of the time series.
TimeseriesKey timeseriesKey = new TimeseriesKey("cpu", "host_" + i, tags);
// Specify the timeseriesKey and timeInUs parameters to create a row of time series data.
TimeseriesRow row = new TimeseriesRow(timeseriesKey, System.currentTimeMillis() * 1000 + i);
// Add data values.
row.addField("cpu_usage", ColumnValue.fromDouble(10.0));
row.addField("cpu_sys", ColumnValue.fromDouble(5.0));
rows.add(row);
}
String tableName = "test_timeseries_table";
PutTimeseriesDataRequest putTimeseriesDataRequest = new PutTimeseriesDataRequest(tableName);
putTimeseriesDataRequest.setRows(rows);
// Write multiple rows of time series data at a time.
PutTimeseriesDataResponse putTimeseriesDataResponse = client.putTimeseriesData(putTimeseriesDataRequest);
// Check whether all data is written to the time series table.
if (!putTimeseriesDataResponse.isAllSuccess()) {
for (PutTimeseriesDataResponse.FailedRowResult failedRowResult : putTimeseriesDataResponse.getFailedRows()) {
System.out.println(failedRowResult.getIndex());
System.out.println(failedRowResult.getError());
}
}
}Step 3: Retrieve time series
If you are not sure about the information about the time series that you want to query, such as the metric name and data source, call the QueryTimeseriesMeta operation to specify conditions to retrieve all the time series that meet the specified conditions.
Query all time series in which the metric name is cpu and the tags contain the os tag that is prefixed with Ubuntu in a time series table named test_timeseries_table.
private static void queryTimeseriesMeta(TimeseriesClient client) {
String tableName = "test_timeseries_table";
QueryTimeseriesMetaRequest queryTimeseriesMetaRequest = new QueryTimeseriesMetaRequest(tableName);
// Query all time series whose measurement name is cpu and tags include os with the prefix Ubuntu. measurement_name="cpu" and have_prefix(os, "Ubuntu")
CompositeMetaQueryCondition compositeMetaQueryCondition = new CompositeMetaQueryCondition(MetaQueryCompositeOperator.OP_AND);
compositeMetaQueryCondition.addSubCondition(new MeasurementMetaQueryCondition(MetaQuerySingleOperator.OP_EQUAL, "cpu"));
compositeMetaQueryCondition.addSubCondition(new TagMetaQueryCondition(MetaQuerySingleOperator.OP_PREFIX, "os", "Ubuntu"));
queryTimeseriesMetaRequest.setCondition(compositeMetaQueryCondition);
queryTimeseriesMetaRequest.setGetTotalHits(true);
// Specify the maximum number of time series metadata that can be returned for a single request.
queryTimeseriesMetaRequest.setLimit(100);
// Initiate the query.
QueryTimeseriesMetaResponse queryTimeseriesMetaResponse = client.queryTimeseriesMeta(queryTimeseriesMetaRequest);
// Display the total number of time series that meet the query conditions.
System.out.println(queryTimeseriesMetaResponse.getTotalHits());
// Save the request results.
List<TimeseriesMeta> timeseriesMetas = new ArrayList<TimeseriesMeta>();
timeseriesMetas.addAll(queryTimeseriesMetaResponse.getTimeseriesMetas());
// If NextToken is included in the response, you can initiate a new request to obtain the remaining results.
while (queryTimeseriesMetaResponse.getNextToken() != null) {
queryTimeseriesMetaRequest.setNextToken(queryTimeseriesMetaResponse.getNextToken());
queryTimeseriesMetaResponse = client.queryTimeseriesMeta(queryTimeseriesMetaRequest);
timeseriesMetas.addAll(queryTimeseriesMetaResponse.getTimeseriesMetas());
// Specify the maximum number of time series that can be returned.
if (timeseriesMetas.size() >= 1000) {
break;
}
}
System.out.println(timeseriesMetas.size());
for (TimeseriesMeta timeseriesMeta : timeseriesMetas) {
System.out.println(timeseriesMeta.getTimeseriesKey().getMeasurementName());
System.out.println(timeseriesMeta.getTimeseriesKey().getDataSource());
System.out.println(timeseriesMeta.getTimeseriesKey().getTags());
System.out.println(timeseriesMeta.getAttributes());
System.out.println(timeseriesMeta.getUpdateTimeInUs());
}
}Step 4: Query time series data
Call the GetTimeseriesData operation to query the time series data that meets the specified conditions in a time series.
The following sample code provides an example on how to query the time series data that meets the specified conditions in a time series table named test_timeseries_table:
private static void getTimeseriesData(TimeseriesClient client) {
String tableName = "test_timeseries_table";
GetTimeseriesDataRequest getTimeseriesDataRequest = new GetTimeseriesDataRequest(tableName);
Map<String, String> tags = new HashMap<String, String>();
tags.put("region", "hangzhou");
tags.put("os", "Ubuntu16.04");
// Specify the measurement name, data source, and tags of a time series to construct the identifier of the time series.
TimeseriesKey timeseriesKey = new TimeseriesKey("cpu", "host_0", tags);
getTimeseriesDataRequest.setTimeseriesKey(timeseriesKey);
// Specify the time range.
getTimeseriesDataRequest.setTimeRange(0, (System.currentTimeMillis() + 60 * 1000) * 1000);
// Specify the maximum number of rows that you want to return.
getTimeseriesDataRequest.setLimit(10);
// Optional. Specify whether to sort the query results in reverse chronological order. Default value: false. If you set this parameter to true, the query results are sorted in reverse chronological order.
getTimeseriesDataRequest.setBackward(false);
// Optional. Specify the columns that you want to return. If you do not specify this parameter, all columns are returned.
getTimeseriesDataRequest.addFieldToGet("string_1", ColumnType.STRING);
getTimeseriesDataRequest.addFieldToGet("long_1", ColumnType.INTEGER);
GetTimeseriesDataResponse getTimeseriesDataResponse = client.getTimeseriesData(getTimeseriesDataRequest);
System.out.println(getTimeseriesDataResponse.getRows().size());
if (getTimeseriesDataResponse.getNextToken() != null) {
// If the nextToken parameter is not empty, you can initiate another request to obtain the remaining data.
getTimeseriesDataRequest.setNextToken(getTimeseriesDataResponse.getNextToken());
getTimeseriesDataResponse = client.getTimeseriesData(getTimeseriesDataRequest);
System.out.println(getTimeseriesDataResponse.getRows().size());
}
}Appendix: Manage a time series table
After you create a time series table, you can perform operations on the time series table as needed.
Query the information about a time series table
You can query the information about a time series table such as the time to live (TTL) of the data in the time series table, the status of the time series table, and the TTL of the time series metadata.
The following sample code provides an example on how to query the information about a time series table.
private static void describeTimeseriesTable(TimeseriesClient client) {
// Specify the name of the time series table.
String tableName = "<TIMESERIES_TABLE>";
DescribeTimeseriesTableResponse describeTimeseriesTableResponse = client.describeTimeseriesTable(new DescribeTimeseriesTableRequest(tableName));
TimeseriesTableMeta tableMeta = describeTimeseriesTableResponse.getTimeseriesTableMeta();
// View the name of the time series table.
System.out.println(tableMeta.getTimeseriesTableName());
// View the status of the time series table.
System.out.println(tableMeta.getStatus());
// View the TTL of data in the time series table.
System.out.println(tableMeta.getTimeseriesTableOptions().getTimeToLive());
// View the TTL of the time series metadata.
System.out.println(tableMeta.getTimeseriesMetaOptions().getMetaTimeToLive());
// Check whether the property columns of the time series metadata can be modified.
System.out.println(tableMeta.getTimeseriesMetaOptions().getAllowUpdateAttributes());
}Modify the configurations of a time series table
If you want to clear historical data or extend the data retention period for a time series table, you can modify the TTL of the data in the time series table or the TTL of the time series metadata. You can also modify whether to allow updating the property columns of time series metadata.
The following sample code provides an example on how to change the TTL of the data in a time series table to three years.
private static void updateTimeseriesTable(TimeseriesClient client) {
// Specify the name of the time series table.
String tableName = "<TIMESERIES_TABLE>";
UpdateTimeseriesTableRequest updateTimeseriesTableRequest = new UpdateTimeseriesTableRequest(tableName);
// Change the TTL to three years.
updateTimeseriesTableRequest.setTimeseriesTableOptions(new TimeseriesTableOptions(86400 * 365 * 3));
client.updateTimeseriesTable(updateTimeseriesTableRequest);
DescribeTimeseriesTableResponse describeTimeseriesTableResponse = client.describeTimeseriesTable(new DescribeTimeseriesTableRequest(tableName));
TimeseriesTableMeta tableMeta = describeTimeseriesTableResponse.getTimeseriesTableMeta();
// View the modified TTL.
System.out.println(tableMeta.getTimeseriesTableOptions().getTimeToLive());
}Delete a time series table
If you no longer need a time series table to store time series data, you can delete the time series table.
The following sample code provides an example on how to delete a time series table.
private static void deleteTimeseriesTable(TimeseriesClient client) {
// Specify the name of the time series table.
String tableName = "<TIMESERIES_TIME>";
DeleteTimeseriesTableRequest deleteTimeseriesTableRequest = new DeleteTimeseriesTableRequest(tableName);
client.deleteTimeseriesTable(deleteTimeseriesTableRequest);
}