After you use a Tablestore SDK to create a time series table, you can write time series data to the table, and query time series data in the table.

Prerequisites

A public preview instance for the TimeSeries model is created. For more information, see Create a public preview instance for the TimeSeries model.

Public preview

The TimeSeries model is in public preview in the China (Shanghai), China (Hangzhou), and China (Shenzhen) regions. During the public preview, you can use the TimeSeries model free of charge. To get started with the TimeSeries model, you can log on to the Tablestore console and click Create Public Preview Instance for TimeSeries Model to create a public preview instance for the TimeSeries model. For more information, see Create a public preview instance for the TimeSeries model.

After you create a public preview instance for the TimeSeries model, you can use the Tablestore console, CLI, or SDKs to get started with the TimeSeries model. For more information, see Use the Tablestore console, Use the Tablestore CLI, and Use Tablestore SDKs.

If you have questions, please join the Tablestore technical support group by searching for group ID 11789671 or 23307953 in DingTalk to contact us.

Operations

Operation Description
CreateTimeseriesTable Creates a time series table.
ListTimeseriesTable Queries the time series tables in the current instance.
DescribeTimeseriesTable Queries the information about a time series table.
UpdateTimeseriesTable Updates the configurations of a time series table.
DeleteTimeseriesTable Deletes a time series table.
PutTimeseriesData Writes time series data.
GetTimeseriesData Queries the data in a time series.
QueryTimeseriesMeta Queries the metadata of a time series.
UpdateTimeseriesMeta Updates the metadata of a time series.
DeleteTimeseriesMeta Deletes the metadata of a time series.

Tablestore SDKs

You can use the following Tablestore SDKs to get started with the TimeSeries model:

Create a time series table

When you call the CreateTimeseriesTable operation to create a time series table, you must specify the configurations of the table.

  • Parameters

    The schema information (timeseriesTableMeta) of a time series table includes the name (timeseriesTableName) and configurations (timeseriesTableOptions) of the table. The following table describes the parameters.

    Parameter Description
    timeseriesTableName The name of the time series table.
    timeseriesTableOptions The configurations of the time series table. The configurations include the following content:

    timeToLive: the retention period of the data in the time series table. Unit: seconds. If you want the data in the time series table to never expire, set this parameter to -1. You can call the UpdateTimeseriesTable operation to change the value of this parameter.

  • Example

    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);
        client.createTimeseriesTable(request);
    }

Write time series data

You can call the PutTimeseriesData operation to write multiple rows of time series data at a time.

  • Parameters

    A row of time series data (timeseriesRow) includes the time series identifier (timeseriesKey) and time series data. The time series data includes data points (fields) and the time (timeInUs) of the data points. The following table describes the parameters.

    Parameter Description
    timeseriesKey The identifier of the time series. The identifier includes the following content:
    • measurementName: the measurement name of the time series.
    • dataSource: the data source of the time series. You can leave this parameter empty.
    • tags: the tags of the time series. The tags are multiple key-value pairs of the STRING type.
    timeInUs The time of the data point. Unit: microseconds.
    fields The data points, which can be multiple pairs of names (FieldKey) and data values (FieldValue).
  • Example

    Write multiple rows of time series data to the time series table named test_timeseries_table at a time.

    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");
            // Use 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 (fields). 
            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());
            }
        }
    }

