# oss-table

Part of **OSS**

# Object Storage Service Structured Storage

## Capabilities Overview

| Sub-capability | Calling Mode | Description |
|----------------|--------------|-------------|
| Manage Namespace | Synchronous | Create, delete, and retrieve namespace information. |
| Manage Table Bucket | Synchronous | Create, delete, and configure table buckets including encryption and policies. |
| Manage Table | Synchronous | Create, delete, rename, and configure tables within table buckets. |

## API Calling Patterns

### Authentication
Use **OSS4-HMAC-SHA256 signature authentication** as the primary method.

- **Header format**:  
  `Authorization: OSS4-HMAC-SHA256 Credential={AccessKeyID}/{date}/{region}/osstables/aliyun_v4_request,Signature={SignatureValue}`
- **Environment variable**: `ALIBABA_CLOUD_ACCESS_KEY_ID` and `ALIBABA_CLOUD_ACCESS_KEY_SECRET`
- Other methods (e.g., STS tokens) may be supported, but OSS4-HMAC-SHA256 is recommended for direct API calls.

### Service Endpoint (Endpoint)
APIs use region-specific endpoints with the pattern:  
`https://{region}.oss-tables.aliyuncs.com`

Common regions:
- `cn-hangzhou`
- `cn-shanghai`
- `cn-beijing`

### Synchronous Request Pattern
All operations in this domain are **synchronous**:
1. Construct a properly signed HTTP request with the correct method (GET, PUT, DELETE, etc.)
2. Send the request to the appropriate endpoint with required URI path and query parameters
3. Receive an immediate JSON or empty (204) response
4. Handle success (2xx) or error (4xx/5xx) status codes directly

No polling or streaming is used—responses are returned in a single round trip.

## Parameter Reference

### Manage Namespace

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|--------|--------|------------|-------------|
| tableBucketARN | string | Yes | — | Must be a valid ARN format | The ARN of the table bucket. Format: `acs:osstables:{region}:{accountId}:bucket/{bucketName}`. |
| namespace | array / string | Yes | — | 1–255 chars; lowercase letters, digits, underscores only; cannot start/end with underscore; cannot be prefixed with `oss`, `acs`, `aliyun`, `alibaba`, or `aws` | For CreateNamespace: array with one namespace name. For DeleteNamespace: single namespace name. |

### Manage Table Bucket

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|--------|--------|------------|-------------|
| name | String | Yes | — | 3–32 chars; lowercase letters, digits, hyphens; cannot start/end with hyphen; cannot start with reserved prefixes | The name of the Table Bucket. |
| tableBucketARN | string | Yes | — | — | The ARN of the Table Bucket. Format: `acs:osstables:{region}:{accountId}:bucket/{bucketName}`. |
| encryptionConfiguration | object | No | — | — | Server-side encryption configuration container. |
| sseAlgorithm | string | Conditional | AES256 | Only `AES256` is supported | Encryption algorithm. Required if `encryptionConfiguration` is specified. |
| kmsKeyArn | string | No | — | Must be left empty | KMS key ARN (not supported; must be empty). |
| maxBuckets | Integer | No | 1,000 | 1 to 1,000 | Maximum number of buckets to return in ListTableBuckets. |
| prefix | string | No | — | — | Filter buckets by name prefix. |
| continuationToken | string | No | — | — | Pagination token for listing buckets. |

### Manage Table

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|--------|--------|------------|-------------|
| tableBucketARN | string | Yes | — | — | ARN of the table bucket. |
| namespace | string | Yes | — | — | Namespace containing the table. |
| name | string | Yes | — | 1–255 chars; lowercase letters, digits, underscores; cannot start/end with underscore | Table name (must be unique in namespace). |
| format | string | Yes | — | Only `ICEBERG` is supported | Table format. |
| versionToken | string | Conditional | — | — | Used for optimistic locking in RenameTable, DeleteTable, and UpdateTableMetadataLocation. |
| metadata | object | No | — | — | Iceberg table metadata (schema, partitionSpec, etc.). |
| resourcePolicy | string | Yes (for PutTablePolicy) | — | — | JSON-escaped IAM policy string. |
| type | string | Yes (for maintenance config) | — | `icebergCompaction` or `icebergSnapshotManagement` | Maintenance configuration type. |
| newNamespaceName | string | No | — | — | New namespace when renaming/moving a table. |
| newName | string | No | — | 1–255 chars; lowercase letters, digits, underscores | New table name. |

## Code Examples

### Create a Namespace - HTTP - China

```http
PUT /namespaces/acs%3Aosstables%3Acn-hangzhou%3A1234567890%3Abucket%2Fmy-table-bucket HTTP/1.1
Content-type: application/json
Host: cn-hangzhou.oss-tables.aliyuncs.com
Date: Thu, 10 Apr 2025 08:00:00 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/osstables/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c****

{
   "namespace": ["my_namespace"]
}
```

### Create an Iceberg Table - HTTP - China

```http
PUT /tables/acs%3Aosstables%3Acn-hangzhou%3A1234567890%3Abucket%2Fmy-table-bucket/my_namespace HTTP/1.1
Content-type: application/json
Host: cn-hangzhou.oss-tables.aliyuncs.com
Date: Thu, 10 Apr 2025 08:00:00 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/osstables/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c****

{
   "name": "basic_table",
   "format": "ICEBERG",
   "metadata": {
      "iceberg": {
         "schema": {
            "fields": [
               {"id": 1, "name": "id", "type": "long", "required": true},
               {"id": 2, "name": "data", "type": "string"}
            ]
         }
      }
   }
}
```

### Set Table Bucket Encryption - HTTP - China

