Table Store Java SDK 查詢時序資料 - Tablestore

使用 Java SDK 查詢指定時間軸在時間範圍內的時序資料，並支援按時間排序、選擇返回列和分頁讀取。

前提條件

安裝Tablestore Java SDK並初始化時序模型用戶端。

功能說明

調用 getTimeseriesData 方法，根據完整的時間軸標識和時間範圍查詢單條時間軸中的資料點。查詢範圍包含起始時間，不包含結束時間。

public GetTimeseriesDataResponse getTimeseriesData(GetTimeseriesDataRequest request) throws TableStoreException, ClientException

說明

通過 putTimeseriesData 寫入的資料可以立即通過 getTimeseriesData 查詢。

以下樣本查詢 example_timeseries_table 中 cpu 時間軸最近一小時的資料，並限制單次最多返回 20 行。

TimeseriesClient timeseriesClient = client.asTimeseriesClient();

Map<String, String> tags = new HashMap<>();
tags.put("region", "cn-hangzhou");
tags.put("host", "host_0");
TimeseriesKey timeseriesKey = new TimeseriesKey("cpu", "source_0", tags);

long endTimeInUs = System.currentTimeMillis() * 1000L;
long beginTimeInUs = endTimeInUs - 3600L * 1000L * 1000L;
GetTimeseriesDataRequest request =
        new GetTimeseriesDataRequest("example_timeseries_table");
request.setTimeseriesKey(timeseriesKey);
request.setTimeRange(beginTimeInUs, endTimeInUs);
request.setLimit(20);

GetTimeseriesDataResponse response = timeseriesClient.getTimeseriesData(request);
for (TimeseriesRow row : response.getRows()) {
    System.out.println(row.getTimeInUs());
    System.out.println(row.getFields());
}

參數說明

GetTimeseriesDataRequest 包含以下參數。

名稱	類型	說明
timeseriesTableName（必選）	`String`	時序表名稱。
timeseriesKey（必選）	`TimeseriesKey`	要查詢的完整時間軸標識。各組成項必須與寫入資料時使用的值一致。
beginTimeInUs（必選）	`long`	查詢範圍的起始時間，格式為從 1970-01-01 00:00:00 UTC 開始計算的微秒時間戳記，取值大於等於 `0`。查詢範圍包含該時間。
endTimeInUs（必選）	`long`	查詢範圍的結束時間，格式為微秒時間戳記，取值大於 `0`。查詢範圍不包含該時間。
limit（可選）	`int`	單次請求的最大返回行數。預設值和最大值均為 `5000`。實際返回行數可能因掃描資料量等因素小於該值，可以通過 `nextToken` 繼續讀取。
nextToken（可選）	`byte[]`	分頁令牌。首次請求不設定；響應中的 `nextToken` 不為空白時，將其傳入下一次請求。該令牌是位元據，如需持久化或傳輸，應進行 Base 64 編碼，不能直接使用 `new String(nextToken)` 轉換。
backward（可選）	`boolean`	是否按時間倒序返回資料。預設值為 `false`，表示按時間正序返回。
fieldsToGet（可選）	`List<Pair<String, ColumnType>>`	要返回的資料欄位名稱和類型。不設定時返回全部資料欄位。指定的資料類型與實際類型不同時，該欄位無法讀取。

時間軸標識

timeseriesKey 的類型為 TimeseriesKey，包含以下參數。

名稱	類型	說明
measurementName（必選）	`String`	度量名稱。寫入時設定為空白時，查詢也使用空值。
dataSource（可選）	`String`	資料來源標識。寫入時設定為空白時，查詢也使用空值。
tags（可選）	`SortedMap<String, String>`	標籤資訊，由字串類型的索引值對組成。必須與寫入時的標籤集合一致。

傳回值

GetTimeseriesDataResponse 包含以下業務返回欄位。

欄位	類型	說明
`rows`	`List<TimeseriesRow>`	通過 `getRows()` 擷取本次請求返回的時序資料行。
`nextToken`	`byte[]`	通過 `getNextToken()` 擷取下一頁令牌。值為 `null` 時，表示當前查詢範圍內的資料已全部返回。

時序資料行

rows[] 中每個元素的類型為 TimeseriesRow，包含以下欄位。

欄位	類型	說明
`timeseriesKey`	`TimeseriesKey`	通過 `getTimeseriesKey()` 擷取時間軸標識。
`timeInUs`	`long`	通過 `getTimeInUs()` 擷取資料點時間，單位為微秒。
`fields`	`SortedMap<String, ColumnValue>`	通過 `getFields()` 擷取資料欄位。

情境樣本

分頁讀取全部資料

當一次請求未返回全部資料時，重複傳入響應中的 nextToken，直至傳回值為 null。

byte[] nextToken = null;
do {
    request.setNextToken(nextToken);
    GetTimeseriesDataResponse response =
            timeseriesClient.getTimeseriesData(request);

    for (TimeseriesRow row : response.getRows()) {
        System.out.println(row.getTimeInUs());
        System.out.println(row.getFields());
    }
    nextToken = response.getNextToken();
} while (nextToken != null);