Back to Details

alibabacloud-tablestore-ops

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Tablestore Read-Only Operations

Tablestore 只读操作

This skill provides CLI-based read-only operations for querying Alibaba Cloud Tablestore (OTS) instances and data tables. Tablestore is a fully managed NoSQL database service that supports storing and accessing large amounts of structured data.
Architecture: 
Aliyun CLI (otsutil) → Tablestore Instance → Data Tables (Wide Table / TimeSeries)
Scope: This skill only covers read/query operations. No create, update, or delete operations are included.
本Skill提供基于CLI的只读操作能力，用于查询阿里云Tablestore（OTS）实例和数据表。Tablestore是一款全托管NoSQL数据库服务，支持存储和访问海量结构化数据。
架构： 
Aliyun CLI (otsutil) → Tablestore Instance → Data Tables (Wide Table / TimeSeries)
适用范围： 本Skill仅覆盖读取/查询操作，不包含任何创建、更新或删除操作。

Prerequisites

前提条件

Pre-check: Aliyun CLI Required (Version 3.3.0+)
Tablestore operations are performed via 
aliyun otsutil
command, which is part of the Aliyun CLI. IMPORTANT: The 
otsutil
subcommand is only available in Aliyun CLI version 3.3.0 or later. The Homebrew version may be outdated - download directly from the official CDN. See references/cli-installation-guide.md for installation instructions.
前置检查：必须安装Aliyun CLI（3.3.0及以上版本）
Tablestore操作通过
aliyun otsutil
命令执行，该命令是Aliyun CLI的组成部分。 重要提示： 
otsutil
子命令仅在Aliyun CLI 3.3.0及以上版本中可用。 Homebrew渠道的版本可能过时，建议直接从官方CDN下载。 安装说明可参考references/cli-installation-guide.md

Installation

安装

Install Aliyun CLI (Version 3.3.0+)

安装Aliyun CLI（3.3.0及以上版本）

WARNING: The Homebrew version (
brew install aliyun-cli
) may not include 
otsutil
. Always download from the official CDN to ensure you get version 3.3.0+ with otsutil support.
Option 1: Download Binary (Recommended)
PlatformDownload
Mac (Universal)Mac Universal
Linux (AMD64)Linux AMD64
Linux (ARM64)Linux ARM64
Windows (64-bit)Windows
Option 2: Mac GUI Installer
Download Mac PKG and double-click to install.
警告： 通过Homebrew安装的版本（
brew install aliyun-cli
）可能不包含
otsutil
。 请始终从官方CDN下载，确保获得支持otsutil的3.3.0及以上版本。
方案1：下载二进制文件（推荐）
平台下载地址
Mac (通用版)Mac Universal
Linux (AMD64)Linux AMD64
Linux (ARM64)Linux ARM64
Windows (64位)Windows
方案2：Mac GUI安装程序
下载Mac PKG安装包，双击完成安装。

macOS / Linux Binary Setup

macOS / Linux 二进制文件配置

bash
undefined
bash
undefined

Download (example for macOS Universal)

下载（以macOS通用版为例）

curl -L -o aliyun-cli.tgz https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-universal.tgz
curl -L -o aliyun-cli.tgz https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-universal.tgz

Extract

解压

tar -xzf aliyun-cli.tgz
tar -xzf aliyun-cli.tgz

Move to PATH

移动到PATH目录

sudo mv aliyun /usr/local/bin/
sudo mv aliyun /usr/local/bin/

Verify installation and version (must be 3.3.0+)

验证安装和版本（必须为3.3.0及以上）

aliyun version
aliyun version

Verify otsutil is available

验证otsutil可用

aliyun otsutil help
undefined
aliyun otsutil help
undefined

Windows Setup

Windows 配置

  1. Download the zip file from the download link above
  2. Extract the zip file to get 
    aliyun.exe
  3. Add the directory to your PATH environment variable
  4. Verify: 
    aliyun version
    (must show 3.3.0 or later)
  1. 从上方下载链接获取zip压缩包
  2. 解压得到
    aliyun.exe
    文件
  3. 将文件所在目录添加到PATH环境变量
  4. 验证：
    aliyun version
    （必须显示3.3.0或更高版本）

Parameter Confirmation

参数确认

