Tablestore CLI 数据表行级读写与导入导出操作 - 表格存储

前提条件

已完成命令行工具的安装和访问凭证配置。具体操作，请参见命令行工具。
已创建数据表。具体操作，请参见数据表操作。

执行数据操作前，请先通过以下命令选定目标数据表。

use -t <tableName>

插入数据

在数据表中插入一行数据。

put --pk '<pk_values>' --attr '<attr_json>'

参数	必填	说明
-k，--pk	是	数据表主键的值，以 JSON 数组表示。重要设置的主键个数和类型必须和数据表的主键个数和类型一致。当主键为自增列时，将自增列的值设置为占位符 null。
-a，--attr	是	属性列，以 JSON 数组表示。每个属性列包含如下字段： c（必选）：属性列名称。 v（必选）：属性列的值。 t（可选）：属性列类型，取值为 integer、string（UTF-8 编码字符串）、binary、boolean、double。当属性列类型为 binary 时必须设置此字段。 ts（可选）：时间戳，即数据的版本号。如果不设置此参数，则默认由系统自动生成。
--condition	否	行存在性条件，支持条件更新。取值： ignore（默认）：无论此行是否存在均会插入新数据，已存在的行会被覆盖。 exist：只有此行存在时才插入新数据，覆盖原有数据。 not_exist：只有此行不存在时才插入数据。
-i，--input	否	通过 JSON 格式的配置文件插入数据。使用配置文件时，无需指定 --pk 和 --attr。

通过配置文件插入数据的命令格式：

Windows

put -i D:\\localpath\\filename.json

Linux 和 macOS

put -i /localpath/filename.json

配置文件示例：

{
    "PK":{
        "Values":["86", 6771]
    },
    "Attr":{
        "Values":[
            {"C":"age", "V":32, "TS":1626860801604, "IsInt":true}
        ]
    }
}

示例

插入一行数据，第一主键列值为 "86"，第二主键列值为 6771，属性列有 name 和 country 两列。
```
put --pk '["86", 6771]' --attr '[{"c":"name", "v":"redchen"}, {"c":"country", "v":"china"}]'
```

在行不存在时插入数据。

put --pk '["86", 6771]' --attr '[{"c":"name", "v":"redchen"}, {"c":"country", "v":"china"}]' --condition not_exist

读取数据

根据主键读取一行数据。

说明

如果读取的数据行不存在，则返回结果为空。

get --pk '<pk_values>'

参数	必填	说明
-k，--pk	是	数据表主键的值，以 JSON 数组表示。设置的主键个数和类型必须和数据表的主键个数和类型一致。
-c，--columns	否	读取的列集合，列名可以是主键列或属性列，多列以逗号分隔。不设置则返回整行数据。
--max_version	否	最多读取的版本数。
--time_range_start	否	读取版本号范围内的数据。time_range_start 和 time_range_end 分别表示起始时间戳和结束时间戳，范围为左闭右开区间。
--time_range_end	否
--time_range_specific	否	读取特定版本号的数据。
-o，--output	否	输出查询结果到本地文件中。

示例

读取第一主键列值为 "86"、第二主键列值为 6771 的行数据。

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

更新数据

更新数据表中一行数据的属性列。

update --pk '<pk_values>' --attr '<attr_json>'

参数	必填	说明
-k，--pk	是	数据表主键的值，以 JSON 数组表示。设置的主键个数和类型必须和数据表的主键个数和类型一致。
--attr	是	属性列，以 JSON 数组表示。每个属性列包含如下字段： c（必选）：属性列名称。 v（必选）：属性列的值。 t（可选）：属性列类型，取值为 integer、string（UTF-8 编码字符串）、binary、boolean、double。当属性列类型为 binary 时必须设置此字段。 ts（可选）：时间戳，即数据的版本号。如果不设置此参数，则默认由系统自动生成。
--delete	否	指定要删除的属性列名称，需与`--attr '[]'`配合使用，表示仅删除指定属性列，不更新其他属性列。删除属性列时，--delete 与 --attr 均为必填项。
--condition	否	行存在性条件，支持条件更新。取值： ignore（默认）：无论此行是否存在均会更新数据。 exist：只有此行存在时才更新数据。 not_exist：只有此行不存在时才插入数据。
-i，--input	否	通过 JSON 格式的配置文件更新数据。使用配置文件时，无需指定 --pk 和 --attr。

