文档

时序表操作

更新时间:

时序模型通过时序表存储时间序列数据,单表能提供高并发写入和查询以及PB级海量数据的低成本存储。创建时序表时,您可以配置数据生命周期和为时序表创建分析存储。创建时序表后,您可以根据实际管理时序表,例如获取实例中的所有时序表名称、更新时序表的配置信息等。

注意事项

  • 单个实例中最多可以创建64张表。其中表包含数据表、二级索引表、Lastpoint索引表和时序表。更多使用限制介绍,请参见时序模型限制

    由于时序表包括时间线元数据表和时间线数据表,因此一个时序表会使用两个表名额。

  • 目前支持使用时序模型功能的地域有华东1(杭州)、华东2(上海)、华北2(北京)、华北3(张家口)、华北6(乌兰察布)、华南1(深圳)、中国香港、德国(法兰克福)、美国(弗吉尼亚)和新加坡。

功能概述

表格存储提供了CreateTimeseriesTableListTimeseriesTableUpdateTimeseriesTableDescribeTimeseriesTableDeleteTimeseriesTable的时序表操作接口。

使用表格存储时序模型存储时序数据前,您需要通过调用CreateTimeseriesTable接口创建一个时序表。

创建时序表时,您需要指定时序表名称以及根据实际配置数据生命周期和时序分析存储

  • 为时序表配置数据生命周期,系统会自动异步清理超过TTL的时序数据。更多信息,请参见时序数据生命周期

  • 为时序表创建默认分析存储或者创建自定义分析存储。使用分析存储功能,您可以低成本存储时序数据以及快速查询和分析时序数据。

    说明

    分析存储功能主要用于时序数据长期存储和分析场景。更多信息,请参见时序分析存储概述

创建时序表后,您可以根据实际需要执行相应操作。

操作

说明

列出时序表名称

当需要查看实例下已有的时序表时,您可以调用ListTimeseriesTable接口获取当前实例下已创建的所有时序表名称。

更新表信息

当需要清理时序表中的历史数据或者希望延长数据保存时间时,您可以调用UpdateTimeseriesTable接口修改时序表数据生命周期、时间线元数据生命周期或者是否允许更新时间线属性列配置。

重要

当存在时间线的保存时间超过时间线元数据TTL时,表格存储会自动异步清理这些时间线元数据,不会删除时序表数据。当通过GetTimeseriesData接口指定时间线标识进行查询时仍可查询到时序表数据。

  • 更新时序表的TTL后,表格存储会自动异步清理时序表中超过TTL的数据。

  • 更新时间线元数据的TTL后,表格存储会自动异步清理超过TTL的时间线元数据。

    重要

    时间线元数据中有一个时间线元数据属性列(_attributes)支持进行更新,但目前仅在时间线元数据生命周期为-1(数据永不过期)时支持该属性的更新。

    如果要将时间线元数据生命周期从-1修改为大于等于7天,请确认业务逻辑中不需要更新时间线元数据属性,并将时间线元数据属性是否允许更新配置为

    如果要将时间线元数据属性是否允许更新配置为,则您需要同步将时间线元数据生命周期调整为-1

  • 时间线元数据属性列默认支持更新,您可以根据需要配置不允许更新时间线元数据属性列。

查询表描述信息

当需要查看时序表的详细配置信息时,您可以调用DescribeTimeseriesTable接口查询时序表的配置信息(例如数据生命周期)、表状态或者时间线元数据配置(例如是否允许更新时间线属性列)。

删除时序表

调用DeleteTimeseriesTable接口删除当前实例下指定时序表。

重要
  • 时序表删除后不支持恢复,请谨慎操作。

  • 删除时序表时,系统会自动删除时序表下的分析存储。

分析存储操作

创建时序表后,您可以调用CreateTimeseriesAnalyticalStore接口为已有时序表创建分析存储。

创建分析存储后,您可以查询分析存储的描述信息、更新分析存储的数据生命周期或者删除分析存储。更多信息,请参见通过控制台使用分析存储或者通过SDK使用分析存储

