Tablestore CLI提供简洁、方便的管理命令,支持Windows、Linux、Mac平台。本文介绍如何使用Tablestore CLI以命令行的方式管理表格存储的数据。

下载

Tablestore CLI的运行平台以及对应的下载地址请参见下表。
平台 下载地址
Windows Windows10
Linux
Mac Mac

前提条件

快速开始

使用Tablestore CLI操作表格存储中的数据。

  1. 执行./ts命令,启动命令行工具。

    如果在Linux系统或者Mac系统下无可执行权限,请执行chmod 755 ts命令赋权后再启动命令行工具。

  2. 执行以下命令配置表格存储实例的接入信息。
    config --endpoint https://myinstance.cn-hangzhou.ots.aliyuncs.com --instance myinstance --id NTSVLeBHzgX2iZfcaXXPJ**** --key 7NR2DiotscDbauohSq9kSHX8BDp99bjs7eNpCR7o****
  3. (可选)执行lt命令,查看当前实例下的所有表。
  4. 执行以下命令创建数据表。

    创建名称为mytable的数据表,该数据表有uid(string类型)和pid(integer类型)两个主键列,数据生命周期为864000秒(10天)且最大版本数为1。

    create -t mytable --pk '[{"c":"uid","t":"string"}, {"c":"pid","t":"integer"}]' --ttl 864000 --version 1
  5. (可选)执行desc -t mytable命令,查看表信息。
  6. 执行use -t mytable命令,使用数据表。
  7. 执行以下命令读写数据。
    • 写入数据
      put --pk '["86", 6771]' --attr '[{"c":"name", "v":"redchen1"}, {"c":"country", "v":"china"}]'
      put --pk '["86", 6772]' --attr '[{"c":"name", "v":"redchen2"}, {"c":"country", "v":"china"}]'
      put --pk '["86", 6773]' --attr '[{"c":"name", "v":"redchen3"}, {"c":"country", "v":"china"}]'
      put --pk '["86", 6774]' --attr '[{"c":"name", "v":"redchen4"}, {"c":"country", "v":"china"}]'
    • 读取数据
      get --pk '["86",6771]'
      get --pk '["86",6772]'
      get --pk '["86",6773]'
      get --pk '["86",6774]'
  8. (可选)执行drop -t mytable -y命令,删除数据表。

查看选项

通过help选项来查看Tablestore CLI支持的所有option。

  • 命令格式
    ./ts help
  • 返回结果
    Commands:
      alter                  Alter table 更新表信息
      clear                  Clear the screen 清空屏幕
      config                 Config the Tablestore access information 配置访问Tablestore的基本信息
      create                 Create a new table 创建表
      del                    Delete the specify row from Tablestore 删除一行数据
      desc                   Show table meta 查询表描述信息
      drop                   Drop the table 删除表
      exit                   Exit the program 
      export                 Export the data of table to disk from Tablestore, not support multi version 表数据导出本地文件,不支持数据多版本
      get                    Get specify row from Tablestore 读取一行数据
      help                   Display help
      import                 Load the data to Tablestore, not support multi version 本地文件数据导入表
      list                   List all tables 列出表名称
      points                 Logically divide the data of the full table into several shards close to the specified size
      press_check            Check data for press 检查压测状态
      press_input            Input data for press 开启压测
      put                    Insert a row to Tablestore 插入一行数据
      quit                   Quit the program
      update                 Insert a row to Tablestore 更新一行数据
      use                    Select table 选择进行数据操作的表

初始化

配置对应的接入信息,请根据实际情况修改对应的字段。

  • 命令格式
    config --endpoint endpoint --instance instanceName --id accessKeyId --key accessKeySecret
    配置项说明请参见下表。
    配置项 示例值 说明
    --endpoint https://myinstance.cn-hangzhou.ots.aliyuncs.com 实例的服务地址。更多信息,请参见服务地址
    --instance myinstance 实例名称。
    --id NTSVLeBHzgX2iZfcaXXPJ**** RAM用户的AccessKey ID和AccessKey Secret。
    --key 7NR2DiotscDbauohSq9kSHX8BDp99bjs7eNpCR7o****
  • 示例
    config --endpoint https://myinstance.cn-hangzhou.ots.aliyuncs.com --instance myinstance --id NTSVLeBHzgX2iZfcaXXPJ**** --key 7NR2DiotscDbauohSq9kSHX8BDp99bjs7eNpCR7o****

