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

Download the zip file from the download link above
Extract the zip file to get aliyun.exe
Add the directory to your PATH environment variable
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:

Obtain AccessKey from Alibaba Cloud Console

For security, use RAM user credentials with AliyunOTSReadOnlyAccess permission

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:

After aliyun otsutil config: Response should show correct Endpoint and Instance
After aliyun otsutil list_instance: Verify expected instance names appear in the list
After aliyun otsutil describe_instance: Verify Status=1 (Running)
After aliyun otsutil list: Verify expected table names appear
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

Use RAM Users: Create RAM users with read-only permissions instead of using root account credentials
Use ReadOnly Policy: Apply AliyunOTSReadOnlyAccess for query-only workflows
Region Selection: Choose the region closest to your application for lower latency
Network Type: Use VPC endpoint for better security in production environments
Credential Security: Use aliyun configure for credential management; never hardcode credentials
Use Profiles: Create dedicated profiles for different environments using aliyun configure --profile <name>
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 |

Alibabacloud Tablestore Ops

Tablestore Read-Only Operations

Prerequisites

Installation

Install Aliyun CLI (Version 3.3.0+)

macOS / Linux Binary Setup

Windows Setup

Parameter Confirmation

Authentication

Configure Credentials (Aliyun CLI)

Configure with Specific Profile

Supported Authentication Modes

RAM Policy

Core Workflow

Part 1: Instance Read Operations

Task 1: Configure Instance (Connect to Instance)

Task 2: Describe Instance

Task 3: List Instances

Part 2: Data Table Read Operations

Task 4: Select Table (use)

Task 5: List Tables (list)

Task 6: Describe Table (desc)

Success Verification

Related APIs

Best Practices

Reference Links

Task 4: Select Table (`use`)

Task 5: List Tables (`list`)

Task 6: Describe Table (`desc`)