Table Store Java SDK 檢索時間軸中繼資料 - Tablestore

使用 Java SDK 按度量名稱、資料來源、標籤、屬性或更新時間檢索時間軸中繼資料，並支援組合條件和分頁讀取。

前提條件

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

功能說明

調用 queryTimeseriesMeta 方法檢索時序表中的時間軸中繼資料。不設定查詢條件時返回全部時間軸中繼資料；設定查詢條件時，可以按一個或多個時間軸特徵篩選。

public QueryTimeseriesMetaResponse queryTimeseriesMeta(QueryTimeseriesMetaRequest request) throws TableStoreException, ClientException

說明

服務端會為新時間軸非同步構建中繼資料索引。寫入新的時間軸後，需等待索引構建完成才能檢索到對應中繼資料。

以下樣本檢索 example_timeseries_table 中度量名稱為 cpu、且 os 標籤值以 Ubuntu 開頭的時間軸中繼資料。

CompositeMetaQueryCondition condition =
        new CompositeMetaQueryCondition(MetaQueryCompositeOperator.OP_AND);
condition.addSubCondition(new MeasurementMetaQueryCondition(
        MetaQuerySingleOperator.OP_EQUAL, "cpu"));
condition.addSubCondition(new TagMetaQueryCondition(
        MetaQuerySingleOperator.OP_PREFIX, "os", "Ubuntu"));

QueryTimeseriesMetaRequest request =
        new QueryTimeseriesMetaRequest("example_timeseries_table");
request.setCondition(condition);
request.setGetTotalHits(true);
request.setLimit(100);

QueryTimeseriesMetaResponse response =
        timeseriesClient.queryTimeseriesMeta(request);
System.out.println(response.getTotalHits());
for (TimeseriesMeta meta : response.getTimeseriesMetas()) {
    System.out.println(meta);
}

參數說明

QueryTimeseriesMetaRequest 包含以下參數。

名稱	類型	說明
timeseriesTableName（必選）	`String`	時序表名稱。
condition（可選）	`MetaQueryCondition`	時間軸中繼資料檢索條件。不設定時返回全部時間軸中繼資料。
getTotalHits（可選）	`boolean`	是否返回合格時間軸中繼資料總數。預設值為 `false`。
limit（可選）	`int`	單次請求最多返回的時間軸中繼資料條數。僅正值生效；實際返回條數可能小於該值。
nextToken（可選）	`byte[]`	分頁令牌。首次請求不設定；響應中的 `nextToken` 不為 `null` 時，將其傳入下一次請求。不能根據當前頁為空白或返回條數小於 `limit` 判斷檢索結束。該令牌是位元據，如需持久化或傳輸，應進行 Base 64 編碼。

condition 可以使用以下查詢條件類型。字串查詢條件支援 OP_EQUAL、OP_GREATER_THAN、OP_GREATER_EQUAL、OP_LESS_THAN、OP_LESS_EQUAL 和 OP_PREFIX；更新時間查詢條件不支援 OP_PREFIX。

組合查詢條件

condition 的類型為 CompositeMetaQueryCondition 時，包含以下參數。

名稱	類型	說明
operator（必選）	`MetaQueryCompositeOperator`	邏輯運算子，取值為 `OP_AND`、`OP_OR` 或 `OP_NOT`。
subConditions（必選）	`List<MetaQueryCondition>`	要組合的子條件列表，不可為空。子條件也可以是組合查詢條件。

度量名稱查詢條件

condition 的類型為 MeasurementMetaQueryCondition 時，包含以下參數。

名稱	類型	說明
operator（必選）	`MetaQuerySingleOperator`	查詢運算子。
value（必選）	`String`	要匹配的度量名稱。

資料來源查詢條件

condition 的類型為 DataSourceMetaQueryCondition 時，包含以下參數。

名稱	類型	說明
operator（必選）	`MetaQuerySingleOperator`	查詢運算子。
value（必選）	`String`	要匹配的資料來源標識。

標籤查詢條件

condition 的類型為 TagMetaQueryCondition 時，包含以下參數。

名稱	類型	說明
operator（必選）	`MetaQuerySingleOperator`	查詢運算子。
tagName（必選）	`String`	要匹配的標籤名稱，不可為空。
value（必選）	`String`	要匹配的標籤值。

屬性查詢條件

condition 的類型為 AttributeMetaQueryCondition 時，包含以下參數。

名稱	類型	說明
operator（必選）	`MetaQuerySingleOperator`	查詢運算子。
attributeName（必選）	`String`	要匹配的屬性名稱，不可為空。
value（必選）	`String`	要匹配的屬性值。

更新時間查詢條件

condition 的類型為 UpdateTimeMetaQueryCondition 時，包含以下參數。

名稱	類型	說明
operator（必選）	`MetaQuerySingleOperator`	查詢運算子，取值為 `OP_EQUAL`、`OP_GREATER_THAN`、`OP_GREATER_EQUAL`、`OP_LESS_THAN` 或 `OP_LESS_EQUAL`。
timeInUs（必選）	`long`	時間軸中繼資料的最後更新時間，格式為從 1970-01-01 00:00:00 UTC 開始計算的微秒時間戳記。

傳回值

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

欄位	類型	說明
`timeseriesMetas`	`List<TimeseriesMeta>`	通過 `getTimeseriesMetas()` 擷取本次請求返回的時間軸中繼資料。
`totalHits`	`long`	通過 `getTotalHits()` 擷取合格時間軸中繼資料總數。僅當請求將 `getTotalHits` 設定為 `true` 時有效，否則為 `-1`。
`nextToken`	`byte[]`	通過 `getNextToken()` 擷取下一頁令牌。值為 `null` 時，表示結果已全部返回。

時間軸中繼資料

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

欄位	類型	說明
`timeseriesKey`	`TimeseriesKey`	通過 `getTimeseriesKey()` 擷取時間軸標識。
`attributes`	`SortedMap<String, String>`	通過 `getAttributes()` 擷取時間軸中繼資料屬性。
`updateTimeInUs`	`long`	通過 `getUpdateTimeInUs()` 擷取中繼資料最後更新時間，單位為微秒。

時間軸標識

timeseriesMetas[].timeseriesKey 的類型為 TimeseriesKey，包含以下欄位。

欄位	類型	說明
`measurementName`	`String`	通過 `getMeasurementName()` 擷取度量名稱。
`dataSource`	`String`	通過 `getDataSource()` 擷取資料來源標識。
`tags`	`SortedMap<String, String>`	通過 `getTags()` 擷取標籤資訊。

情境樣本

分頁讀取全部中繼資料

當響應中的 nextToken 不為 null 時，重複傳入該令牌，直至全部結果返回。

List<TimeseriesMeta> allMetas = new ArrayList<>();
byte[] nextToken = null;
do {
    request.setNextToken(nextToken);
    QueryTimeseriesMetaResponse response =
            timeseriesClient.queryTimeseriesMeta(request);

    allMetas.addAll(response.getTimeseriesMetas());
    nextToken = response.getNextToken();
} while (nextToken != null);