表操作

通过Tablestore CLI可以对表进行的操作,包括创建表、选择进行操作的表,列出表名称,更新表,查询表描述信息和删除表。

  • 创建数据表
    • 命令格式
      create -t tableName --pk '[{"c":"primaryKeyName", "t":"primaryKeyType"}, {"c":"primaryKeyName", "t":"primaryKeyType", "opt":"options"}]'--ttl timeToLive --version maxVersion 

      配置项说明请参见下表。

      配置项 示例值 说明
      -t,--table mytable 数据表名称。
      -p,--pk [{"c":"uid","t":"string"}, {"c":"pid","t":"integer"}] 数据表主键列,以JSON格式的数组表示。包含如下字段:
      • c(必选):主键列名称。
      • t(必选):主键列类型,取值范围为string、integer、binary。
      • opt(可选):可选配置,取值范围为none和auto,默认值为none。当取值为auto时,表示该主键列为自增列。

        关于主键自增列的更多信息,请参见主键列自增

      单表最多可设置4个主键,第一个主键默认为分区键。主键的配置及顺序设置后不能修改。

      --ttl 864000 数据表中数据的保存时间。当数据的保存时间超过设置的数据生命周期时,系统会自动清理超过数据生命周期的数据。单位为秒。

      如果不设置此项,则默认值为-1,表示数据永不过期。

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

      --version 1 数据表中的属性列能够保留数据的最大版本个数。当属性列数据的版本个数超过设置的最大版本数时,系统会自动删除较早版本的数据。

      如果不设置此项,则默认值为1,表示只保留最新版本的数据。

      取值必须为非0整数。

      --read_cu 0 为数据表配置预留读吞吐量或预留写吞吐量。默认值均为0,即完全按量计费。单位为CU。

      容量型实例中的数据表的预留读/写吞吐量只能设置为0,不允许预留。

      • 当预留读吞吐量或预留写吞吐量大于0时,表格存储会根据配置为数据表预留相应资源,且数据表创建成功后,将会立即按照预留吞吐量开始计费,超出预留的部分进行按量计费。
      • 当预留读吞吐量或预留写吞吐量设置为0时,表格存储不会为数据表预留相应资源。
      --write_cu 0
      -i,--input /tmp/create_table_meta.json 通过JSON格式的配置文件创建数据表。
      您也可以通过配置文件创建表,命令格式如下:
      • Windows平台
        create -i D:\\localpath\\filename.json
      • Linux和Mac平台
        create -i /localpath/filename.json
      配置文件的示例如下:
      {
          "Name": "mytable",
          "Meta": {
              "Pk": [
                  {
                      "C": "uid",
                      "T": "string",
                      "Opt": "none"
                  },
                  {
                      "C": "pid",
                      "T": "integer",
                      "Opt": "none"
                  }
              ]
          },
          "Option": {
              "TTL": 864000,
              "Version": 3
          },
          "CU": {
              "Read": 0,
              "Write": 0
          },
          "Stream": {
              "Enable": true,
              "Expire": 24
          }
      }
    • 示例

      创建名称为mytable的数据表,该数据表有uid(string类型)和pid(integer类型)两个主键列,表中数据永不过期。

      create -t mytable --pk '[{"c":"uid", "t":"string"}, {"c":"pid", "t":"integer"}]'

      创建名称为mytable的数据表,该数据表有uid(string类型)和pid(integer类型)两个主键列并设置第二主键列pid(integer类型)为自增列,表中数据永不过期。

      create -t mytable --pk '[{"c":"uid", "t":"string"}, {"c":"pid", "t":"integer", "opt":"auto"}]'

      创建名称为mytable的数据表,该数据表有uid(string类型)和pid(integer类型)两个主键列,表中数据在864000秒(即10天)后过期且只保留最新版本。

      create -t mytable --pk '[{"C":"uid","t":"string"}, {"c":"pid","t":"integer"}]' --ttl 864000 --version 1
  • 选择进行数据操作的表
    • 命令格式
      use -t tableName
    • 示例

      使用mytable数据表。

      use -t mytable
  • 列出表名称
    • 命令格式
      ./ts list
    • 示例

      列出实例下所有表的名称。

      ./ts list
  • 更新表
    • 命令格式
      alter -t tableName --ttl timeToLive --version maxVersion --read_cu readCU --write_cu writeCU
    • 示例

      修改mytable数据表的数据生命周期为86400秒(即1天),最大版本数为1,且预留读CU和预留写CU均为0。

      alter -t mytable --ttl 86400 --version 1 --read_cu 0 --write_cu 0
  • 查询表描述信息
    • 命令格式
      desc -t tableName

      配置项说明请参见下表。

      配置项 示例值 说明
      --t,--table mytable 数据表名称。
      -o,--output /tmp/describe_table_meta.json 输出表描述信息到本地指定路径的JSON格式文件中。
    • 示例

      查询mytable表的描述信息。

      desc -t mytable
      查询mytable表的描述信息并将表的描述信息保存到本地文件describe_table_meta.json中。
      desc -t mytable -o  /tmp/describe_table_meta.json
  • 删除表
    • 命令格式
      drop -t tableName -y

      配置项说明请参见下表。

      配置项 示例值 说明
      --t,--table mytable 数据表名称。
      -y,--yes 不涉及 显示确认信息。命令中必须带有此配置项。
    • 示例

      删除mytable表。

      drop -t mytable -y