Query time series

  • Parameters

    The metaQueryCondition parameter specifies the conditions for a time series query. The conditions include compositeMetaQueryCondition, measurementMetaQueryCondition, dataSourceMetaQueryCondition, tagMetaQueryCondition, attributeMetaQueryCondition, and updateTimeMetaQueryCondition. The following table describes the parameters.

    Parameter Description
    compositeMetaQueryCondition The composite condition that includes the following content:
    • operator: the logical operator. Valid values: AND, OR, and NOT.
    • subConditions: the subconditions that can be combined by using operators for complex queries.
    measurementMetaQueryCondition The measurement name condition that includes the following content:
    • operator: the relational operator or the prefix match condition. Valid values for the relational operator: =, !=, >, >=, <, and <=.
    • value: the measurement name for a match query. Type: STRING.
    dataSourceMetaQueryCondition The data source condition that includes the following content:
    • operator: the relational operator or the prefix match condition. Valid values for the relational operator: =, !=, >, >=, <, and <=.
    • value: the data source for a match query. Type: STRING.
    tagMetaQueryCondition The tag condition that includes the following content:
    • operator: the relational operator or the prefix match condition. Valid values for the relational operator: =, !=, >, >=, <, and <=.
    • value: the tag for a match query. Type: STRING.
    attributeMetaQueryCondition The attribute condition for the metadata of the time series. The attribute condition includes the following content:
    • operator: the relational operator or the prefix match condition. Valid values for the relational operator: =, !=, >, >=, <, and <=.
    • attributeName: the name of the attribute. Type: STRING.
    • value: the value of the attribute. Type: STRING.
    updateTimeMetaQueryCondition The update time condition for the metadata of the time series. The update time condition includes the following content:
    • operator: the relational operator. Valid values: =, !=, >, >=, <, and <=.
    • timeInUs: the timestamp when the metadata of the time series is updated. Unit: microseconds.
  • Example

    Query all time series in which the measurement name is cpu and the tags include the os tag whose tag value is prefixed with Ubuntu in the 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 in which the measurement name is cpu and the tags include the os tag whose tag value is prefixed with Ubuntu. Condition: 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);
        QueryTimeseriesMetaResponse queryTimeseriesMetaResponse = client.queryTimeseriesMeta(queryTimeseriesMetaRequest);
        System.out.println(queryTimeseriesMetaResponse.getTotalHits());
        for (TimeseriesMeta timeseriesMeta : queryTimeseriesMetaResponse.getTimeseriesMetas()) {
            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());
        }
    }

Query time series data

  • Parameters
    Parameter Description
    timeseriesKey The identifier of the time series that you want to query. The identifier includes the following content:
    • measurementName: the measurement name of the time series.
    • dataSource: the data source of the time series. You can leave this parameter empty.
    • tags: the tags of the time series. The tags are multiple key-value pairs of the STRING type.
    timeRange The time range for the query. The time range includes the following content:
    • beginTimeInUs: the start time.
    • endTimeInUs: the end time.
    backward Specifies whether to sort the query results in reverse chronological order. This allows you to obtain the latest data in a time series. Valid values:
    • true: sorts the query results in reverse chronological order.
    • false: sorts the query results in chronological order. This is the default value.
    fieldsToGet The columns that you want to query. If you do not specify this parameter, all columns are queried.
    Notice When you specify the fieldsToGet parameter, you must specify the name and data type of each column that you want to query. If the specified data type of a column is not that of the column in the time series table, the data of the column cannot be queried.
    limit The maximum number of rows to return.
    Note The limit parameter limits only the maximum number of rows to return. Even if the number of rows that meets the specified conditions exceeds the limit, the number of rows that are returned may be less than the value of the limit parameter due to other limits such as the maximum amount of data for a scan. In this case, you can obtain the remaining rows by using the nextToken parameter.
    nextToken The token that is used to obtain more results. If only some rows that meet the specified conditions are returned in a query, the response contains the nextToken parameter. You can specify the nextToken parameter in the next request to obtain the remaining rows.
  • Example

    Query the time series data that meets the specified conditions in the 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");
        // Use 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 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 query. If you do not specify this parameter, all columns are queried. 
        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 a request again to obtain the remaining data. 
            getTimeseriesDataRequest.setNextToken(getTimeseriesDataResponse.getNextToken());
            getTimeseriesDataResponse = client.getTimeseriesData(getTimeseriesDataRequest);
            System.out.println(getTimeseriesDataResponse.getRows().size());
        }
    }