Creates an Iceberg table in a specified Table Bucket namespace.
Usage notes
This API supports only Iceberg tables, not Lance tables. To create Lance tables, use the Lance REST Namespace API or the Lance ecosystem (Spark, Trino, and other compute engines).
-
A table name must be 1 to 255 characters in length and can contain only lowercase letters, digits, and underscores (_). It cannot start or end with an underscore, and cannot start with oss, acs, aliyun, alibaba, or aws.
-
Before you create a table, make sure that the destination Table Bucket and namespace exist.
Permissions
|
API |
Action |
Description |
|
CreateTable |
oss:CreateTable |
Create a table. |
|
oss:PutTableData |
Write to the data bucket. Required when the metadata parameter is specified. |
|
|
oss:PutTableEncryption |
Required when the encryptionConfiguration parameter is specified. |
Request syntax
PUT /tables/{tableBucketARN}/{namespace} HTTP/1.1
Content-type: application/json
Host: cn-hangzhou.oss-tables.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
{
"name": "string",
"format": "string",
"encryptionConfiguration": {
"sseAlgorithm": "string",
"kmsKeyArn": "string"
},
"metadata": {
"iceberg": {
"schema": {
"fields": [
{
"id": number,
"name": "string",
"type": "string",
"required": boolean
}
]
},
"partitionSpec": {
"specId": number,
"fields": [
{
"sourceId": number,
"transform": "string",
"name": "string"
}
]
},
"writeOrder": {
"orderId": number,
"fields": [
{
"sourceId": number,
"transform": "string",
"direction": "string",
"nullOrder": "string"
}
]
},
"properties": {
"string": "string"
}
}
}
}
Parameters
|
Parameter |
Type |
Required |
Example |
Description |
|
tableBucketARN |
string |
Yes |
acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket |
The table bucket ARN, specified in the URI. Format: |
|
namespace |
string |
Yes |
my_namespace |
The namespace containing the table. Specified in the URI. |
|
name |
string |
Yes |
my_table |
The table name. Must be unique within the namespace, 1–255 characters, lowercase letters, digits, and underscores (_) only. Cannot start or end with an underscore, or start with oss, acs, aliyun, alibaba, or aws. |
|
format |
string |
Yes |
ICEBERG |
The table format. Only |
|
encryptionConfiguration |
object |
No |
- |
Server-side encryption configuration. If omitted, the table inherits encryption from the table bucket. Child nodes: |
|
sseAlgorithm |
string |
Yes, if |
AES256 |
The encryption algorithm. Only |
|
kmsKeyArn |
string |
No |
acs:kms:cn-hangzhou:1234567890:key/key-id |
The KMS key ARN. Not supported in the current version; must be left empty. Parent node: |
|
metadata |
object |
No |
- |
Iceberg table metadata, including schema, partitioning rules, write order, and properties. Child node: |
|
iceberg |
object |
Yes, if |
- |
Iceberg table metadata. Parent node: |
|
schema |
object |
No |
- |
Iceberg table schema definition. Parent node: |
|
fields |
array |
Yes, if |
- |
Column definitions. Each element describes one column:
Parent node: |
|
partitionSpec |
object |
No |
- |
Table partitioning rule. Parent node:
|
|
fields |
array |
Parent node: |
||
|
writeOrder |
object |
No |
- |
Physical sort order for writes. Parent node:
|
|
fields |
array |
Parent node: |
||
|
properties |
object |
No |
- |
Iceberg table properties in key-value format. Parent node: |
Response parameters
|
Parameter |
Type |
Example |
Description |
|
tableARN |
string |
acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket/table/table-id |
The created table ARN. Format: |
|
versionToken |
string |
abc123def456 |
Version token for optimistic locking. |
Examples
Example 1: Table with a schema
Creates a table with a two-field schema: id and data.
Request example
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"}
]
}
}
}
}
Example 2: Table with an identity partition
Creates a table with an identity partition on the region field.
Request example
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****
{
"format": "ICEBERG",
"metadata": {
"iceberg": {
"schema": {
"fields": [
{"id": 1, "name": "id", "type": "long", "required": true},
{"id": 2, "name": "region", "type": "string"},
{"id": 3, "name": "ts", "type": "timestamptz"}
]
},
"partitionSpec": {
"specId": 0,
"fields": [
{"sourceId": 2, "transform": "identity", "name": "region"}
]
}
}
},
"name": "partitioned_table"
}
Example 3: Table with time and bucket partitions
Creates a table with day and bucket partitions.
Request example
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****
{
"format": "ICEBERG",
"metadata": {
"iceberg": {
"schema": {
"fields": [
{"id": 1, "name": "id", "type": "long", "required": true},
{"id": 2, "name": "data", "type": "string"},
{"id": 3, "name": "ts", "type": "timestamptz"}
]
},
"partitionSpec": {
"fields": [
{"sourceId": 3, "transform": "day", "name": "ts_day"},
{"sourceId": 1, "transform": "bucket[256]", "name": "id_bucket"}
]
}
}
},
"name": "multi_partition_table"
}
Example 4: Table with a write order
Creates a table that sorts writes by ts descending, then id ascending.
Request example
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****
{
"format": "ICEBERG",
"metadata": {
"iceberg": {
"schema": {
"fields": [
{"id": 1, "name": "id", "type": "long", "required": true},
{"id": 2, "name": "ts", "type": "timestamptz"},
{"id": 3, "name": "category", "type": "string"}
]
},
"writeOrder": {
"orderId": 1,
"fields": [
{"sourceId": 2, "transform": "identity", "direction": "desc", "nullOrder": "nulls-last"},
{"sourceId": 1, "transform": "identity", "direction": "asc", "nullOrder": "nulls-first"}
]
}
}
},
"name": "sorted_table"
}
Example 5: Table with specified properties
Creates a table with Iceberg V2 format, default write format, and target file size properties.
Request example
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": "v2_table",
"format": "ICEBERG",
"metadata": {
"iceberg": {
"schema": {
"fields": [
{"id": 1, "name": "id", "type": "long", "required": true},
{"id": 2, "name": "name", "type": "string"}
]
},
"properties": {
"format-version": "2",
"write.format.default": "parquet",
"write.target-file-size-bytes": "134217728"
}
}
}
}
Example 6: Table with a full configuration
Creates a table with schema, partition spec, write order, properties, and encryption.
Request example
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****
{
"encryptionConfiguration": {
"sseAlgorithm": "AES256"
},
"format": "ICEBERG",
"metadata": {
"iceberg": {
"schema": {
"fields": [
{"id": 1, "name": "id", "type": "long", "required": true},
{"id": 2, "name": "ts", "type": "timestamptz", "required": true},
{"id": 3, "name": "region", "type": "string"},
{"id": 4, "name": "amount", "type": "double"}
]
},
"partitionSpec": {
"specId": 0,
"fields": [
{"sourceId": 2, "transform": "day", "name": "ts_day"},
{"sourceId": 3, "transform": "identity", "name": "region"}
]
},
"writeOrder": {
"orderId": 1,
"fields": [
{"sourceId": 2, "transform": "identity", "direction": "desc", "nullOrder": "nulls-last"},
{"sourceId": 1, "transform": "identity", "direction": "asc", "nullOrder": "nulls-first"}
]
},
"properties": {
"format-version": "2",
"write.format.default": "parquet"
}
}
},
"name": "full_featured_table"
}
Response example
HTTP/1.1 200 OK
Server: AliyunOSS
x-oss-request-id: 5C06A3B67B8B5A3DA422****
x-oss-server-time: 3
Content-Type: application/json
{
"tableARN": "acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket/table/table_id",
"versionToken": "aaabbb"
}
Schema field types
Primitive types
Primitive types supported by the Iceberg schema:
|
Type |
Minimum version |
Description |
Example value |
|
boolean |
V1 |
A boolean value. |
true |
|
int |
V1 |
A 32-bit signed integer. |
42 |
|
long |
V1 |
A 64-bit signed integer. |
1234567890 |
|
float |
V1 |
A 32-bit IEEE 754 floating-point number. |
3.14 |
|
double |
V1 |
A 64-bit IEEE 754 floating-point number. |
3.141592653589793 |
|
decimal(P,S) |
V1 |
A fixed-precision decimal number, where P is the precision (the total number of digits, up to 38) and S is the scale (the number of digits to the right of the decimal point). |
decimal(10,2) → 12345678.90 |
|
date |
V1 |
A calendar date without a time or time zone. |
2025-04-10 |
|
time |
V1 |
A time of day without a date or time zone, with microsecond precision. |
14:30:00.000000 |
|
timestamp |
V1 |
A timestamp without a time zone, with microsecond precision. |
2025-04-10T14:30:00.000000 |
|
timestamptz |
V1 |
A timestamp with time zone information, stored in UTC with microsecond precision. |
2025-04-10T14:30:00.000000+00:00 |
|
timestamp_ns |
V3 |
A timestamp without a time zone, with nanosecond precision. |
2025-04-10T14:30:00.000000000 |
|
timestamptz_ns |
V3 |
A timestamp with time zone information, stored in UTC with nanosecond precision. |
2025-04-10T14:30:00.000000000+00:00 |
|
string |
V1 |
A variable-length UTF-8 string. |
hello world |
|
uuid |
V1 |
A 128-bit universally unique identifier. |
550e8400-e29b-41d4-a716-446655440000 |
|
fixed[L] |
V1 |
A fixed-length byte array, where L is the length in bytes. |
fixed[16] |
|
binary |
V1 |
A variable-length byte array. |
- |
V3 types (timestamp_ns, timestamptz_ns, unknown, geometry, geography) require Iceberg format-version 3. OSS Tables defaults to V2. To use V3 types, set "format-version": "3" in the table properties.
Compatible source types for transforms
|
Transform |
Format |
Description |
Compatible source types |
|
identity |
identity |
Identity partition. Partitions by the raw value of the source field. |
All primitive types |
|
year |
year |
Partitions by the year from a source date or timestamp. |
date, timestamp, timestamptz, timestamp_ns, timestamptz_ns |
|
month |
month |
Partitions by the year and month from a source date or timestamp. |
date, timestamp, timestamptz, timestamp_ns, timestamptz_ns |
|
day |
day |
Partitions by the year, month, and day from a source date or timestamp. |
date, timestamp, timestamptz, timestamp_ns, timestamptz_ns |
|
hour |
hour |
Partitions by the year, month, day, and hour from a source timestamp. |
timestamp, timestamptz, timestamp_ns, timestamptz_ns |
|
bucket[N] |
bucket[N] |
Hash bucketing. Partitions data into N buckets by hashing the source field value and using a modulo operation. N must be a positive integer. |
int, long, decimal, date, time, timestamp, timestamptz, timestamp_ns, timestamptz_ns, string, uuid, fixed[L], binary |
|
truncate[N] |
truncate[N] |
Truncate partition. Truncates integer values to a width of N or string values to a length of N characters. N must be a positive integer. |
int, long, decimal, string, binary |
|
void |
void |
Void partition. Maps all values to null. Typically used to remove a partition field while preserving the partition evolution history. |
All types |
SDK
CreateTable is available in these SDKs:
ossutil CLI
The ossutil command for CreateTable is create-table.
Error codes
|
Error code |
HTTP status code |
Description |
|
BadRequestException |
400 |
The request is invalid or malformed. |
|
InvalidTableName |
400 |
Invalid table name. A table name must be 1–255 characters long, contain only lowercase letters, digits, and underscores (_), cannot start or end with an underscore, and cannot start with oss, acs, aliyun, alibaba, or aws. |
|
ForbiddenException |
403 |
The caller does not have permission to make this request. |
|
NotFoundException |
404 |
The requested resource does not exist. |
|
ConflictException |
409 |
The request conflicts with a previous write operation. |