# oss-structured_storage

Part of **OSS**

# Object Storage Service Structured Storage CLI Reference

## Command Overview

| Command | Purpose | Syntax |
|--------|---------|--------|
| create-table-bucket | Create a new table bucket | `ossutil tables-api create-table-bucket [flags]` |
| list-table-buckets | List all table buckets owned by the user | `ossutil tables-api list-table-buckets [flags]` |
| get-table-bucket | Retrieve details of a specific table bucket | `ossutil tables-api get-table-bucket [flags]` |
| delete-table-bucket | Delete an empty table bucket | `ossutil tables-api delete-table-bucket [flags]` |
| put-table-bucket-encryption | Set server-side encryption for a table bucket | `ossutil tables-api put-table-bucket-encryption [flags]` |
| get-table-bucket-encryption | Get encryption configuration of a table bucket | `ossutil tables-api get-table-bucket-encryption [flags]` |
| delete-table-bucket-encryption | Remove encryption from a table bucket | `ossutil tables-api delete-table-bucket-encryption [flags]` |
| put-table-bucket-policy | Set resource policy for a table bucket | `ossutil tables-api put-table-bucket-policy [flags]` |
| get-table-bucket-policy | Retrieve resource policy of a table bucket | `ossutil tables-api get-table-bucket-policy [flags]` |
| put-table-bucket-maintenance-configuration | Configure maintenance settings (e.g., Unreferenced File Cleanup) | `ossutil tables-api put-table-bucket-maintenance-configuration [flags]` |
| get-table-bucket-maintenance-configuration | Get maintenance configuration of a table bucket | `ossutil tables-api get-table-bucket-maintenance-configuration [flags]` |
| create-table | Create an Iceberg table in a namespace | `ossutil tables-api create-table [flags]` |
| list-tables | List tables in a namespace | `ossutil tables-api list-tables [flags]` |
| get-table | Describe a table’s schema and metadata | `ossutil tables-api get-table [flags]` |
| delete-table | Delete a table from a namespace | `ossutil tables-api delete-table [flags]` |
| rename-table | Rename or move a table between namespaces | `ossutil tables-api rename-table [flags]` |
| put-table-policy | Set resource policy for a table | `ossutil tables-api put-table-policy [flags]` |
| get-table-policy | Retrieve table-level resource policy | `ossutil tables-api get-table-policy [flags]` |
| put-table-encryption | Set server-side encryption for a table | `ossutil tables-api put-table-encryption [flags]` |
| get-table-encryption | Get table encryption configuration | `ossutil tables-api get-table-encryption [flags]` |
| put-table-maintenance-configuration | Configure Iceberg maintenance (compaction, snapshot) | `ossutil tables-api put-table-maintenance-configuration [flags]` |
| get-table-maintenance-configuration | Get table maintenance settings | `ossutil tables-api get-table-maintenance-configuration [flags]` |
| get-table-maintenance-job-status | Check status of automated maintenance jobs | `ossutil tables-api get-table-maintenance-job-status [flags]` |
| get-table-metadata-location | Retrieve metadata file path and version token | `ossutil tables-api get-table-metadata-location [flags]` |
| update-table-metadata-location | Update table metadata location after commit | `ossutil tables-api update-table-metadata-location [flags]` |

## Command Details

### create-table-bucket

**Purpose**: Create a new globally unique table bucket for structured data storage.

**Syntax**:
```bash
ossutil tables-api create-table-bucket --name <name> [--encryption-configuration <json-or-file>] [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --name | — | string | Yes | The name of the Table Bucket. Must be 3–63 characters, lowercase letters, numbers, and hyphens only; must start and end with a letter or number; globally unique within a region. |
| --encryption-configuration | — | string | No | Server-side encryption configuration as a JSON string or file path (e.g., `file://config.json`). Supports `sseAlgorithm`: `AES256` or `KMS`. |

```bash
# Create a basic table bucket
ossutil tables-api create-table-bucket --name my-table-bucket

# Create with AES256 encryption
ossutil tables-api create-table-bucket --name my-table-bucket --encryption-configuration '{"sseAlgorithm":"AES256"}'

# Create with KMS encryption using a config file
ossutil tables-api create-table-bucket --name my-table-bucket --encryption-configuration file://encryption-config.json
```

