CreateTableBucket

Usage notes

A Table Bucket is the top-level resource container for OSS Tables. It stores and manages tables in Apache Iceberg format. A Table Bucket uses a three-level hierarchy: Table Bucket > namespace > table.

When you call this operation:

An Alibaba Cloud account can create a maximum of 10 Table Buckets in a single region.
A Table Bucket name must be unique within the same Alibaba Cloud account and region.

Permissions

API	Action	Description
CreateTableBucket	oss:CreateTableBucket	Required to create a Table Bucket.
CreateTableBucket	oss:PutTableBucketEncryption	Required if you specify the encryptionConfiguration parameter.

Request syntax

PUT /buckets HTTP/1.1
Content-type: application/json
Host: cn-hangzhou.oss-tables.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

{
   "encryptionConfiguration": {
      "kmsKeyArn": "string",
      "sseAlgorithm": "string"
   },
   "name": "string"
}

Request parameters

Parameter	Type	Required	Example	Description
name	String	Yes	my-table-bucket	The Table Bucket name. Must be 3 to 32 characters and can contain only lowercase letters, digits, and hyphens (-). Cannot start or end with a hyphen. Cannot start with oss, acs, aliyun, alibaba, or aws.
encryptionConfiguration	Container	No	-	The server-side encryption configuration.
sseAlgorithm	String	No	AES256	The encryption algorithm. Only AES256 is supported. Parent node: encryptionConfiguration
kmsKeyArn	String	No	-	The KMS key ARN. This parameter must be left empty. Parent node: encryptionConfiguration

Response parameters

Parameter	Type	Example	Description
arn	String	acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket	The ARN of the Table Bucket.

Examples

Request example

Creates a Table Bucket named my-table-bucket with AES256 server-side encryption.

PUT /buckets 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****

{
   "name": "my-table-bucket",
   "encryptionConfiguration": {
      "sseAlgorithm": "AES256"
   }
}

Response example

HTTP/1.1 200 OK
Server: AliyunOSS
x-oss-request-id: 5C06A3B67B8B5A3DA422****
x-oss-server-time: 3
Content-Type: application/json


{
   "arn": "acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket"
}

SDKs

The following SDKs support this operation:

ossutil CLI

The ossutil equivalent is create-table-bucket.

Error codes

Error code	HTTP status code	Description
BadRequestException	400	The request is invalid or malformed.
ForbiddenException	403	The caller lacks the required permissions.
ConflictException	409	The request conflicts with a previous write operation. Retry the request.