自定义时间线标识和作为主键的数据字段

自定义时间线标识

自定义时间线标识的使用场景主要集中在需要对数据进行精确时间定位、区间查询、趋势分析和事件关联的领域，以下是一些具体的使用案例：

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

  在 IT 运维和工业设备监控中，自定义时间线标识能够帮助精确标记故障发生的时间点，结合其他时序数据（如设备状态、日志信息），快速定位问题原因，进行根本原因分析。

• 用户行为分析。

  在互联网应用中，通过记录用户的登录时间、页面浏览时间、操作序列等，自定义时间线标识可以用来分析用户活跃时段、会话时长、行为路径，进而优化用户体验、个性化推荐内容。

• 金融交易审计。

  在金融领域，每一笔交易都需要精确的时间戳记录，自定义时间线标识不仅用于确保交易的顺序性和完整性，还用于反欺诈分析，如识别异常交易模式、追踪资金流。

通过自定义时间线标识，可以灵活地对时序数据进行分组、筛选和分析，满足不同业务场景下对时序数据的精细管理与洞察需求。

配置作为主键的数据字段

当实际业务中存在时间线标识和时间点相同但是时序数据不同的数据存储需求时，您可以通过为时序表添加作为主键的数据字段来实现。以下是一些具体的使用场景：

• 事件关联分析。

  在某些复杂的分析场景中，可能需要根据时间线标识以外的数据字段来关联时序数据。添加作为主键的数据字段可以快速定位到特定设备在特定时间点的数据，适用于故障排查、行为分析等。

• 多维度索引。

  在时序数据库的高级应用中，如需对数据进行多维度查询和过滤，添加作为主键的数据字段可以加速查询效率，特别是在处理海量数据时，能够更精确地定位到感兴趣的时序数据。

• 多租户时序数据管理。

  在为多个客户提供时序数据存储服务时，可能需要在时序数据表中加入租户 ID 作为其中一个主键，与时间戳一起构成复合主键，确保不同租户的数据隔离和高效访问。

使用控制台

1. 在创建时序表时，自定义时间线标识。具体操作，请参考时序表操作。

2. 使用自定义时间线标识写入时序数据到时序表。

   写入数据到时序表时，客户端中的自定义时间线标识字段会以标签键值对的形式传递给表格存储服务端，表格存储服务端会先从自定义时间线标识字段键值对中提取出度量名称和数据源，剩余键值对作为时间线标签。具体操作，请参考写入时序数据。

   重要

   在创建时序表时，如果自定义的时间线标识中未包含标签字段 _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. 使用自定义时间线标识写入时序数据到时序表。

   写入数据到时序表时，客户端中的自定义时间线标识字段会以标签键值对的形式传递给表格存储服务端，表格存储服务端会先从自定义时间线标识字段键值对中提取出度量名称和数据源，剩余键值对作为时间线标签。

   重要

   在创建时序表时，如果自定义的时间线标识中未包含标签字段 _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;