Tablestore：通過SDK使用時序模型

前提條件

• 已建立時序模型執行個體。具體操作，請參見建立時序模型執行個體。

• 已初始化TimeseriesClient。具體操作，請參見初始化OTSClient。

注意事項

目前支援使用時序模型功能的地區有華東1（杭州）、華東2（上海）、華北2（北京）、華北3（張家口）、華北6（烏蘭察布）、華南1（深圳）、中國香港、德國（法蘭克福）、美國（維吉尼亞）、沙特（利雅得）和新加坡。

使用SDK

您可以使用如下語言的SDK實現時序模型功能。本文Java SDK為例介紹時序模型的使用。

• Java SDK：時序模型

• Go SDK：時序模型

步驟一：建立時序表

當使用Table Store時序模型時，您需要使用CreateTimeseriesTable介面建立時序表用於儲存時序資料。

以下樣本用於建立test_timeseries_table時序表，且該表中資料永不到期。

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);
}

步驟二：寫入資料

建立時序表後，您可以使用PutTimeseriesData介面批量寫入時序資料到時序表。

以下樣本用於向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");
        // 通過measurementName、dataSource和tags構建TimeseriesKey。
        TimeseriesKey timeseriesKey = new TimeseriesKey("cpu", "host_" + i, tags);
        // 指定timeseriesKey和timeInUs建立timeseriesRow。
        TimeseriesRow row = new TimeseriesRow(timeseriesKey, System.currentTimeMillis() * 1000 + i);
        // 增加資料值（field）。
        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);
    // 一次寫入多行時序資料。
    PutTimeseriesDataResponse putTimeseriesDataResponse = client.putTimeseriesData(putTimeseriesDataRequest);
    // 檢查是否全部成功。
    if (!putTimeseriesDataResponse.isAllSuccess()) {
        for (PutTimeseriesDataResponse.FailedRowResult failedRowResult : putTimeseriesDataResponse.getFailedRows()) {
            System.out.println(failedRowResult.getIndex());
            System.out.println(failedRowResult.getError());
        }
    }
}

步驟三：檢索時間軸

如果不確定要查詢的時間軸資訊（例如度量名稱、資料來源資訊），請使用QueryTimeseriesMeta介面指定多種條件檢索時間軸。

以下樣本用於查詢指定時序表中度量名稱為cpu，標籤中含有os標籤且標籤首碼為Ubuntu的所有時間軸。

private static void queryTimeseriesMeta(TimeseriesClient client) {
    // 填寫時序表名稱。
    String tableName = "<TIME_SERIES_TABLE>";
    QueryTimeseriesMetaRequest queryTimeseriesMetaRequest = new QueryTimeseriesMetaRequest(tableName);
    // 查詢度量名稱為cpu，標籤中含有os標籤且首碼為"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);
    // 限制單次請求返回的時間軸中繼資料條數。
    queryTimeseriesMetaRequest.setLimit(100);
    // 發起查詢。
    QueryTimeseriesMetaResponse queryTimeseriesMetaResponse = client.queryTimeseriesMeta(queryTimeseriesMetaRequest);
    // 列印合格時間軸的總條數。
    System.out.println(queryTimeseriesMetaResponse.getTotalHits());

    // 儲存請求結果。
    List<TimeseriesMeta> timeseriesMetas = new ArrayList<TimeseriesMeta>();
    timeseriesMetas.addAll(queryTimeseriesMetaResponse.getTimeseriesMetas());

    // 如果有NextToken，可以繼續發起請求擷取。
    while (queryTimeseriesMetaResponse.getNextToken() != null) {
        queryTimeseriesMetaRequest.setNextToken(queryTimeseriesMetaResponse.getNextToken());
        queryTimeseriesMetaResponse = client.queryTimeseriesMeta(queryTimeseriesMetaRequest);
        timeseriesMetas.addAll(queryTimeseriesMetaResponse.getTimeseriesMetas());
        // 限制總共擷取的條數。
        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());
    }
}

步驟四：查詢時序資料

使用GetTimeseriesData介面查詢指定時間軸中合格時序資料。

以下樣本用於查詢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");
    // 通過measurementName、dataSource和tags構建TimeseriesKey。
    TimeseriesKey timeseriesKey = new TimeseriesKey("cpu", "host_0", tags);
    getTimeseriesDataRequest.setTimeseriesKey(timeseriesKey);
    // 指定時間範圍。
    getTimeseriesDataRequest.setTimeRange(0, (System.currentTimeMillis() + 60 * 1000) * 1000);
    // 限制返回行數。
    getTimeseriesDataRequest.setLimit(10);
    // 設定是否倒序讀取資料，可不設定，預設值為false。如果設定為true，則倒序讀取資料。
    getTimeseriesDataRequest.setBackward(false);
    // 設定擷取部分資料列，可不設定，預設擷取全部資料列。
    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) {
        // 如果nextToken不為空白，可以發起下一次請求。
        getTimeseriesDataRequest.setNextToken(getTimeseriesDataResponse.getNextToken());
        getTimeseriesDataResponse = client.getTimeseriesData(getTimeseriesDataRequest);
        System.out.println(getTimeseriesDataResponse.getRows().size());
    }
}

常見問題

• 如何更新時序資料

• 如何刪除時序資料

• 資料寫入時序表後是否可以立即查詢到？