Tablestore：自訂時間軸標識和作為主鍵的資料欄位

自訂時間軸標識

自訂時間軸標識的使用情境主要集中在需要對資料進行精確時間定位、區間查詢、趨勢分析和事件關聯的領域，以下是一些具體的使用案例：

• 故障排查與根本原因分析。

  在 IT 營運和工業裝置監控中，自訂時間軸標識能夠協助精確標記故障發生的時間點，結合其他時序資料（如裝置狀態、日誌資訊），快速定位問題原因，進行根本原因分析。

• 使用者行為分析。

  在互連網應用中，通過記錄使用者的登入時間、頁面瀏覽時間、操作序列等，自訂時間軸標識可以用來分析使用者活躍時段、會話時間長度、行為路徑，進而最佳化使用者體驗、個人化推薦內容。

• 金融交易審計。

  在金融領域，每一筆交易都需要精確的時間戳記錄，自訂時間軸標識不僅用於確保交易的順序性和完整性，還用於反欺詐分析，如識別異常交易模式、追蹤資金流。

通過自訂時間軸標識，可以靈活地對時序資料進行分組、篩選和分析，滿足不同業務情境下對時序資料的精細管理與洞察需求。

配置作為主鍵的資料欄位

當實際業務中存在時間軸標識和時間點相同但是時序資料不同的資料存放區需求時，您可以通過為時序表添加作為主鍵的資料欄位來實現。以下是一些具體的使用情境：

• 事件關聯分析。

  在某些複雜的分析情境中，可能需要根據時間軸標識以外的資料欄位來關聯時序資料。添加作為主鍵的資料欄位可以快速定位到特定裝置在特定時間點的資料，適用於故障排查、行為分析等。

• 多維度索引。

  在時序資料庫的進階應用程式中，如需對資料進行多維度查詢和過濾，添加作為主鍵的資料欄位可以加速查詢效率，特別是在處理海量資料時，能夠更精確地定位到感興趣的時序資料。

• 多租戶時序資料管理。

  在為多個客戶提供時序資料存放區服務時，可能需要在時序資料表中加入租戶 ID 作為其中一個主鍵，與時間戳記一起構成複合主鍵，確保不同租戶的資料隔離和高效訪問。

使用控制台

1. 在建立時序表時，自訂時間軸標識。具體操作，請參考時序表操作。

2. 使用自訂時間軸標識寫入時序資料到時序表。

   寫入資料到時序表時，用戶端中的自訂時間軸識別欄位會以標籤索引值對的形式傳遞給Table Store服務端，Table Store服務端會先從自訂時間軸識別欄位索引值對中提取出度量名稱和資料來源，剩餘索引值對作為時間軸標籤。具體操作，請參考寫入時序資料。

   重要

   在建立時序表時，如果自訂的時間軸標識中未包含標籤欄位 _tags，但在寫入時序資料時，時間軸標識的索引值對中（在排除度量名稱、資料來源和自訂欄位後）仍存在其他剩餘索引值對，則該資料行將無法成功寫入。

