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

bash

# 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)

bash

# 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

bash

# 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:

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.

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:

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"
}

Task 2: Describe Instance

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:

= Running. Other values indicate abnormal status.

Task 3: List Instances

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.

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:

bash

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:

bash

aliyun otsutil use -t mytable

Task 5: List Tables (

list

)

List table names under the current instance.

Command Format:

bash

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:

bash

# 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:

bash

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:

bash

# 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:

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:

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

NPX Install

Tags

SKILL.md Content

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

alibabacloud-tablestore-ops

NPX Install

Tags

SKILL.md Content

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`
)