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)

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.

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]: \x3CYOUR_ACCESS_KEY_ID>
# Aliyun Access Key Secret [None]: \x3CYOUR_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

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 \x3Cendpoint> --instance \x3CinstanceName>

Endpoint Format:

• Public: https://\x3Cinstance_name>.\x3Cregion_id>.ots.aliyuncs.com
• VPC: https://\x3Cinstance_name>.\x3Cregion_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 \x3CregionId> -n \x3CinstanceName>

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 \x3CregionId>

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 \x3CtableName>

Example:

aliyun otsutil use -t mytable

Task 5: List Tables (list)

List table names under the current instance.

Command Format:

aliyun otsutil list [options]

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 \x3CtableName>] [-f \x3Cformat>] [-o \x3CoutputPath>]

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:

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

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 \x3Cname>
7. Export Table Schema: Use aliyun otsutil desc -o \x3Cfile> to export and backup table definitions

Reference Links