单行数据操作

通过Tablestore CLI可以进行的单行数据操作,包括插入一行数据,读取一行数据,更新一行数据和删除一行数据。

  • 插入一行数据
    • 命令格式
      put --pk '[primaryKeyValue, primaryKeyValue]' --attr '[{"c":"attributeColumnName", "v":"attributeColumnValue"}, {"c":"attributeColumnName", "v":"attributeColumnValue", "ts":timestamp}]' --condition condition

      配置项说明请参见下表。

      参数 示例值 说明
      -p,--pk ["86", 6771] 数据表主键的值,以数组表示。
      注意
      • 设置的主键个数和类型必须和数据表的主键个数和类型一致。
      • 当主键为自增列时,只需将自增列的值设置为占位符null。
      --attr [{"c":"name", "v":"redchen"}, {"c":"country", "v":"china", "ts":1626860469000}] 数据表属性列,以JSON格式的数组表示。每个属性列包含如下字段:
      • c(必选):属性列名称。
      • v(必选):属性列的值。
      • t(可选):属性列类型,取值范围为integer、string(UTF-8编码字符串)、binary、boolean、double五种。当属性列类型为binary时必须设置此字段不可省略。
      • ts(可选):时间戳即数据的版本号,可以由系统自动生成或者自定义,如果不设置此参数,则默认由系统自动生成。更多信息,请参见数据版本和生命周期
      --condition ignore 使用条件更新,可以设置原行的存在性条件。取值范围如下:
      • ignore(默认):表示无论此行是否存在均会插入新数据,如果之前行已存在,则写入数据时会覆盖原有数据。
      • exist:表示只有此行存在时才会插入新数据,写入数据时会覆盖原有数据。
      • not_exist:表示只有此行不存在时才会插入数据。

      关于条件更新的更多信息,请参见条件更新

      -i, --input /temp/inputdata.json 通过JSON格式的配置文件插入数据。
      您也可以通过配置文件插入数据,命令格式如下:
      • Windows平台
        put -i D:\\localpath\\filename.json
      • Linux和Mac平台
        put -i /localpath/filename.json
      配置文件的示例如下:
      {
          "PK":{
              "Values":[
                  "86",
                  6771
              ]
          },
          "Attr":{
              "Values":[
                  {
                      "C":"age",
                      "V":32,
                      "TS":1626860801604,
                      "IsInt":true
                  }
              ]
          }
      }
    • 示例
      在数据表中插入一行数据。该行的第一主键列值为“86”,第二主键列值为6771,属性列有name(string类型)和country(string类型)两列。
      put --pk '["86", 6771]' --attr '[{"c":"name", "v":"redchen"}, {"c":"country", "v":"china"}]'
      在数据表中插入一行数据,该行的第一主键列值为“86”,第二主键列值为6771,属性列有name(string类型)和country(string类型)两列。无论此行是否存在均会插入新数据,如果之前行已存在,则写入数据时会覆盖原有数据。
      put --pk '["86", 6771]' --attr '[{"c":"name", "v":"redchen"}, {"c":"country", "v":"china"}]'  --condition ignore
      在数据表中插入一行数据,该行的第一主键列值为“86”,第二主键列值为6771,属性列有name(string类型)和country(string类型)两列,并且country列的时间戳为15327798534。
      put --pk '["86", 6771]' --attr '[{"c":"name", "v":"redchen"}, {"c":"country", "v":"china", "ts":15327798534}]'
      当数据表中第二主键列为自增列时,在数据表中插入一行数据。该行的第一主键列值为“86”,第二主键列值为null,属性列有name(string类型)和country(string类型)两列。
      put --pk '["86", null]' --attr '[{"c":"name", "v":"redchen"}, {"c":"country", "v":"china"}]'
  • 读取一行数据
    • 命令格式
      get --pk '[primaryKeyValue,primaryKeyValue]'

      配置项说明请参见下表。

      配置项 示例值 说明
      -p,--pk ["86",6771] 数据表主键的值,以数组表示。
      注意 设置的主键个数和类型必须和数据表的主键个数和类型一致。
      --columns name,uid 读取的列集合,列名可以是主键列或属性列。如果不设置返回的列名,则返回整行数据。
      --max_version 1 最多读取的版本数。
      --time_range_start 1626860469000 读取版本号范围内的数据。time_range_start和time_range_end分别表示起始时间戳和结束时间戳,范围为左闭右开区间。
      --time_range_end 1626865270000
      --time_range_specific 1626862870000 读取特定版本号的数据。
      -o, --output /tmp/querydata.json 输出查询结果到本地指定路径的JSON格式文件中。
    • 示例

      读取第一主键列值为“86”,第二主键列值为6771的行数据。

      get --pk '["86",6771]'
  • 更新一行数据
    • 命令格式
      update --pk '[primaryKeyValue, primaryKeyValue]' --attr '[{"c":"attributeColumnName", "v":"attributeColumnValue"}, {"c":"attributeColumnName", "v":"attributeColumnValue", "ts":timestamp}]' --condition condition
      配置项说明请参见下表。
      参数 示例值 说明
      -p,--pk ["86", 6771] 数据表主键的值,以数组表示。
      注意 设置的主键个数和类型必须和数据表的主键个数和类型一致。
      --attr [{"c":"name", "v":"redchen"}, {"c":"country", "v":"china", "ts":15327798534}] 数据表属性列,以JSON格式的数组表示。每个属性列包含如下字段:
      • c(必选):属性列名称。
      • v(必选):属性列的值。
      • t(可选):属性列类型,取值范围为是integer、string(UTF-8编码字符串)、binary、boolean、double五种。当属性列类型为binary时必须设置此字段不可省略。
      • ts(可选):时间戳即数据的版本号,可以由系统自动生成或者自定义,如果不设置此参数,则默认由系统自动生成。
      --condition ignore 使用条件更新,可以设置原行的存在性条件。取值范围如下:
      • ignore(默认):表示无论此行是否存在均会插入新数据,如果之前行已存在,则写入数据时会覆盖原有数据。
      • exist:表示只有此行存在时才会插入新数据,写入数据时会覆盖原有数据。
      • not_exist:表示只有此行不存在时才会插入数据。

      关于条件更新的更多信息,请参见条件更新

      -i, --input /tmp/inputdata.json 通过JSON格式的配置文件更新数据。
      您也可以通过配置文件更新数据,命令格式如下:
      • Windows平台
        update -i D:\\localpath\\filename.json
      • Linux和Mac平台
        update -i /localpath/filename.json
      配置文件的示例如下:
      {
          "PK":{
              "Values":[
                  "86",
                  6771
              ]
          },
          "Attr":{
              "Values":[
                  {
                      "C":"age",
                      "V":32,
                      "TS":1626860801604,
                      "IsInt":true
                  }
              ]
          }
      }
    • 示例

      更新第一主键列为“86”,第二主键列为6771的行数据。无论此行是否存在均会插入新数据,如果之前行已存在,则写入数据时会覆盖原有数据。

      update --pk '["86", 6771]' --attr '[{"c":"name", "v":"redchen"}, {"c":"country", "v":"china"}]'  --condition ignore
  • 删除一行数据
    • 命令格式
      del --pk '[primaryKeyValue,primaryKeyValue]'
    • 示例

      删除第一主键列值为“86”,第二主键列值为6771的行数据。

      del --pk '["86", 6771]'