使用方式

您可以使用控制台、命令行工具或者SDK进行时序表操作。

说明

通过不同使用方式进行操作时支持的功能存在差异,请以实际为准。

进行时序表操作前,您需要完成如下准备工作。

  • 使用阿里云账号或者使用具有表格存储操作权限的RAM用户进行操作。如果需要为RAM用户授权表格存储操作权限,请参见通过RAM Policy为RAM用户授权进行配置。

    使用SDK方式和命令行工具方式进行操作时,如果当前无可用AccessKey,您还需要为阿里云账号或者RAM用户创建AccessKey。具体操作,请参见创建AccessKey

  • 已创建时序模型实例。具体操作,请参见创建时序模型实例

    重要

    如果要使用分析存储功能,请在华东1(杭州)、华东2(上海)、华北2(北京)或者华北3(张家口)地域下创建时序模型实例。更多信息,请参见时序分析存储概述

  • 使用SDK方式进行操作时,还需要完成初始化Client。具体操作,请参见初始化OTSClient

  • 使用命令行工具方式进行操作前,还需要完成下载并启动命令行工具,然后配置接入实例信息。具体操作,请参见下载命令行工具启动并配置接入实例

使用控制台

通过控制台创建一张时序表。

  1. 进入实例管理页面。

    1. 登录表格存储控制台

    2. 在页面上方,选择资源组和地域。

    3. 概览页面,单击实例名称或者单击实例操作实例管理

  2. 实例详情页签,单击时序表列表页签。

  3. 时序表列表页签,单击创建时序表

    说明

    您也可以单击一键生成样例,创建一张测试表以及样例数据来快速体验功能。对于新建的测试表,系统会进行一些初始化操作,因此需要等待几十秒左右才能看到时间线。

  4. 创建时序表对话框,按照如下说明配置时序表信息。

    参数

    描述

    时序表名称

    时序表的名称,用于在实例中唯一标识一张时序表。

    时序表的命名规则为由大小写字母、数字或下划线(_)组成,且只能以字母或下划线(_)开头,长度在1~128个字符之间。

    重要

    时序表的名称不能与当前已存在的数据表、二级索引表和时序表的名称相同。

    数据生命周期

    时序表中数据的过期时间,单位为秒。当系统判断当前时间减去用户传入数据列的时间已经超过设置的数据生命周期时,系统会自动清理超过数据生命周期的数据。

    重要

    在时序表中,系统判断数据产生时间以用户传入的时间列为准,并非数据写入表中的时间。

    取值必须大于等于86400秒(一天)或者必须为-1(数据永不过期)。

    时间线标识

    时间线标识也称为时间序列标识,用来唯一标识一条时间线。时间线标识由度量名称、数据源和标签三部分组成,时间线标识在时序表中对应的名称分别为_m_name、_data_source和_tags。其中标签由多个字符串类型的键值对组成。

    重要

    时序表创建完成后不可变更自定义时间线标识字段,请谨慎操作。

    • 自定义时间线标识字段名称必须由小写字母、数字和下划线组成,且不能以数字开头。长度为1~128个字节。

    • 自定义时间线标识字段数量上限为6。

    说明

    通过单击添加时间线标识,您可以添加多个自定义时间线标识字段;单击自定义时间线标识字段后的fig_20221020_delete图标,可以删除不需要添加的字段。

    主键字段

    当实际业务中存在时间线标识和时间点相同,但是时序数据不同的数据存储需求时,您可以通过为时序表添加作为主键的数据字段来实现。

    重要

    时序表创建完成后不可变更作为主键的数据字段,请谨慎操作。

    • 作为主键的数据字段名称必须由小写字母、数字和下划线组成,且不能以数字开头。长度为1~128个字节。

    • 作为主键的数据字段数量上限为4。

    • 作为主键的数据字段,数据类型可选为字符串整型

    说明

    通过单击添加主键字段,您可以添加多个作为主键的数据字段;单击作为主键的数据字段后的fig_20221020_delete图标,可以删除不需要添加的字段。

    创建分析存储

    分析存储功能主要用于时序数据长期存储和分析场景。使用分析存储(Analytical Store)功能,您可以低成本存储时序数据以及快速查询和分析时序数据。更多信息,请参见时序分析存储概述

    系统默认已开启分析存储,请根据实际业务场景进行分析存储配置。

    • 如果不需要使用分析存储,关闭创建分析存储开关即可。

    • 如果需要创建默认分析存储,创建分析存储保持默认配置即可。

    • 如果需要自定义分析存储,创建分析存储保持默认,打开高级选项开关并配置分析存储名称分析存储生命周期

    创建Lastpoint索引

    Lastpoint索引提供了快速获取时间线最新时间点数据的能力。创建Lastpoint索引后,您可以通过数据读取接口(包括GetRowBatchGetRowGetRange)、SQL或多元索引查询Lastpoint索引表中的数据。

    系统默认关闭创建Lastpoint索引开关,请根据实际业务场景进行Lastpoint索引配置。

    • 如果不需要创建Lastpoint索引,保持默认配置即可。

    • 如果需要创建Lastpoint索引,请打开创建Lastpoint索引开关,并配置Lastpoint索引名称

    说明
    • Lastpoint索引名称必须由字母、数字和下划线组成,且不能以数字开头。长度为1~128个字节。

    • 一个时序表最多只能创建10个Lastpoint索引。

  5. 单击确定

    时序表创建完成后,在时序表列表页签,您可以查看已创建的时序表。如果新建的表未显示在列表中,可单击fig_tablestore_002图标,刷新时序表列表。

