全部產品
Search
文件中心

Tablestore:通過SDK使用時序模型

更新時間:Jun 30, 2024

通過SDK建立時序表後,您可以寫入時序資料並對時間軸進行檢索以及查詢時序資料。

前提條件

介面

介面

描述

CreateTimeseriesTable

建立一張時序表。

ListTimeseriesTable

擷取當前執行個體下的時序表列表。

DescribeTimeseriesTable

擷取一個時序表的資訊。

UpdateTimeseriesTable

更新時序表的配置資訊。

DeleteTimeseriesTable

刪除一個時序表。

PutTimeseriesData

寫入時序資料。

GetTimeseriesData

查詢某個時間軸的資料。

QueryTimeseriesMeta

檢索時間軸的中繼資料。

UpdateTimeseriesMeta

更新時間軸的中繼資料。

DeleteTimeseriesMeta

刪除時間軸的中繼資料。

使用

您可以使用如下語言的SDK實現時序模型功能。本文Java 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());
    }
}

附錄:管理時序表

建立時序表後,請根據需要執行相應操作。

查詢時序表描述資訊

當需要查詢時序表的TTL配置、時序表狀態、時間軸表的TTL配置等詳細資料時,您可以查詢時序表的描述資訊。

以下樣本用於查詢指定時序表的描述資訊。

private static void describeTimeseriesTable(TimeseriesClient client) {
    // 填寫時序表名稱。
    String tableName = "<TIMESERIES_TABLE>";
    DescribeTimeseriesTableResponse describeTimeseriesTableResponse = client.describeTimeseriesTable(new DescribeTimeseriesTableRequest(tableName));
    TimeseriesTableMeta tableMeta = describeTimeseriesTableResponse.getTimeseriesTableMeta();
    // 查看時序表名。
    System.out.println(tableMeta.getTimeseriesTableName()); 
    // 查看時序表狀態。
    System.out.println(tableMeta.getStatus()); 
    // 查看時序表的TTL配置。
    System.out.println(tableMeta.getTimeseriesTableOptions().getTimeToLive()); 
    // 查看時間軸表的TTL配置。
    System.out.println(tableMeta.getTimeseriesMetaOptions().getMetaTimeToLive()); 
    // 查看是否允許更新時間軸屬性列。
    System.out.println(tableMeta.getTimeseriesMetaOptions().getAllowUpdateAttributes()); 
}

更新時序表

當需要清理時序表中的歷史資料或者延長資料儲存時間長度時,您可以更新時序表的TTL配置資訊或者時間軸表的TTL配置。您還可以更新是否支援修改時間軸屬性列。

以下樣本用於更新指定時序表的TTL為3年。

private static void updateTimeseriesTable(TimeseriesClient client) {
    // 填寫時序表名稱。
    String tableName = "<TIMESERIES_TABLE>";
    UpdateTimeseriesTableRequest updateTimeseriesTableRequest = new UpdateTimeseriesTableRequest(tableName);
    // 更新TTL為3年。
    updateTimeseriesTableRequest.setTimeseriesTableOptions(new TimeseriesTableOptions(86400 * 365 * 3)); 
    client.updateTimeseriesTable(updateTimeseriesTableRequest);

    DescribeTimeseriesTableResponse describeTimeseriesTableResponse = client.describeTimeseriesTable(new DescribeTimeseriesTableRequest(tableName));
    TimeseriesTableMeta tableMeta = describeTimeseriesTableResponse.getTimeseriesTableMeta();
    // 查看更新後時序表的TTL配置。
    System.out.println(tableMeta.getTimeseriesTableOptions().getTimeToLive()); 
}

刪除時序表

當不再需要使用時序表來儲存時序資料時,您可以刪除時序表。

以下樣本用於刪除指定時序表。

private static void deleteTimeseriesTable(TimeseriesClient client) {
    // 填寫時序表名稱。
    String tableName = "<TIMESERIES_TIME>";
    DeleteTimeseriesTableRequest deleteTimeseriesTableRequest = new DeleteTimeseriesTableRequest(tableName);
    client.deleteTimeseriesTable(deleteTimeseriesTableRequest);
}