IMPORTANT: Parameter Confirmation — Before executing any command, ALL user-customizable parameters (e.g., RegionId, instance names, AccessKey, endpoint, etc.) MUST be confirmed with the user. Do NOT assume or use default values without explicit user approval.
ParameterRequiredDescriptionDefault
--endpoint
Yes (for table ops)Instance endpoint URL-
--instance
Yes (for table ops)Instance name-
-n
(instanceName)		Yes (for describe_instance)Instance name-
-r
(regionId)		Yes (for instance ops)Region ID (e.g., cn-hangzhou)-
-t
(tableName)		Yes (for table ops)Data table name-
Note: AccessKey credentials are configured via 
aliyun configure
, not passed as command parameters.
重要提示：参数确认 — 执行任何命令前，所有用户可自定义参数（例如RegionId、实例名、AccessKey、endpoint等）必须与用户确认。未经用户明确许可，不得假设或使用默认值。
参数必填说明默认值
--endpoint
是（表操作必填）实例endpoint URL-
--instance
是（表操作必填）实例名称-
-n
(instanceName)		是（查询实例详情必填）实例名称-
-r
(regionId)		是（实例操作必填）区域ID（例如cn-hangzhou）-
-t
(tableName)		是（表操作必填）数据表名称-
注意： AccessKey凭证通过
aliyun configure
配置，不作为命令参数传递。

Authentication

身份认证

Pre-check: Alibaba Cloud Credentials Required
Security Rules:
  • NEVER echo or print AccessKey values
  • NEVER ask the user to input AccessKey directly in plain text
  • ONLY configure credentials using 
    aliyun configure
If no valid credentials exist:
  1. Obtain AccessKey from Alibaba Cloud Console
  2. For security, use RAM user credentials with 
    AliyunOTSReadOnlyAccess
    permission
  3. Configure credentials using Aliyun CLI
前置检查：必须提供阿里云凭证
安全规则：
  • 禁止回显或打印AccessKey值
  • 禁止要求用户直接输入明文AccessKey
  • 仅可通过
    aliyun configure
    配置凭证
如果不存在有效凭证：
  1. 从阿里云控制台获取AccessKey
  2. 出于安全考虑，使用拥有
    AliyunOTSReadOnlyAccess
    权限的RAM用户凭证
  3. 通过Aliyun CLI配置凭证

Configure Credentials (Aliyun CLI)

配置凭证（Aliyun CLI）

bash
undefined
bash
undefined

Interactive configuration (recommended)

交互式配置（推荐）

aliyun configure
aliyun configure

Follow prompts:

按照提示输入：

Aliyun Access Key ID [None]: <YOUR_ACCESS_KEY_ID>

Aliyun Access Key ID [None]: <YOUR_ACCESS_KEY_ID>

Aliyun Access Key Secret [None]: <YOUR_ACCESS_KEY_SECRET>

Aliyun Access Key Secret [None]: <YOUR_ACCESS_KEY_SECRET>

Default Region Id [None]: cn-hangzhou

Default Region Id [None]: cn-hangzhou

Default output format [json]: json

Default output format [json]: json

Default Language [zh]: en

Default Language [zh]: en

undefined
undefined

Configure with Specific Profile

使用指定配置文件

bash
undefined
bash
undefined

Create a named profile

创建命名配置文件

aliyun configure --profile tablestore-user
aliyun configure --profile tablestore-user

Use the profile for otsutil commands

执行otsutil命令时使用该配置文件

aliyun otsutil --profile tablestore-user list_instance -r cn-hangzhou
undefined
aliyun otsutil --profile tablestore-user list_instance -r cn-hangzhou
undefined

Supported Authentication Modes

支持的认证模式

ModeDescriptionConfigure Command
AKAccessKey ID/Secret (default)
aliyun configure --mode AK
RamRoleArnRAM role assumption
aliyun configure --mode RamRoleArn
EcsRamRoleECS instance role
aliyun configure --mode EcsRamRole
OIDCOIDC role assumption
aliyun configure --mode OIDC
模式说明配置命令
AKAccessKey ID/Secret（默认）
aliyun configure --mode AK
RamRoleArnRAM角色扮演
aliyun configure --mode RamRoleArn
EcsRamRoleECS实例角色
aliyun configure --mode EcsRamRole
OIDCOIDC角色扮演
aliyun configure --mode OIDC

RAM Policy

RAM权限策略

Required permissions for Tablestore read-only operations:
json
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ots:GetInstance",
        "ots:ListInstance",
        "ots:ListTable",
        "ots:DescribeTable"
      ],
      "Resource": "acs:ots:*:*:instance/*"
    }
  ]
}
Or use the managed policy: 
AliyunOTSReadOnlyAccess
See references/ram-policies.md for detailed permissions.
Tablestore只读操作所需权限：
json
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ots:GetInstance",
        "ots:ListInstance",
        "ots:ListTable",
        "ots:DescribeTable"
      ],
      "Resource": "acs:ots:*:*:instance/*"
    }
  ]
}
也可直接使用托管策略：
AliyunOTSReadOnlyAccess
详细权限说明可参考references/ram-policies.md