简单压测操作

通过Tablestore CLI可以进行的简单压测操作,包括开启压测和检查压测状态。

  • 开启压测
    • 命令格式
      press_input --part partitionKeyValue --count rowCount
      配置项说明请参见下表。
      配置项 示例值 说明
      --begin 0 从指定行序号开始插入数据,默认值为0。
      --part redchen 分区键值,默认值为redchen。
      --count 10 插入的行数,每行数据长度为1 KB。
    • 示例

      对分区键值为redchen的分区插入10行数据,每行数据大小为1 KB。

      press_input --part redchen --count 10
  • 检查压测状态
    • 命令格式
      press_check --part partitionKeyValue --begin begin --count rowCount
      配置项说明请参见下表。
      配置项 示例值 说明
      --begin 0 从指定行序号开始插入数据,默认值为0。
      --part redchen 分区键值,默认值为redchen。
      --count 1000 检查压测状态的行数,每行数据长度为1 KB。
      -y, --yes 不涉及 显示消耗的时间。
    • 示例

      从第一行开始检查1000行数据的压测状态。

      press_check --part redchen --begin 0 --count 1000
简单压测的具体操作如下:
  1. 创建数据表。

    创建名称为mytable的数据表,该数据表的第一主键列为分区键,第二主键列为行序号。

    create -t mytable --pk '[{"c":"uid", "t":"string"}, {"c":"pid", "t":"integer"}]'
  2. 执行use -t mytable命令,使用数据表。
  3. 执行press_input --part redchen --count 10命令,开启压测。
  4. 执行press_check --part redchen --begin 0 --count 1000命令,检查压测状态。

