Tablestore Read-Only Operations

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.

Prerequisites

• Tablestore service must be activated. See Alibaba Cloud Console
• Obtain AccessKey ID and AccessKey Secret from RAM Console

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.

Installation

Install Aliyun CLI (Version 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)

Platform	Download
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.

macOS / Linux Binary Setup

# Download (example for macOS Universal)
curl -L -o aliyun-cli.tgz https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-universal.tgz

# Extract
tar -xzf aliyun-cli.tgz

# Move to PATH
sudo mv aliyun /usr/local/bin/

# Verify installation and version (must be 3.3.0+)
aliyun version

# Verify otsutil is available
aliyun otsutil help

Windows Setup

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)

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.

Parameter	Required	Description	Default
--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.

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

Configure Credentials (Aliyun CLI)

# Interactive configuration (recommended)
aliyun configure

# Follow prompts:
# Aliyun Access Key ID [None]: <YOUR_ACCESS_KEY_ID>
# Aliyun Access Key Secret [None]: <YOUR_ACCESS_KEY_SECRET>
# Default Region Id [None]: cn-hangzhou
# Default output format [json]: json
# Default Language [zh]: en

Configure with Specific Profile

# Create a named profile
aliyun configure --profile tablestore-user

# Use the profile for otsutil commands
aliyun otsutil --profile tablestore-user list_instance -r cn-hangzhou

Supported Authentication Modes

Mode	Description	Configure Command
AK	AccessKey ID/Secret (default)	aliyun configure --mode AK
RamRoleArn	RAM role assumption	aliyun configure --mode RamRoleArn
EcsRamRole	ECS instance role	aliyun configure --mode EcsRamRole
OIDC	OIDC role assumption	aliyun configure --mode OIDC

RAM Policy

Required permissions for Tablestore read-only operations:

{
  "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.

Core Workflow

Part 1: Instance Read Operations

Task 1: Configure Instance (Connect to Instance)

Configure the endpoint to select which instance to operate on.

Important: You must configure the instance before performing any table operations.

Command Format:

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:

aliyun otsutil config --endpoint https://myinstance.cn-hangzhou.ots.aliyuncs.com --instance myinstance

Response:

{
  "Endpoint": "https://myinstance.cn-hangzhou.ots.aliyuncs.com",
  "AccessKeyId": "NTS**********************",
  "AccessKeySecret": "7NR2****************************************",
  "AccessKeySecretToken": "",
  "Instance": "myinstance"
}

Task 2: Describe Instance

View instance details including name, creation time, status, and quota.

Command Format:

aliyun otsutil describe_instance -r <regionId> -n <instanceName>

Example:

aliyun otsutil describe_instance -r cn-hangzhou -n myinstance

Response:

{
  "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.

Task 3: List Instances

Get all instances in a specified region.

Command Format:

aliyun otsutil list_instance -r <regionId>

Example:

aliyun otsutil list_instance -r cn-hangzhou

Response:

["myinstance", "another-instance"]

Note: Returns empty array [] if no instances exist in the region.

---

Part 2: Data Table Read Operations

Prerequisite: You must first configure an instance endpoint using aliyun otsutil config (Task 1) before running table operations.

Task 4: Select Table (use)

Select a data table for subsequent operations.

Command Format:

aliyun otsutil use --wc -t <tableName>

Parameter	Required	Description
--wc	No	Indicates the target is a data table (wide column) or index table
-t, --table	Yes	Table name

Example:

aliyun otsutil use -t mytable

Task 5: List Tables (list)

List table names under the current instance.

Command Format:

aliyun otsutil list [options]

Parameter	Required	Description
-a, --all	No	List all table names (data tables + timeseries tables)
-d, --detail	No	List tables with detailed information
-w, --wc	No	List only data table (wide column) names
-t, --ts	No	List only timeseries table names

Examples:

# List tables of the current type
aliyun otsutil list

# List all tables
aliyun otsutil list -a

# List only data tables
aliyun otsutil list -w

# List only timeseries tables
aliyun otsutil list -t

Task 6: Describe Table (desc)

View detailed table information including primary keys, TTL, max versions, and throughput.

Command Format:

aliyun otsutil desc [-t <tableName>] [-f <format>] [-o <outputPath>]

Parameter	Required	Description
-t, --table	No	Table name. If omitted, describes the currently selected table (via use)
-f, --print_format	No	Output format: json (default) or table
-o, --output	No	Save output to a local JSON file

Examples:

# Describe the currently selected table
aliyun otsutil desc

# Describe a specific table
aliyun otsutil desc -t mytable

# Output in table format
aliyun otsutil desc -t mytable -f table

# Save table info to file
aliyun otsutil desc -t mytable -o /tmp/table_meta.json

Example Response:

{
  "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:

Field	Description
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

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

Related APIs

CLI Command	Description
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.

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

Reference Links

Reference	Description
cli-installation-guide.md	Aliyun CLI installation guide
related-apis.md	Complete CLI command reference
verification-method.md	Verification steps for each operation
ram-policies.md	RAM permission requirements
Aliyun CLI GitHub	Aliyun CLI source code and documentation
Instance Operations Doc	Instance operations reference
Data Table Operations Doc	Data table operations reference