Core Workflow

核心工作流

Part 1: Instance Read Operations

第一部分：实例读取操作

Task 1: Configure Instance (Connect to Instance)

任务1：配置实例（连接到实例）

Configure the endpoint to select which instance to operate on.
Important: You must configure the instance before performing any table operations.
Command Format:
bash
aliyun otsutil config --endpoint <endpoint> --instance <instanceName>
Endpoint Format:
  • Public: 
    https://<instance_name>.<region_id>.ots.aliyuncs.com
  • VPC: 
    https://<instance_name>.<region_id>.vpc.tablestore.aliyuncs.com
Example:
bash
aliyun otsutil config --endpoint https://myinstance.cn-hangzhou.ots.aliyuncs.com --instance myinstance
Response:
json
{
  "Endpoint": "https://myinstance.cn-hangzhou.ots.aliyuncs.com",
  "AccessKeyId": "NTS**********************",
  "AccessKeySecret": "7NR2****************************************",
  "AccessKeySecretToken": "",
  "Instance": "myinstance"
}
配置endpoint以选择要操作的实例。
重要提示： 执行任何表操作前必须先配置实例。
命令格式：
bash
aliyun otsutil config --endpoint <endpoint> --instance <instanceName>
Endpoint格式：
  • 公网：
    https://<instance_name>.<region_id>.ots.aliyuncs.com
  • VPC：
    https://<instance_name>.<region_id>.vpc.tablestore.aliyuncs.com
示例：
bash
aliyun otsutil config --endpoint https://myinstance.cn-hangzhou.ots.aliyuncs.com --instance myinstance
返回结果：
json
{
  "Endpoint": "https://myinstance.cn-hangzhou.ots.aliyuncs.com",
  "AccessKeyId": "NTS**********************",
  "AccessKeySecret": "7NR2****************************************",
  "AccessKeySecretToken": "",
  "Instance": "myinstance"
}

Task 2: Describe Instance

任务2：查询实例详情

View instance details including name, creation time, status, and quota.
Command Format:
bash
aliyun otsutil describe_instance -r <regionId> -n <instanceName>
Example:
bash
aliyun otsutil describe_instance -r cn-hangzhou -n myinstance
Response:
json
{
  "ClusterType": "ssd",
  "CreateTime": "2024-07-18 09:15:10",
  "Description": "First instance created by CLI.",
  "InstanceName": "myinstance",
  "Network": "NORMAL",
  "Quota": { "EntityQuota": 64 },
  "ReadCapacity": 5000,
  "Status": 1,
  "TagInfos": {},
  "UserId": "1379************",
  "WriteCapacity": 5000
}
Status Values: 
1
= Running. Other values indicate abnormal status.
查看实例详情，包括名称、创建时间、状态、配额等信息。
命令格式：
bash
aliyun otsutil describe_instance -r <regionId> -n <instanceName>
示例：
bash
aliyun otsutil describe_instance -r cn-hangzhou -n myinstance
返回结果：
json
{
  "ClusterType": "ssd",
  "CreateTime": "2024-07-18 09:15:10",
  "Description": "First instance created by CLI.",
  "InstanceName": "myinstance",
  "Network": "NORMAL",
  "Quota": { "EntityQuota": 64 },
  "ReadCapacity": 5000,
  "Status": 1,
  "TagInfos": {},
  "UserId": "1379************",
  "WriteCapacity": 5000
}
状态值说明： 
1
= 运行中，其他值表示状态异常。

Task 3: List Instances

任务3：列出实例列表

Get all instances in a specified region.
Command Format:
bash
aliyun otsutil list_instance -r <regionId>
Example:
bash
aliyun otsutil list_instance -r cn-hangzhou
Response:
json
["myinstance", "another-instance"]
Note: Returns empty array 
[]
if no instances exist in the region.
获取指定区域下的所有实例。
命令格式：
bash
aliyun otsutil list_instance -r <regionId>
示例：
bash
aliyun otsutil list_instance -r cn-hangzhou
返回结果：
json
["myinstance", "another-instance"]
注意： 如果该区域下没有实例，将返回空数组
[]
。

Part 2: Data Table Read Operations

第二部分：数据表读取操作