3. 讀取時序表中資料。

   1. 為時序表建立 SQL 映射關係。更多資訊，請參見建立多值模型映射關係。

      1. 在時序表管理頁面，單擊 SQL 查詢頁簽。

      2. 單擊 SQL 查詢頁簽下方左側，單擊時序模型執行個體名稱的“+”。

      3. 在建立映射表的對話方塊中，按照如下說明配置映射表資訊。

         參數	描述
         表名	時序表名稱。
         映射表名	映射表名稱。 說明 為時序表建立 SQL 映射關係時，系統會自動在映射表名前添加時序表名::的首碼。
         流量分析儲存查詢	分析儲存功能主要用於時序資料長期儲存和分析情境。流量分析儲存（Analytical Store）功能，您可以低成本儲存時序資料以及快速查詢和分析時序資料。更多資訊，請參見 分析儲存 。 系統預設關閉流量分析儲存查詢開關，請根據實際業務情境進行相應配置。 如果不需要流量分析儲存來儲存與分析時序資料，流量分析儲存查詢保持預設配置即可。 如果需要低成本儲存時序資料以及快速查詢和分析時序資料，請確保已建立分析儲存並開啟流量分析儲存查詢開關。 重要 支援分析儲存功能的地區包括華東1（杭州）、華東2（上海）、華北2（北京）和華北3（張家口）。如需流量分析儲存功能，請在上述地區下建立時序模型執行個體。 如果建立了流量分析儲存查詢的 SQL 映射表，則在刪除分析儲存時，您需要同時刪除分析儲存 SQL 映射表。否則會導致刪除分析儲存失敗。

      4. 單擊產生 SQL，系統會自動產生建立 SQL 映射關係的 SQL 陳述式。

         自訂時間軸標識後，在建立 SQL 映射關係時，需要將時間軸標識和作為主鍵的資料欄位設定為 SQL 映射表的主鍵。

      5. 單擊執行 SQL。

   2. 使用 SELECT 語句查詢資料。

      在 SQL 控制台輸入 SQL 陳述式，單擊執行 SQL。

      以下樣本用於查詢時序表的映射表 cpu::ts1 中 cpu_usage 值超過 90.0 的時間軸資訊。

      SELECT `host`, `processor`, `_tags` , `_time` FROM `cpu::ts1` WHERE cpu_usage > 90.0;

使用 SDK

此處以Java SDK為例介紹自訂時間軸標識的操作。

1. 在建立時序表時，自訂時間軸標識。

   以下樣本用於建立一個不帶分析儲存的時序表，同時自訂時間軸標識。

   private static void createTimeseriesTable(TimeseriesClient client) {
       TimeseriesTableMeta timeseriesTableMeta = new TimeseriesTableMeta("<TIMESERIES_TABLE_NAME>");
       timeseriesTableMeta.setTimeseriesTableOptions(new TimeseriesTableOptions(-1));
       // 自訂時間軸表標識。度量名稱對應名稱為host，資料來源對應名稱為processor，標籤對應名稱為_tags。
       timeseriesTableMeta.addTimeseriesKey("host");
       timeseriesTableMeta.addTimeseriesKey("processor");
       timeseriesTableMeta.addTimeseriesKey("_tags");
       CreateTimeseriesTableRequest request = new CreateTimeseriesTableRequest(timeseriesTableMeta);
       request.setEnableAnalyticalStore(false);
       client.createTimeseriesTable(request);
   }

2. 使用自訂時間軸標識寫入時序資料到時序表。

   寫入資料到時序表時，用戶端中的自訂時間軸識別欄位會以標籤索引值對的形式傳遞給Table Store服務端，Table Store服務端會先從自訂時間軸識別欄位索引值對中提取出度量名稱和資料來源，剩餘索引值對作為時間軸標籤。

   重要

   在建立時序表時，如果自訂的時間軸標識中未包含標籤欄位 _tags，但在寫入時序資料時，時間軸標識的索引值對中（在排除度量名稱、資料來源和自訂欄位後）仍存在其他剩餘索引值對，則該資料行將無法成功寫入。

   以下樣本用於使用自訂時間軸標識寫入 3 行時序資料到時序表中。

   private static void putTimeseriesData(TimeseriesClient client) {
       long timeInUs = System.currentTimeMillis() * 1000;
       List<TimeseriesRow> rows = new ArrayList<TimeseriesRow>();
       for (int i = 0; i < 3; i++) {
           Map<String, String> tags = new HashMap<>();
           // 添加自訂時間軸識別欄位
           tags.put("host", "host_" + i);
           tags.put("processor", String.valueOf(i));
           // 不屬於自訂識別欄位額的索引值對會添加到標籤中
           tags.put("region", "hangzhou");
           TimeseriesKey timeseriesKey = new TimeseriesKey("", "", tags);
           TimeseriesRow row = new TimeseriesRow(timeseriesKey, timeInUs);
           row.addField("cpu_usage", ColumnValue.fromDouble(10.0));
           row.addField("cpu_sys", ColumnValue.fromDouble(5.0));
           rows.add(row);
       }
       String tableName = "<TIMESERIES_TABLE_NAME>";
       PutTimeseriesDataRequest putTimeseriesDataRequest = new PutTimeseriesDataRequest(tableName);
       putTimeseriesDataRequest.setRows(rows);
       client.putTimeseriesData(putTimeseriesDataRequest);
   }

   資料寫入成功後，時序表中的時序資料如下：

   host	processor	_tags	_time	cpu_usage	cpu_sys
   host_0	0	["region=hangzhou"]	1712476524000000	10.0	5.0
   host_1	1	["region=hangzhou"]	1712476524000000	10.0	5.0
   host_2	2	["region=hangzhou"]	1712476524000000	10.0	5.0