创建时序表后,请根据实际需要执行相应操作管理时序表。

功能

描述

更新时序表数据生命周期

  1. 时序表列表页签,单击时序表名称。

  2. 基本详情页签的基本信息区域,单击数据生命周期后的image.png图标。

  3. 在弹出的悬浮框中,修改数据生命周期。

    时序表中数据的过期时间,单位为秒。取值必须大于等于86400秒(一天)或者必须为-1(数据永不过期)。

  4. 单击确定

更新时间线元数据生命周期

  1. 时序表列表页签,单击时序表名称。

  2. 基本详情页签的基本信息区域,单击时间线元数据生命周期后的image.png图标。

  3. 在弹出的悬浮框中,修改数据生命周期。

    时序时间线表的时间线数据存活时间,单位为秒。取值必须大于等于604800秒(即7天)或者必须为-1(数据永不过期)。

  4. 单击确定

更新时间线元数据属性是否允许更新

  1. 时序表列表页签,单击时序表名称。

  2. 基本详情页签的基本信息区域,单击时间线元数据属性是否允许更新后的image.png图标。

  3. 在弹出的悬浮框中,选择是否允许更新时间线属性列。

  4. 单击确定

删除时序表

  1. 时序表列表页签,单击删除

  2. 在弹出的对话框中单击确定

使用命令行工具

通过命令行工具执行create命令创建时序表。更多信息,请参见创建表

以下示例用于创建名称为mytable的时序表,表中数据永不过期。

create -m timeseries -t mytable --ttl -1

执行表操作前,您需要执行use命令选择要使用的表。更多信息,请参见使用表

以下示例用于使用mytable时序表。

use --ts -t mytable

创建并使用时序表后,请根据实际需要执行相应操作管理时序表。

功能

描述

列出时序表名称

执行list命令列出表名称。更多信息,请参见列出表名称

以下示例用于列出所有时序表名称。

list -t

更新表信息

执行alter命令更新表信息。更多信息,请参见更新表

以下示例用于修改当前表的数据生命周期为86400秒(即1天)。

alter --ttl 86400 --ts

查询表描述信息

执行desc命令查看时序表的信息。更多信息,请参见查看表信息

以下示例用于查看mytable时序表的信息。

desc --ts -t mytable

删除时序表

执行drop命令删除不需要的表。更多信息,请参见删除表

以下示例用于删除mytable表。

drop -t mytable --ts -y