```http
PUT /buckets/acs%3Aosstables%3Acn-hangzhou%3A1234567890%3Abucket%2Fmy-table-bucket/encryption HTTP/1.1
Content-Type: application/json
Host: cn-hangzhou.oss-tables.aliyuncs.com
Date: GMT Date
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/osstables/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c****

{
   "encryptionConfiguration": {
      "sseAlgorithm": "AES256"
   }
}
```

### List Tables in a Namespace - HTTP - China

```http
GET /tables/acs%3Aosstables%3Acn-hangzhou%3A1234567890%3Abucket%2Fmy-table-bucket?namespace=my_namespace HTTP/1.1
Host: cn-hangzhou.oss-tables.aliyuncs.com
Date: Thu, 10 Apr 2025 08:00:00 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/osstables/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c****
```

### Rename a Table - HTTP - China

```http
PUT /tables/acs%3Aosstables%3Acn-hangzhou%3A1234567890%3Abucket%2Fmy-table-bucket/my_namespace/my_table/rename HTTP/1.1
Content-type: application/json
Host: cn-hangzhou.oss-tables.aliyuncs.com
Date: Thu, 10 Apr 2025 08:00:00 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/osstables/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c****

{
   "newNamespaceName": "new_namespace",
   "newName": "new_table",
   "versionToken": "aaabbb"
}
```

### Get Table Metadata Location - HTTP - China

```http
GET /tables/acs%3Aosstables%3Acn-hangzhou%3A1234567890%3Abucket%2Fmy-table-bucket/my_namespace/my_table/metadata-location HTTP/1.1
Host: cn-hangzhou.oss-tables.aliyuncs.com
Date: Thu, 10 Apr 2025 08:00:00 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/osstables/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c****
```

## Response Format

```json
{
   "namespace": ["my_namespace"],
   "tableBucketARN": "acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket"
}
```

**Key Fields**:
- `namespace` — The created or retrieved namespace name(s)
- `tableBucketARN` — The ARN of the associated table bucket
- `arn` — Resource ARN (for bucket creation)
- `tableARN` — Full ARN of a table (includes table ID)
- `versionToken` — Token for optimistic locking in concurrent operations
- `metadataLocation` — OSS path to the Iceberg metadata JSON file
- `warehouseLocation` — Base OSS path for table data files
- `continuationToken` — Pagination token for list operations

## Error Handling

| Error Code (Code) | Description (Description) | Recommended Action (Recommended Action) |
|-------------------|---------------------------|----------------------------------------|
| BadRequestException | The request is invalid or malformed. | Validate request syntax, parameter names, and values against the API specification. |
| ForbiddenException | The caller lacks permission for this request. | Ensure your RAM user or role has the required OSS permissions (e.g., `oss:CreateNamespace`). |
| NotFoundException | The requested resource does not exist. | Verify the ARN, namespace, or table name is correct and the resource exists. |
| ConflictException | The specified namespace already exists. (or version conflict) | For create operations, choose a different name. For updates, fetch the latest `versionToken` and retry. |

### Rate Limits & Retry
- Table Bucket creation: Max 10 per account per region
- ListTables: Max 1,000 tables per request
- General QPS: Up to 100 requests per second per account for most operations

Use exponential backoff (e.g., 1s, 2s, 4s) for retries on 429 or 5xx errors. The `Retry-After` header is not used; rely on client-side backoff.

## Environment Requirements

- Use standard HTTP clients (curl, Python `requests`, Java `HttpClient`, etc.)
- Set environment variables:
  ```bash
  export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
  export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
  ```
- No specific SDK is required—raw HTTP works—but official Alibaba Cloud SDKs can simplify signing.

## FAQ

Q: How do I authenticate my API requests?
A: Use OSS4-HMAC-SHA256 signature authentication. Sign each request using your AccessKey ID and Secret, following the v4 signing process documented for OSS.

Q: Can I use this API to manage non-Iceberg tables?
A: No. The Structured Storage API currently only supports Apache Iceberg table format (`format: "ICEBERG"`).

Q: What happens if I delete a table bucket that contains tables?
A: The DeleteTableBucket operation will fail with a `ConflictException`. You must first delete all namespaces and tables within the bucket.

Q: How do I handle concurrent table modifications?
A: Use the `versionToken` from `GetTable` or `GetTableMetadataLocation` in update operations (e.g., RenameTable, UpdateTableMetadataLocation). If the token doesn’t match the current version, a `ConflictException` is returned.

Q: Are table bucket names globally unique?
A: Table bucket names must be unique within a region and Alibaba Cloud account, but not globally across all users.

## Pricing & Billing

### Billing Model
Per-request pricing. Each API call (successful or failed) counts as one request.

### Price Reference

| Tier / Operation | Input Price | Output Price |
|------------------|------------|-------------|
| CreateNamespace | 0.0001 / | — |
| DeleteNamespace | 0.001 / | — |
| CreateTable | 0.0001 / | 0.0001 / |
| GetTable | 0.001 / | 0.001 / |
| ListTables | 0.0001 / | 0.0001 / |
| DeleteTablePolicy | 0.0001 / | 0 / |

### Free Tier
- CreateTable, DeleteTablePolicy, GetTable, ListTables: 1,000 free requests per month
- DeleteNamespace: No free tier
- CreateNamespace: No free tier mentioned

### Usage Limits
- Table Buckets: Max 10 per account per region
- ListTables: Max 1,000 tables per response
- Request body size: Max 8,192 bytes for CreateTable

### Billing Notes
- Charges apply per API call, regardless of success
- Data storage and transfer fees are billed separately under OSS usage
- Encryption configuration changes do not incur additional costs beyond the API request fee