Prerequisite: You must first configure an instance endpoint using 
aliyun otsutil config
(Task 1) before running table operations.
前置条件： 执行表操作前，必须先通过
aliyun otsutil config
（任务1）配置实例endpoint。

Task 4: Select Table (
use
)

任务4：选择数据表（
use
）

Select a data table for subsequent operations.
Command Format:
bash
aliyun otsutil use --wc -t <tableName>
ParameterRequiredDescription
--wc
NoIndicates the target is a data table (wide column) or index table
-t, --table
YesTable name
Example:
bash
aliyun otsutil use -t mytable
选择要执行后续操作的数据表。
命令格式：
bash
aliyun otsutil use --wc -t <tableName>
参数必填说明
--wc
否表示目标为数据表（宽列）或索引表
-t, --table
是表名称
示例：
bash
aliyun otsutil use -t mytable

Task 5: List Tables (
list
)

任务5：列出数据表（
list
）

List table names under the current instance.
Command Format:
bash
aliyun otsutil list [options]
ParameterRequiredDescription
-a, --all
NoList all table names (data tables + timeseries tables)
-d, --detail
NoList tables with detailed information
-w, --wc
NoList only data table (wide column) names
-t, --ts
NoList only timeseries table names
Examples:
bash
undefined
列出当前实例下的表名称。
命令格式：
bash
aliyun otsutil list [options]
参数必填说明
-a, --all
否列出所有表名称（数据表 + 时序表）
-d, --detail
否列出表的详细信息
-w, --wc
否仅列出数据表（宽列）名称
-t, --ts
否仅列出时序表名称
示例：
bash
undefined

List tables of the current type

列出当前类型的表

aliyun otsutil list
aliyun otsutil list

List all tables

列出所有表

aliyun otsutil list -a
aliyun otsutil list -a

List only data tables

仅列出数据表

aliyun otsutil list -w
aliyun otsutil list -w

List only timeseries tables

仅列出时序表

aliyun otsutil list -t
undefined
aliyun otsutil list -t
undefined

Task 6: Describe Table (
desc
)

任务6：查询表详情（
desc
）

View detailed table information including primary keys, TTL, max versions, and throughput.
Command Format:
bash
aliyun otsutil desc [-t <tableName>] [-f <format>] [-o <outputPath>]
ParameterRequiredDescription
-t, --table
NoTable name. If omitted, describes the currently selected table (via 
use
)
-f, --print_format
NoOutput format: 
json
(default) or 
table
-o, --output
NoSave output to a local JSON file
Examples:
bash
undefined
查看表的详细信息，包括主键、TTL、最大版本数、吞吐量等。
命令格式：
bash
aliyun otsutil desc [-t <tableName>] [-f <format>] [-o <outputPath>]
参数必填说明
-t, --table
否表名称。如果省略，将查询当前选中的表（通过
use
命令选择）
-f, --print_format
否输出格式：
json
（默认）或
table
-o, --output
否将输出保存到本地JSON文件
示例：
bash
undefined

Describe the currently selected table

查询当前选中的表详情

aliyun otsutil desc
aliyun otsutil desc

Describe a specific table

查询指定表的详情

aliyun otsutil desc -t mytable
aliyun otsutil desc -t mytable

Output in table format

以表格格式输出

aliyun otsutil desc -t mytable -f table
aliyun otsutil desc -t mytable -f table

Save table info to file

将表信息保存到文件

aliyun otsutil desc -t mytable -o /tmp/table_meta.json

**Example Response:**
```json
{
  "Name": "mytable",
  "Meta": {
    "Pk": [
      { "C": "uid", "T": "string", "Opt": "none" },
      { "C": "pid", "T": "integer", "Opt": "none" }
    ]
  },
  "Option": {
    "TTL": -1,
    "Version": 1
  },
  "CU": {
    "Read": 0,
    "Write": 0
  }
}
Response Fields:
FieldDescription
Name
Table name
Meta.Pk
Primary key columns: 
C
=name, 
T
=type (
string
/
integer
/
binary
), 
Opt
=option (
none
/
auto
)
Option.TTL
Data time-to-live in seconds (
-1
= never expire)
Option.Version
Max attribute column versions retained
CU.Read
/ 
CU.Write
Reserved read/write capacity units
aliyun otsutil desc -t mytable -o /tmp/table_meta.json

**返回示例：**
```json
{
  "Name": "mytable",
  "Meta": {
    "Pk": [
      { "C": "uid", "T": "string", "Opt": "none" },
      { "C": "pid", "T": "integer", "Opt": "none" }
    ]
  },
  "Option": {
    "TTL": -1,
    "Version": 1
  },
  "CU": {
    "Read": 0,
    "Write": 0
  }
}
返回字段说明：
字段说明
Name
表名称
Meta.Pk
主键列：
C
=列名, 
T
=类型（
string
/
integer
/
binary
）, 
Opt
=配置（
none
/
auto
）
Option.TTL
数据生命周期，单位为秒（
-1
表示永不过期）
Option.Version
保留的属性列最大版本数
CU.Read
/ 
CU.Write
预留读/写容量单元