通过配置文件更新数据的命令格式：

Windows

update -i D:\\localpath\\filename.json

Linux 和 macOS

update -i /localpath/filename.json

配置文件格式与插入数据一致。

示例

更新第一主键列值为 "86"、第二主键列值为 6771 的行数据。

update --pk '["86", 6771]' --attr '[{"c":"name", "v":"redchen"}, {"c":"country", "v":"china"}]' --condition ignore

删除主键值为 "abc" 的行中 aaa 属性列。
```
update --pk '["abc"]' --delete aaa --attr '[]'
```

删除数据

根据主键删除一行数据。

delete --pk '<pk_values>'

参数	必填	说明
-k，--pk	是	数据表主键的值，以 JSON 数组表示。设置的主键个数和类型必须和数据表的主键个数和类型一致。

示例

删除第一主键列值为 "86"、第二主键列值为 6771 的行数据。

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

扫描数据

扫描获取数据表中所有数据或指定行数的数据。

scan --limit <n>

参数	必填	说明
--limit	否	本次扫描返回的最大行数。不设置则扫描整表所有数据。

示例

扫描获取数据表中最多 10 行数据。

scan --limit 10

导出数据

导出数据表中的数据到本地 JSON 文件。

scan -o /localpath/filename.json

参数	必填	说明
-o，--output	是	导出数据到指定的本地文件路径。
-c，--columns	否	导出的列集合，列名可以是主键列或属性列，多列以逗号分隔。不设置则导出整行数据。
--max_version	否	最多导出的版本数。
--time_range_start	否	导出版本号范围内的数据。time_range_start 和 time_range_end 分别表示起始时间戳和结束时间戳，范围为左闭右开区间。
--time_range_end	否
--time_range_specific	否	导出特定版本号的数据。
--backward	否	导出数据按照主键降序排列。
-l，--limit	否	本次导出最多返回的行数。
-b，--begin	否	导出范围的起始点和结束点，主键范围为左闭右开区间。说明 --begin 值为 [null,null] 时，表示起始点为 [INF_MIN,INF_MIN]，即各主键列从最小值开始。 --end 值为 [null,null] 时，表示结束点为 [INF_MAX,INF_MAX]，即各主键列到最大值结束。
-e，--end	否

示例

导出当前表中全部数据到本地文件 mydata.json。
```
scan -o /tmp/mydata.json
```
导出 uid 和 name 列的数据。
```
scan -o /tmp/mydata.json -c uid,name
```

导出指定主键范围内的数据。

scan -o /tmp/mydata.json -b '["86", 6771]' -e '["86", 6775]'

导入数据

导入本地 JSON 文件中的数据到数据表中。

重要

如果本地 JSON 文件所在路径中存在汉字，则导入数据时会出错。

import -i /localpath/filename.json

参数	必填	说明
-a，--action	否	导入数据的模式。取值： put（默认）：如果某行数据已存在，则先删除原行数据（原行所有列及所有版本的数据），再写入新行数据。 update：如果该行已存在，可新增或删除属性列、删除属性列指定版本的数据，或更新已有属性列的值。如果该行不存在，则新增一行数据。
-i，--input	是	JSON 格式的本地数据文件路径。重要主键个数和类型必须和数据表的主键个数和类型一致。当主键为自增列时，需将自增列的值设置为占位符 null。
--ignore_version	否	忽略时间戳检查，使用当前时间作为时间戳。

数据文件格式（每行一条 JSON 记录）：

{"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
```
导入数据并使用当前时间作为时间戳。
```
import -i /tmp/mydata.json --ignore_version
```