使用SDK

您可以使用Java SDKGo SDK创建时序表以及管理时序表。此处以Java SDK为例介绍时序表的创建和管理。

请根据实际场景选择合适的示例进行时序表创建。

说明

如果需要低成本存储时序数据以及快速查询和分析时序数据,您可以为时序表创建分析存储。分析存储功能主要用于时序数据长期存储和分析场景。更多信息,请参见时序分析存储概述

创建不带分析存储的时序表

以下示例用于创建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);
    //不创建默认分析存储。
    request.setEnableAnalyticalStore(false);    
    client.createTimeseriesTable(request);
}

创建时序表时创建默认分析存储

以下示例用于创建test_timeseries_table时序表且该表中数据永不过期,同时创建一个默认分析存储。其中默认分析存储的名称固定为default_analytical_store,且默认分析存储内的数据永不过期。

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

创建时序表时创建自定义分析存储

以下示例用于创建test_timeseries_table时序表且该表中数据永不过期,同时创建一个自定义分析存储。该自定义分析存储的名称为test_analytical_store,且自定义分析存储内的数据永不过期。

private static void createTimeseriesTable(TimeseriesClient client) {
    // 设置时序表名称和TTL。
    String tableName = "test_timeseries_table";
    TimeseriesTableMeta timeseriesTableMeta = new TimeseriesTableMeta(tableName);
    int timeToLive = -1;
    timeseriesTableMeta.setTimeseriesTableOptions(new TimeseriesTableOptions(timeToLive));
    CreateTimeseriesTableRequest request = new CreateTimeseriesTableRequest(timeseriesTableMeta);

    // 自定义分析存储。
    List<TimeseriesAnalyticalStore> analyticalStores = new ArrayList<TimeseriesAnalyticalStore>();
    analyticalStores.add(new TimeseriesAnalyticalStore("test_analytical_store"));
    request.setAnalyticalStores(analyticalStores);

    client.createTimeseriesTable(request);
}

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

重要

表格存储Java SDK从5.17.1版本开始支持自定义时间线标识和作为主键的数据字段功能。使用该功能时,请确保获取了正确的Java SDK版本。关于Java SDK历史迭代版本的更多信息,请参见Java SDK历史迭代版本

以下示例用于创建一张时序表,时间线标识由pk1和pk2构成,同时有三个作为主键的数据字段field1(整型)、field2(字符串类型)和field3(二进制类型)。

private static void createTimeseriesTable(TimeseriesClient client) {
    String tableName = "test_timeseries_table";
    TimeseriesTableMeta timeseriesTableMeta = new TimeseriesTableMeta(tableName);
    timeseriesTableMeta.addTimeseriesKey("pk1");
    timeseriesTableMeta.addTimeseriesKey("pk2");
    timeseriesTableMeta.addFieldPrimaryKey("field1", PrimaryKeyType.INTEGER);
    timeseriesTableMeta.addFieldPrimaryKey("field2", PrimaryKeyType.STRING);
    timeseriesTableMeta.addFieldPrimaryKey("field3", PrimaryKeyType.BINARY);
    int timeToLive = -1;
    timeseriesTableMeta.setTimeseriesTableOptions(new TimeseriesTableOptions(timeToLive));
    CreateTimeseriesTableRequest request = new CreateTimeseriesTableRequest(timeseriesTableMeta);
    client.createTimeseriesTable(request);
}

创建时序表时配置Lastpoint索引

重要

表格存储Java SDK从5.17.1版本开始支持Lastpoint索引功能。使用该功能时,请确保获取了正确的Java SDK版本。关于Java SDK历史迭代版本的更多信息,请参见Java SDK历史迭代版本

以下示例创建一张时序表时同时创建一个名称为index1的Lastpoint索引。

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);
    request.addLastpointIndex(new CreateTimeseriesTableRequest.LastpointIndex("index1"));
    client.createTimeseriesTable(request);
}

创建时序表后,请根据实际需要执行相应操作管理时序表。

列出时序表名称