3. 使用 SQL 讀取時序表中資料。

   1. 為時序表建立 SQL 映射關係。更多資訊，請參見建立多值模型映射關係。

      自訂時間軸標識後，在建立 SQL 映射關係時，您需要將自訂時間軸標識和時間列設定為 SQL 映射表的主鍵。

      配置樣本如下：

      CREATE TABLE `cpu::ts1` (
          `host` VARCHAR(1024),
          `processor` VARCHAR(1024),
          `_tags` VARCHAR(1024),
          `_time` BIGINT(20),
          `cpu_usage` DOUBLE,
          `cpu_sys` DOUBLE,
          PRIMARY KEY(`host`,`processor`,`_tags`,`_time`)
      );

   2. 使用 SELECT 語句查詢資料。

      以下樣本用於查詢時序表的映射表 cpu::ts1 中 cpu_usage 值超過 90.0 的時間軸資訊。

      SELECT `host`, `processor`, `_tags` , `_time` FROM `cpu::ts1` WHERE cpu_usage > 90.0;

使用控制台

1. 在建立時序表時，配置作為主鍵的資料欄位。具體操作，請參考時序表操作。

2. 寫入時序資料到時序表。

   寫入資料到時序表時，作為主鍵的資料欄位不可為空，使用作為主鍵的資料欄位能夠存入多行相同時間軸標識和時間點的時序資料。具體操作，請參考寫入時序資料。

3. 讀取時序表中資料。

   1. 為時序表建立 SQL 映射關係。更多資訊，請參見建立多值模型映射關係。

      1. 在時序表管理頁面，單擊 SQL 查詢頁簽。

      2. 單擊 SQL 查詢頁簽下方左側，單擊時序模型執行個體名稱的“+”。

      3. 在建立映射表的對話方塊中，按照如下說明配置映射表資訊。

         參數	描述
         表名	時序表名稱
         映射表名	映射表名稱 說明 為時序表建立 SQL 映射關係時，系統會自動在映射表名前添加時序表名::的首碼。
         流量分析儲存查詢	分析儲存功能主要用於時序資料長期儲存和分析情境。流量分析儲存（Analytical Store）功能，您可以低成本儲存時序資料以及快速查詢和分析時序資料。更多資訊，請參見分析儲存。 系統預設關閉流量分析儲存查詢開關，請根據實際業務情境進行相應配置。 如果不需要流量分析儲存來儲存與分析時序資料，流量分析儲存查詢保持預設配置即可。 如果需要低成本儲存時序資料以及快速查詢和分析時序資料，請確保已建立分析儲存並開啟流量分析儲存查詢開關。 重要 支援分析儲存功能的地區包括華東1（杭州）、華東2（上海）、華北2（北京）和華北3（張家口）。如需流量分析儲存功能，請在上述地區下建立時序模型執行個體。 如果建立了流量分析儲存查詢的 SQL 映射表，則在刪除分析儲存時，您需要同時刪除分析儲存 SQL 映射表。否則會導致刪除分析儲存失敗。

      4. 單擊產生 SQL，系統會自動產生建立 SQL 映射關係的 SQL 陳述式。

         為時序表配置作為主鍵的資料欄位後，在建立 SQL 映射關係時，您需要將時間軸標識和作為主鍵的資料欄位設定為 SQL 映射表的主鍵。

      5. 單擊執行 SQL。

   2. 使用 SELECT 語句查詢資料。

      在 SQL 控制台輸入 SQL 陳述式，單擊執行 SQL。

      以下樣本用於查詢時序表的映射表 cpu::ts1 中 cpu_usage 值超過 90.0 的時間軸資訊。

      SELECT `host`, `processor`, `_tags` , `_time` FROM `cpu::ts1` WHERE cpu_usage > 90.0;