数据备份操作

通过Tablestore CLI可以进行的数据备份操作,包括表数据导出到本地文件和本地文件数据导入到表。

  • 表数据导出本地文件
    • 命令格式
      export -o /localpath/filename.json -c attributeColumnName,attributeColumnName,attributeColumnName

      配置项说明请参见下表。

      配置项 示例值 说明
      -c, --columns uid,name 导出的列集合,列名可以是主键列或属性列。如果不设置列名,则导出整行数据。
      --max_version 1 最多导出的版本数。
      --time_range_start 1626865596000 导出版本号范围内的数据。time_range_start和time_range_end分别表示起始时间戳和结束时间戳,范围为前闭后开区间。
      --time_range_end 1626869196000
      --time_range_specific 1626867396000 导出特定版本号的数据。
      --backward true 导出数据是否按照主键降序排列。取值范围如下:
      • false(默认):按照主键升序排列。
      • true:按照主键降序排列。
      -o, --output /tmp/mydata.json 输出查询结果到本地指定路径的JSON格式文件中。
    • 示例

      导出当前表中全部数据到本地文件mydata.json。

      export -o /tmp/mydata.json

      导出当前表中uid和name列的数据到本地文件mydata.json。

      export -o /tmp/mydata.json -c uid,name
  • 通过本地文件导入数据到当前表
    • 命令格式
      import -i /localpath/filename.json --ignore_ts

      配置项说明请参见下表。

      配置项 示例值 说明
      -i, --input /tmp/inputdata.json 通过JSON格式的本地文件导入数据到当前表。
      --ignore_ts 不涉及 忽略时间戳检查,使用当前时间作为时间戳。
      本地文件的配置示例如下:
      {
       "PK":{
              "Values":[
                  "redchen",
                  0
              ]
          },
          "Attr":{
              "Values":[
                  {
                      "C":"country",
                      "V":"china0"
                  },
                  {
                      "C":"name",
                      "V":"redchen0"
                  }
              ]
          }
      }
      {
          "PK":{
              "Values":[
                  "redchen",
                  1
              ]
          },
          "Attr":{
              "Values":[
                  {
                      "C":"country",
                      "V":"china1"
                  },
                  {
                      "C":"name",
                      "V":"redchen1"
                  }
              ]
          }
      }                              
    • 示例

      导入mydata.json文件的数据到当前表。

      import -i /tmp/mydata.json

      导入mydata.json文件的数据到当前表,且使用当前时间作为时间戳。

      import -i /tmp/mydata.json --ignore_ts