Tablestore：使用SDK

前提條件

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

注意事項

• 時序模型功能將從2022年05月26日正式開始收費。

• 目前支援使用時序模型功能的地區有華東1（杭州）、華東2（上海）、華北2（北京）、華北3（張家口）、華南1（深圳）、德國（法蘭克福）和新加坡。

介面

使用

您可以使用如下語言的SDK實現時序模型功能。

• Java SDK
• Go SDK

建立時序表

使用CreateTimeseriesTable建立時序表時，需要指定表的配置資訊。

• 參數

  時序表的結構資訊（timeseriesTableMeta）包括表名（timeseriesTableName）和配置資訊（timeseriesTableOptions）的配置，詳細參數說明請參見下表。

  參數	說明
  timeseriesTableName	時序表名。
  timeseriesTableOptions	時序表的配置資訊，包括如下內容： timeToLive：配置時序表的資料存活時間，單位為秒。如果希望資料永不到期，可以設定為-1。您可以通過UpdateTimeseriesTable介面修改。

• 樣本

  建立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介面，您可以批量寫入時序資料。一次PutTimeseriesData調用可以寫入多行資料。

• 參數

  一行時序資料（timeseriesRow）包括時間軸標識（timeseriesKey）和時間軸資料的配置，其中時間軸資料包括資料點的時間（timeInUs）和資料點（fields）。詳細參數說明請參見下表。

  參數	說明
  timeseriesKey	時間軸標識，包括如下內容： measurementName：時間軸的度量名稱。 dataSource：資料來源資訊，可以為空白。 tags：時間軸的標籤資訊，為多個字串的key-value對。
  timeInUs	資料點的時間，單位為微秒。
  fields	資料點，可以由多個名稱（FieldKey）和資料值（FieldValue）對組成。

• 樣本

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

檢索時間軸

• 參數

  metaQueryCondition表示檢索時間軸的條件，包括compositeMetaQueryCondition（組合條件）、measurementMetaQueryCondition（度量名稱條件）、dataSourceMetaQueryCondition（資料來源條件）、tagMetaQueryCondition（標籤條件）、attributeMetaQueryCondition（屬性條件）和updateTimeMetaQueryCondition（更新時間條件）。詳細參數說明請參見下表。

  參數	說明
  compositeMetaQueryCondition	組合條件，包括如下內容： operator：邏輯運算子，可選AND、OR、NOT。 subConditions：子條件列表，通過operator組成複雜查詢條件。
  measurementMetaQueryCondition	度量名稱條件，包括如下內容： operator：關係運算子或首碼匹配條件，關係運算子可選=、!=、>、>=、<、<=。 value：要匹配的度量名稱值，類型為字串。
  dataSourceMetaQueryCondition	資料來源條件，包括如下內容： operator：關係運算子或首碼匹配條件，關係運算子可選=、!=、>、>=、<、<=。 value：要匹配的資料來源值，類型為字串。
  tagMetaQueryCondition	標籤條件，包括如下內容： operator：關係運算子或首碼匹配條件，關係運算子可選=、!=、>、>=、<、<=。 value：要匹配的標籤值，類型為字串。
  attributeMetaQueryCondition	時間軸中繼資料的屬性條件，包括如下內容： operator：關係運算子或首碼匹配條件，關係運算子可選=、!=、>、>=、<、<=。 attributeName：屬性名稱，類型為字串。 value：屬性值，類型為字串。
  updateTimeMetaQueryCondition	時間軸中繼資料的更新時間條件，包括如下內容： operator：關係運算子，可選=、!=、>、>=、<、<=。 timeInUs：時間軸中繼資料更新時間的時間戳記，單位為微秒。

• 樣本

  查詢test_timeseries_table時序表中度量名稱為cpu，標籤中含有os標籤且標籤首碼為"Ubuntu"的所有時間軸。

  private static void queryTimeseriesMeta(TimeseriesClient client) {
      String tableName = "test_timeseries_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);
      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());
      }
  }

查詢時序資料

• 參數

  參數	說明
  timeseriesKey	要查詢的時間軸，包括如下內容： measurementName：時間軸的度量名稱。 dataSource：資料來源資訊，可以為空白。 tags：時間軸的標籤資訊，為多個字串的key-value對。
  timeRange	要查詢的時間範圍，範圍為左閉右開區間。包括如下內容： beginTimeInUs：起始時間。 endTimeInUs：結束時間。
  backward	是否按照時間倒序讀取資料，可用於擷取某條時間軸的最新資料。取值範圍如下： true：按照時間倒序讀取。 false（預設）：按照時間正序讀取。
  fieldsToGet	要擷取的資料列列名。如果不指定，則預設擷取所有列。 重要 fieldsToGet中需要指定要擷取的每一列的列名和類型。如果類型不符，則讀取不到對應列的資料。
  limit	本次最多返回的行數。 說明 limit僅限制最多返回的行數，在滿足條件行數大於limit時，也可能由於掃描資料量等限制導致返回行數少於limit條，此時可以通過nextToken繼續擷取後面的行。
  nextToken	如果一次查詢僅返回了部分合格行，此時response中會包括nextToken，可在下一次請求中指定nextToken用來繼續讀取資料。

• 樣本

  查詢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());
      }
  }