Success Verification

成功验证

See references/verification-method.md for detailed verification steps.
Quick Verification:
  1. After 
    aliyun otsutil config
    : Response should show correct Endpoint and Instance
  2. After 
    aliyun otsutil list_instance
    : Verify expected instance names appear in the list
  3. After 
    aliyun otsutil describe_instance
    : Verify Status=1 (Running)
  4. After 
    aliyun otsutil list
    : Verify expected table names appear
  5. After 
    aliyun otsutil desc
    : Verify table schema and configuration are correct
详细验证步骤可参考references/verification-method.md
快速验证：
  1. 执行
    aliyun otsutil config
    后：返回结果应显示正确的Endpoint和Instance
  2. 执行
    aliyun otsutil list_instance
    后：验证预期的实例名称出现在列表中
  3. 执行
    aliyun otsutil describe_instance
    后：验证Status=1（运行中）
  4. 执行
    aliyun otsutil list
    后：验证预期的表名称出现在列表中
  5. 执行
    aliyun otsutil desc
    后：验证表结构和配置正确

Related APIs

相关API

CLI CommandDescription
aliyun otsutil config
Configure CLI access (endpoint, instance)
aliyun otsutil describe_instance
Get instance details
aliyun otsutil list_instance
List all instances in a region
aliyun otsutil use
Select a data table for subsequent operations
aliyun otsutil list
List tables under the current instance
aliyun otsutil desc
View detailed table information
See references/related-apis.md for complete API reference.
CLI命令说明
aliyun otsutil config
配置CLI访问信息（endpoint、实例）
aliyun otsutil describe_instance
获取实例详情
aliyun otsutil list_instance
列出某个区域下的所有实例
aliyun otsutil use
选择要执行后续操作的数据表
aliyun otsutil list
列出当前实例下的表
aliyun otsutil desc
查看表的详细信息
完整API参考可查看references/related-apis.md

Best Practices

最佳实践

  1. Use RAM Users: Create RAM users with read-only permissions instead of using root account credentials
  2. Use ReadOnly Policy: Apply 
    AliyunOTSReadOnlyAccess
    for query-only workflows
  3. Region Selection: Choose the region closest to your application for lower latency
  4. Network Type: Use VPC endpoint for better security in production environments
  5. Credential Security: Use 
    aliyun configure
    for credential management; never hardcode credentials
  6. Use Profiles: Create dedicated profiles for different environments using 
    aliyun configure --profile <name>
  7. Export Table Schema: Use 
    aliyun otsutil desc -o <file>
    to export and backup table definitions
  1. 使用RAM用户： 创建拥有只读权限的RAM用户，避免使用根账号凭证
  2. 使用只读策略： 针对仅查询的工作流，应用
    AliyunOTSReadOnlyAccess
    策略
  3. 区域选择： 选择离应用最近的区域，降低延迟
  4. 网络类型： 生产环境使用VPC endpoint，安全性更高
  5. 凭证安全： 使用
    aliyun configure
    管理凭证，永远不要硬编码凭证
  6. 使用配置文件： 通过
    aliyun configure --profile <name>
    为不同环境创建专用配置文件
  7. 导出表结构： 使用
    aliyun otsutil desc -o <file>
    导出并备份表定义

Reference Links

参考链接

ReferenceDescription
cli-installation-guide.mdAliyun CLI installation guide
related-apis.mdComplete CLI command reference
verification-method.mdVerification steps for each operation
ram-policies.mdRAM permission requirements
Aliyun CLI GitHubAliyun CLI source code and documentation
Instance Operations DocInstance operations reference
Data Table Operations DocData table operations reference
参考文档说明
cli-installation-guide.mdAliyun CLI安装指南
related-apis.md完整CLI命令参考
verification-method.md各操作的验证步骤
ram-policies.mdRAM权限要求
Aliyun CLI GitHubAliyun CLI源码和文档
实例操作文档实例操作参考
数据表操作文档数据表操作参考