以下示例用于获取实例下所有时序表的表名。

private static void listTimeseriesTable(TimeseriesClient client) {
    ListTimeseriesTableResponse listTimeseriesTableResponse = client.listTimeseriesTable();
    for (String table : listTimeseriesTableResponse.getTimeseriesTableNames()) {
        System.out.println(table);
    }
}

更新时序表数据生命周期

以下示例用于更新指定时序表的TTL为3年。

private static void updateTimeseriesTable(TimeseriesClient client) {
    // 填写时序表名称。
    String tableName = "<TIMESERIES_TABLE>";
    UpdateTimeseriesTableRequest updateTimeseriesTableRequest = new UpdateTimeseriesTableRequest(tableName);
    // 更新TTL为3年。
    updateTimeseriesTableRequest.setTimeseriesTableOptions(new TimeseriesTableOptions(86400 * 365 * 3)); 
    client.updateTimeseriesTable(updateTimeseriesTableRequest);

    DescribeTimeseriesTableResponse describeTimeseriesTableResponse = client.describeTimeseriesTable(new DescribeTimeseriesTableRequest(tableName));
    TimeseriesTableMeta tableMeta = describeTimeseriesTableResponse.getTimeseriesTableMeta();
    // 查看更新后时序表的TTL配置。
    System.out.println(tableMeta.getTimeseriesTableOptions().getTimeToLive()); 
}

查询时序表描述信息

以下示例用于查询指定时序表的描述信息。

private static void describeTimeseriesTable(TimeseriesClient client) {
    // 填写时序表名称。
    String tableName = "<TIMESERIES_TABLE>";
    DescribeTimeseriesTableResponse describeTimeseriesTableResponse = client.describeTimeseriesTable(new DescribeTimeseriesTableRequest(tableName));
    TimeseriesTableMeta tableMeta = describeTimeseriesTableResponse.getTimeseriesTableMeta();
    // 查看时序表名。
    System.out.println(tableMeta.getTimeseriesTableName()); 
    // 查看时序表状态。
    System.out.println(tableMeta.getStatus()); 
    // 查看时序表的TTL配置。
    System.out.println(tableMeta.getTimeseriesTableOptions().getTimeToLive()); 
    // 查看时间线表的TTL配置。
    System.out.println(tableMeta.getTimeseriesMetaOptions().getMetaTimeToLive()); 
    // 查看是否允许更新时间线属性列。
    System.out.println(tableMeta.getTimeseriesMetaOptions().getAllowUpdateAttributes()); 
    //如果为时序表创建了分析存储,您可以使用如下代码获取时序表的分析存储信息。
    List<TimeseriesAnalyticalStore> analyticalStores = describeTimeseriesTableResponse.getAnalyticalStores(); // 查看时序表的分析存储配置。
    for (TimeseriesAnalyticalStore store : analyticalStores) {
        // 查看分析存储名称。
        System.out.println(store.getAnalyticalStoreName()); 
        // 查看分析存储TTL配置。
        System.out.println(store.getTimeToLive()); 
        // 查看分析存储同步配置。
        System.out.println(store.getSyncOption()); 
    }
}

删除时序表

以下示例用于删除指定时序表。

private static void deleteTimeseriesTable(TimeseriesClient client) {
    // 填写时序表名称。
    String tableName = "<TIMESERIES_TIME>";
    DeleteTimeseriesTableRequest deleteTimeseriesTableRequest = new DeleteTimeseriesTableRequest(tableName);
    client.deleteTimeseriesTable(deleteTimeseriesTableRequest);
}

相关文档

  • 创建时序表后,您可以写入时序数据以及读取表中时序数据。更多信息,请参见基础数据操作

  • 您可以通过时序Writer将时序数据写入时序表。时序Writer支持多表写入、写入状态统计、行级别回调和自定义配置功能。具体操作,请参见使用时序Writer写入时序数据

  • 如果要低成本存储时序数据以及快速查询和分析时序数据,您可以为时序表创建分析存储。更多信息,请参见时序分析存储概述