使用 SDK

此處以Java SDK為例介紹配置作為主鍵的資料欄位的操作。

1. 在建立時序表時配置作為主鍵的資料欄位。

   以下樣本用於建立一個不帶分析儲存的時序表，同時為其配置作為主鍵的資料欄位。

   private static void createTimeseriesTable(TimeseriesClient client) {
       TimeseriesTableMeta timeseriesTableMeta = new TimeseriesTableMeta("<TIMESERIES_TABLE_NAME>");
       timeseriesTableMeta.setTimeseriesTableOptions(new TimeseriesTableOptions(-1));
       // 添加作為主鍵的資料欄位。
       timeseriesTableMeta.addFieldPrimaryKey("processor", PrimaryKeyType.INTEGER);
       CreateTimeseriesTableRequest request = new CreateTimeseriesTableRequest(timeseriesTableMeta);
       request.setEnableAnalyticalStore(false);
       client.createTimeseriesTable(request);
   }

2. 寫入時序資料到時序表。

   寫入資料到時序表時，作為主鍵的資料欄位不可為空，使用作為主鍵的資料欄位能夠存入多行相同時間軸標識和時間點的時序資料。

   以下樣本用於向時序表中寫入 3 行相同的時間軸標識和時間點的時序資料。

   private static void putTimeseriesData(TimeseriesClient client) {
       long timeInUs = System.currentTimeMillis() * 1000;
       List<TimeseriesRow> rows = new ArrayList<TimeseriesRow>();
       for (int i = 0; i < 3; i++) {
           Map<String, String> tags = new HashMap<>();
           tags.put("region", "hangzhou");
           TimeseriesKey timeseriesKey = new TimeseriesKey("cpu", "host_" + i, tags);
           TimeseriesRow row = new TimeseriesRow(timeseriesKey, timeInUs);
           // 作為主鍵的資料欄位不可為空
           row.addField("processor", ColumnValue.fromLong(i));
           row.addField("cpu_usage", ColumnValue.fromDouble(10.0));
           row.addField("cpu_sys", ColumnValue.fromDouble(5.0));
           rows.add(row);
       }
       String tableName = "<TIMESERIES_TABLE_NAME>";
       PutTimeseriesDataRequest putTimeseriesDataRequest = new PutTimeseriesDataRequest(tableName);
       putTimeseriesDataRequest.setRows(rows);
       client.putTimeseriesData(putTimeseriesDataRequest);
   }

   資料寫入成功後，時序表中的時序資料如下：

   _m_name	_data_source	_tags	_time	processor	cpu_usage	cpu_sys
   cpu	host_0	["region=hangzhou"]	1712476524000000	0	10.0	5.0
   cpu	host_1	["region=hangzhou"]	1712476524000000	1	10.0	5.0
   cpu	host_2	["region=hangzhou"]	1712476524000000	2	10.0	5.0

3. 使用 SQL 讀取時序表中資料。

   1. 為時序表建立 SQL 映射關係。更多資訊，請參見建立多值模型映射關係。

      為時序表配置作為主鍵的資料欄位後，在建立 SQL 映射關係時，您需要將時間軸標識和作為主鍵的資料欄位設定為 SQL 映射表的主鍵。

      配置樣本如下：

      CREATE TABLE `cpu::ts1` (
          `_m_name` VARCHAR(1024),
          `_data_source`  VARCHAR(1024),
          `_tags` VARCHAR(1024),
          `_time` BIGINT(20),
          `processor` BIGINT,
          `cpu_usage` DOUBLE,
          `cpu_sys` DOUBLE,
          PRIMARY KEY(`_m_name`,`_data_source`,`_tags`,`_time`,`processor`)
      );

   2. 使用 SELECT 語句查詢資料。

      以下樣本用於查詢時序表的映射表 cpu::ts1 中 cpu_usage 值超過 90.0 的時間軸資訊。

      SELECT `_m_name`, `_data_source`, `_tags` , `_time`, `processor` FROM `cpu::ts1` WHERE cpu_usage > 90.0;