### list-table-buckets

**Purpose**: List all table buckets owned by the authenticated user.

**Syntax**:
```bash
ossutil tables-api list-table-buckets [--prefix <prefix>] [--max-buckets <int>] [--continuation-token <token>] [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --prefix | — | string | No | Filter buckets whose names start with this prefix. |
| --max-buckets | — | integer | No | Maximum number of buckets to return per request. |
| --continuation-token | — | string | No | Token from a previous response to fetch the next page. |

```bash
# List all table buckets
ossutil tables-api list-table-buckets

# List buckets starting with "prod-"
ossutil tables-api list-table-buckets --prefix prod-

# Paginate results (first 10)
ossutil tables-api list-table-buckets --max-buckets 10
```

### get-table-bucket

**Purpose**: Retrieve detailed information about a specific table bucket.

**Syntax**:
```bash
ossutil tables-api get-table-bucket --table-bucket-arn <arn> [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --table-bucket-arn | — | string | Yes | ARN in format `acs:osstables:{region}:{accountId}:bucket/{name}`. |

```bash
# Get bucket details
ossutil tables-api get-table-bucket --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket
```

### delete-table-bucket

**Purpose**: Delete a table bucket. All namespaces and tables must be removed first.

**Syntax**:
```bash
ossutil tables-api delete-table-bucket --table-bucket-arn <arn> [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --table-bucket-arn | — | string | Yes | ARN in format `acs:osstables:{region}:{accountId}:bucket/{name}`. |

```bash
# Delete an empty table bucket
ossutil tables-api delete-table-bucket --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket
```

### put-table-bucket-encryption

**Purpose**: Configure server-side encryption for a table bucket.

**Syntax**:
```bash
ossutil tables-api put-table-bucket-encryption --table-bucket-arn <arn> --encryption-configuration <json-or-file> [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --table-bucket-arn | — | string | Yes | ARN in format `acs:osstables:{region}:{accountId}:bucket/{name}`. |
| --encryption-configuration | — | string | Yes | JSON string or file path specifying `sseAlgorithm` (`AES256` or `KMS`) and optional `kmsKeyId`. |

```bash
# Enable AES256 encryption
ossutil tables-api put-table-bucket-encryption --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket --encryption-configuration '{"sseAlgorithm":"AES256"}'

# Enable KMS encryption
ossutil tables-api put-table-bucket-encryption --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket --encryption-configuration '{"sseAlgorithm":"KMS","kmsKeyId":"1234abcd-12ab-34cd-56ef-1234567890ab"}'
```

### get-table-bucket-encryption

**Purpose**: Retrieve the current encryption configuration of a table bucket.

**Syntax**:
```bash
ossutil tables-api get-table-bucket-encryption --table-bucket-arn <arn> [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --table-bucket-arn | — | string | Yes | ARN in format `acs:osstables:{region}:{accountId}:bucket/{name}`. |

```bash
# Get encryption settings
ossutil tables-api get-table-bucket-encryption --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket
```

### delete-table-bucket-encryption

**Purpose**: Remove encryption configuration from a table bucket. New data will not be encrypted.

**Syntax**:
```bash
ossutil tables-api delete-table-bucket-encryption --table-bucket-arn <arn> [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --table-bucket-arn | — | string | Yes | ARN in format `acs:osstables:{region}:{accountId}:bucket/{name}`. |

```bash
# Disable encryption
ossutil tables-api delete-table-bucket-encryption --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket
```

### put-table-bucket-policy

**Purpose**: Set a resource policy to control access to the table bucket.

**Syntax**:
```bash
ossutil tables-api put-table-bucket-policy --table-bucket-arn <arn> --resource-policy <json-or-file> [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --table-bucket-arn | — | string | Yes | ARN in format `acs:osstables:{region}:{accountId}:bucket/{name}`. |
| --resource-policy | — | string | Yes | JSON-formatted policy string or file path defining access permissions. |

```bash
# Set a public-read policy
ossutil tables-api put-table-bucket-policy --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket --resource-policy '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":"*","Action":"osstables:*","Resource":"acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket"}]}'
```

### get-table-bucket-policy

**Purpose**: Retrieve the resource policy attached to a table bucket.

**Syntax**:
```bash
ossutil tables-api get-table-bucket-policy --table-bucket-arn <arn> [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --table-bucket-arn | — | string | Yes | ARN in format `acs:osstables:{region}:{accountId}:bucket/{name}`. |

```bash
# Get current policy
ossutil tables-api get-table-bucket-policy --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket
```

### put-table-bucket-maintenance-configuration

**Purpose**: Configure maintenance behavior such as Unreferenced File Cleanup for Iceberg tables.

**Syntax**:
```bash
ossutil tables-api put-table-bucket-maintenance-configuration --table-bucket-arn <arn> --type <type> --value <json-or-file> [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --table-bucket-arn | — | string | Yes | ARN in format `acs:osstables:{region}:{uid}:bucket/{bucket-name}`. |
| --type | — | string | Yes | Maintenance type. Only `iceberg` is supported. |
| --value | — | string | Yes | JSON configuration or file path. Example: `{"settings":{"unreferenced_file_cleanup":{"enabled":true}}}`. |

```bash
# Enable Unreferenced File Cleanup
ossutil tables-api put-table-bucket-maintenance-configuration --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket --type iceberg --value '{"settings":{"unreferenced_file_cleanup":{"enabled":true}}}'

# Load config from file
ossutil tables-api put-table-bucket-maintenance-configuration --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket --type iceberg --value file://maintenance.json
```

### get-table-bucket-maintenance-configuration

**Purpose**: Retrieve the current maintenance configuration of a table bucket.

**Syntax**:
```bash
ossutil tables-api get-table-bucket-maintenance-configuration --table-bucket-arn <arn> [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --table-bucket-arn | — | string | Yes | ARN in format `acs:osstables:{region}:{uid}:bucket/{bucket-name}`. |

```bash
# Get maintenance settings
ossutil tables-api get-table-bucket-maintenance-configuration --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket
```

### create-table

**Purpose**: Create an Iceberg table within a namespace in a table bucket.

**Syntax**:
```bash
ossutil tables-api create-table --table-bucket-arn <arn> --namespace <ns> --name <name> --format ICEBERG --metadata <json-or-file> [--encryption-configuration <json-or-file>] [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --table-bucket-arn | — | string | Yes | ARN in format `acs:osstables:{region}:{uid}:bucket/{bucket-name}`. |
| --namespace | — | string | Yes | Namespace where the table will be created. |
| --name | — | string | Yes | Table name (lowercase letters, numbers, underscores; starts/ends with letter/number). |
| --format | — | string | Yes | Table format. Only `ICEBERG` is supported. |
| --metadata | — | string | Yes | JSON schema definition or file path. |
| --encryption-configuration | — | string | No | Optional table-level encryption config. |

```bash
# Create a simple Iceberg table
ossutil tables-api create-table --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket --namespace my_namespace --name my_table --format ICEBERG --metadata '{"iceberg":{"schema":{"fields":[{"id":1,"name":"id","type":"long","required":true},{"id":2,"name":"data","type":"string"}]}}}'

# Load schema from file
ossutil tables-api create-table --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket --namespace my_namespace --name my_table --format ICEBERG --metadata file://table_metadata.json
```

### list-tables

**Purpose**: List all tables in a specified namespace.

**Syntax**:
```bash
ossutil tables-api list-tables --table-bucket-arn <arn> --namespace <ns> [--prefix <prefix>] [--max-tables <int>] [--continuation-token <token>] [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --table-bucket-arn | — | string | Yes | ARN in format `acs:osstables:{region}:{uid}:bucket/{bucket-name}`. |
| --namespace | — | string | Yes | Namespace to list tables from. |
| --prefix | — | string | No | Filter tables by name prefix. |
| --max-tables | — | integer | No | Maximum tables to return. |
| --continuation-token | — | string | No | Pagination token for next page. |

```bash
# List all tables in namespace
ossutil tables-api list-tables --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket --namespace my_namespace

# List tables starting with "logs_"
ossutil tables-api list-tables --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket --namespace my_namespace --prefix logs_
```

### get-table

**Purpose**: Describe a table’s schema, creation time, and metadata.

**Syntax**:
```bash
ossutil tables-api get-table [--table-bucket-arn <arn> --namespace <ns> --name <name>] [--table-arn <arn>] [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --table-bucket-arn | — | string | Conditional | ARN of the bucket. Required if not using `--table-arn`. |
| --namespace | — | string | Conditional | Namespace. Required if not using `--table-arn`. |
| --name | — | string | Conditional | Table name. Required if not using `--table-arn`. |
| --table-arn | — | string | Conditional | Full table ARN: `acs:osstables:{region}:{uid}:bucket/{bucket}/table/{ns}/{name}`. Alternative to the above three. |

```bash
# Get table by components
ossutil tables-api get-table --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket --namespace my_namespace --name my_table

# Get table by full ARN
ossutil tables-api get-table --table-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket/table/my_namespace/my_table
```

### delete-table

**Purpose**: Delete a table from a namespace. Irreversible.

**Syntax**:
```bash
ossutil tables-api delete-table --table-bucket-arn <arn> --namespace <ns> --name <name> [--version-token <token>] [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --table-bucket-arn | — | string | Yes | ARN in format `acs:osstables:{region}:{uid}:bucket/{bucket-name}`. |
| --namespace | — | string | Yes | Namespace containing the table. |
| --name | — | string | Yes | Name of the table to delete. |
| --version-token | — | string | No | Version token to prevent concurrent modification conflicts. |

```bash
# Delete a table
ossutil tables-api delete-table --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket --namespace my_namespace --name my_table

# Delete with version token for safety
ossutil tables-api delete-table --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket --namespace my_namespace --name my_table --version-token abc123
```

### rename-table

**Purpose**: Rename a table or move it to a different namespace.

**Syntax**:
```bash
ossutil tables-api rename-table --table-bucket-arn <arn> --namespace <current-ns> --name <current-name> [--new-name <name>] [--new-namespace <ns>] [--version-token <token>] [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --table-bucket-arn | — | string | Yes | ARN in format `acs:osstables:{region}:{uid}:bucket/{bucket-name}`. |
| --namespace | — | string | Yes | Current namespace of the table. |
| --name | — | string | Yes | Current table name. |
| --new-name | — | string | Conditional | New table name (if changing name). |
| --new-namespace | — | string | Conditional | Target namespace (if moving). |
| --version-token | — | string | No | Version token for optimistic locking. |

```bash
# Rename table in same namespace
ossutil tables-api rename-table --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket --namespace my_namespace --name old_table --new-name new_table

# Move table to new namespace
ossutil tables-api rename-table --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket --namespace my_namespace --name my_table --new-namespace target_namespace

# Rename and move with version token
ossutil tables-api rename-table --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket --namespace my_namespace --name old_table --new-name new_table --new-namespace target_namespace --version-token abc123def456
```

### put-table-policy

**Purpose**: Apply a resource policy to control access to a specific table.

**Syntax**:
```bash
ossutil tables-api put-table-policy --table-bucket-arn <arn> --namespace <ns> --name <name> --resource-policy <json-or-file> [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --table-bucket-arn | — | string | Yes | ARN in format `acs:osstables:{region}:{uid}:bucket/{bucket-name}`. |
| --namespace | — | string | Yes | Namespace of the table. |
| --name | — | string | Yes | Table name. |
| --resource-policy | — | string | Yes | JSON policy string or file path. |

```bash
# Grant read access to a RAM user
ossutil tables-api put-table-policy --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket --namespace my_namespace --name my_table --resource-policy '{"Version":"1","Statement":[{"Effect":"Allow","Principal":["acs:ram::9876543210:root"],"Action":["osstables:GetTable"],"Resource":["acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket/namespace/my_namespace/table/my_table"]}]}'
```

### get-table-policy

**Purpose**: Retrieve the resource policy attached to a table.

**Syntax**:
```bash
ossutil tables-api get-table-policy --table-bucket-arn <arn> --namespace <ns> --name <name> [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --table-bucket-arn | — | string | Yes | ARN in format `acs:osstables:{region}:{uid}:bucket/{bucket-name}`. |
| --namespace | — | string | Yes | Namespace of the table. |
| --name | — | string | Yes | Table name. |

```bash
# Get table policy
ossutil tables-api get-table-policy --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket --namespace my_namespace --name my_table
```

### get-table-encryption

**Purpose**: Retrieve the encryption configuration of a table. If none, inherits from bucket.

**Syntax**:
```bash
ossutil tables-api get-table-encryption --table-bucket-arn <arn> --namespace <ns> --name <name> [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --table-bucket-arn | — | string | Yes | ARN in format `acs:osstables:{region}:{uid}:bucket/{bucket-name}`. |
| --namespace | — | string | Yes | Namespace of the table. |
| --name | — | string | Yes | Table name. |

```bash
# Get table encryption settings
ossutil tables-api get-table-encryption --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket --namespace my_namespace --name my_table
```

### put-table-maintenance-configuration

**Purpose**: Configure Iceberg-specific maintenance like compaction and snapshot management.

**Syntax**:
```bash
ossutil tables-api put-table-maintenance-configuration --table-bucket-arn <arn> --namespace <ns> --name <name> --type <type> --value <json-or-file> [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --table-bucket-arn | — | string | Yes | ARN in format `acs:osstables:{region}:{uid}:bucket/{bucket-name}`. |
| --namespace | — | string | Yes | Namespace of the table. |
| --name | — | string | Yes | Table name. |
| --type | — | string | Yes | Maintenance type: `icebergCompaction` or `icebergSnapshotManagement`. |
| --value | — | string | Yes | JSON configuration or file path. |

```bash
# Enable compaction with target file size
ossutil tables-api put-table-maintenance-configuration --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket --namespace my_namespace --name my_table --type icebergCompaction --value '{"status":"enabled","settings":{"targetFileSizeMB":512}}'

# Enable snapshot management
ossutil tables-api put-table-maintenance-configuration --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket --namespace my_namespace --name my_table --type icebergSnapshotManagement --value '{"status":"enabled","settings":{"minSnapshotsToKeep":5,"maxSnapshotAgeHours":168}}'

# Disable compaction
ossutil tables-api put-table-maintenance-configuration --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket --namespace my_namespace --name my_table --type icebergCompaction --value '{"status":"disabled"}'
```

### get-table-maintenance-configuration

**Purpose**: Retrieve current maintenance settings for a table.

**Syntax**:
```bash
ossutil tables-api get-table-maintenance-configuration --table-bucket-arn <arn> --namespace <ns> --name <name> [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --table-bucket-arn | — | string | Yes | ARN in format `acs:osstables:{region}:{uid}:bucket/{bucket-name}`. |
| --namespace | — | string | Yes | Namespace of the table. |
| --name | — | string | Yes | Table name. |

```bash
# Get table maintenance config
ossutil tables-api get-table-maintenance-configuration --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket --namespace my_namespace --name my_table
```

### get-table-maintenance-job-status

**Purpose**: Check the execution status of automated maintenance jobs for a table.

**Syntax**:
```bash
ossutil tables-api get-table-maintenance-job-status --table-bucket-arn <arn> --namespace <ns> --name <name> [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --table-bucket-arn | — | string | Yes | ARN in format `acs:osstables:{region}:{uid}:bucket/{bucket-name}`. |
| --namespace | — | string | Yes | Namespace of the table. |
| --name | — | string | Yes | Table name. |

```bash
# Check job status
ossutil tables-api get-table-maintenance-job-status --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket --namespace my_namespace --name my_table
```

### get-table-metadata-location

**Purpose**: Retrieve the metadata file path and version token for optimistic locking.

**Syntax**:
```bash
ossutil tables-api get-table-metadata-location --table-bucket-arn <arn> --namespace <ns> --name <name> [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --table-bucket-arn | — | string | Yes | ARN in format `acs:osstables:{region}:{uid}:bucket/{bucket-name}`. |
| --namespace | — | string | Yes | Namespace of the table. |
| --name | — | string | Yes | Table name. |

```bash
# Get metadata location and version token
ossutil tables-api get-table-metadata-location --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket --namespace my_namespace --name my_table
```

### update-table-metadata-location

**Purpose**: Update the table’s metadata location after committing a new snapshot.

**Syntax**:
```bash
ossutil tables-api update-table-metadata-location --table-bucket-arn <arn> --namespace <ns> --name <name> --metadata-location <path> --version-token <token> [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --table-bucket-arn | — | string | Yes | ARN in format `acs:osstables:{region}:{uid}:bucket/{bucket-name}`. |
| --namespace | — | string | Yes | Namespace of the table. |
| --name | — | string | Yes | Table name. |
| --metadata-location | — | string | Yes | Path to the new metadata file (e.g., OSS URI). |
| --version-token | — | string | Yes | Version token from `get-table-metadata-location` for optimistic locking. |

```bash
# Update metadata location after commit
ossutil tables-api update-table-metadata-location --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket --namespace my_namespace --name my_table --metadata-location oss://my-table-bucket/metadata/my_namespace/my_table/metadata/00001-abc123.metadata.json --version-token abc123def456
```

## Common Scenarios

### Scenario 1: Set Up a Secure Data Lake Table Bucket

```bash
# Step 1: Create a table bucket with AES256 encryption
ossutil tables-api create-table-bucket --name analytics-bucket --encryption-configuration '{"sseAlgorithm":"AES256"}'

# Step 2: Enable Unreferenced File Cleanup for cost optimization
ossutil tables-api put-table-bucket-maintenance-configuration --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/analytics-bucket --type iceberg --value '{"settings":{"unreferenced_file_cleanup":{"enabled":true}}}'

# Step 3: Create a namespace and table (assume namespace exists or is created via other means)
ossutil tables-api create-table --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/analytics-bucket --namespace sales --name daily_revenue --format ICEBERG --metadata file://revenue_schema.json
```

### Scenario 2: Migrate and Secure an Existing Table

```bash
# Step 1: Get current table details and version token
ossutil tables-api get-table --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/old-bucket --namespace default --name events
TOKEN=$(ossutil tables-api get-table-metadata-location --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/old-bucket --namespace default --name events --output json | jq -r '.versionToken')

# Step 2: Rename table to new namespace with version token
ossutil tables-api rename-table --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/old-bucket --namespace default --name events --new-namespace production --version-token "$TOKEN"

# Step 3: Apply a restrictive policy
ossutil tables-api put-table-policy --table-bucket-arn acs:osstables:cn-hangzhou:1234567890:bucket/old-bucket --namespace production --name events --resource-policy file://restricted-policy.json
```

## Environment Setup

### Installation
Install `ossutil` by following the official installation guide for your operating system. Ensure the binary is in your system PATH.

### Configuration
Configure credentials using:
```bash
ossutil config
```
This prompts for AccessKey ID, AccessKey Secret, and default region. Alternatively, set environment variables:
```bash
export OSS_ACCESS_KEY_ID=your-access-key-id
export OSS_ACCESS_KEY_SECRET=your-access-key-secret
export OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com
```

## FAQ

Q: How do I configure credentials for the ossutil CLI?
A: Run `ossutil config` to interactively set up credentials, or use environment variables `OSS_ACCESS_KEY_ID` and `OSS_ACCESS_KEY_SECRET`. The tool also reads from `~/.ossutilconfig`.

Q: What is the difference between table bucket encryption and table encryption?
A: Table bucket encryption applies to all tables by default. Table-level encryption overrides the bucket setting for that specific table. If no table encryption is set, it inherits from the bucket.

Q: How do I handle pagination when listing many tables or buckets?
A: Use `--max-buckets` or `--max-tables` to limit results per call, and pass the `continuation-token` from the previous response to fetch the next page.

Q: Why do I need a version token for rename or metadata updates?
A: Version tokens enable optimistic locking to prevent conflicts during concurrent modifications. Always fetch the current token before updating.

Q: How can I verify that a maintenance job ran successfully?
A: Use `get-table-maintenance-job-status` to check the recent execution status and any failure reasons for compaction or snapshot management jobs.