CreateTable - Create an Iceberg table in an OSS Table Bucket - Object Storage Service

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: `acs:osstables:{region}:{uid}:bucket/{bucketName}`.
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.
format	string	Yes	ICEBERG	The table format. Only `ICEBERG` is supported.
encryptionConfiguration	object	No	-	Server-side encryption configuration. If omitted, the table inherits encryption from the table bucket. Child nodes: `sseAlgorithm`, `kmsKeyArn`.
sseAlgorithm	string	Yes, if `encryptionConfiguration` is specified.	AES256	The encryption algorithm. Only `AES256` is supported. Parent node: `encryptionConfiguration`.
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: `encryptionConfiguration`.
metadata	object	No	-	Iceberg table metadata, including schema, partitioning rules, write order, and properties. Child node: `iceberg`.
iceberg	object	Yes, if `metadata` is specified.	-	Iceberg table metadata. Parent node: `metadata`. Child nodes: `schema`, `partitionSpec`, `writeOrder`, and `properties`.
schema	object	No	-	Iceberg table schema definition. Parent node: `iceberg`. Child node: `fields`.
fields	array	Yes, if `schema` is specified.	-	Column definitions. Each element describes one column: id: Optional integer. Recommended; must be unique within the schema. Referenced by `sourceId` in `partitionSpec`. name: Required. The field name. type: Required. The field data type. Supported types are listed in Schema Field Types. required: Optional boolean. Defaults to `false`. When `true`, the column rejects `NULL` values. Parent node: `schema`
partitionSpec	object	No	-	Table partitioning rule. Parent node: `iceberg`. Child nodes: specId: Optional integer. Defaults to `0`. fields: Partition field definitions. Details in the next row.
fields	array			sourceId: Required. Must match a field `id` in the schema. transform: Required. The partition transformation type. Supported values are `identity`, `void`, `year`, `month`, `day`, `hour`, `bucket[N]`, and `truncate[N]`. fieldId: Optional integer. name: Required. The name of the partition field. Parent node: `partitionSpec`
writeOrder	object	No	-	Physical sort order for writes. Parent node: `iceberg`. Child nodes: orderId: Optional integer. Defaults to `1`; must be at least `1`. fields: Sort field definitions. Details in the next row.
fields	array			sourceId: Required. Must match a field `id` in the schema. transform: Required. The sort transformation type. Supported values are `identity`, `void`, `year`, `month`, `day`, `hour`, `bucket[N]`, and `truncate[N]`. direction: Required. `asc` (ascending) or `desc` (descending). nullOrder: Required. `nulls-first` or `nulls-last`. Parent node: `writeOrder`
properties	object	No	-	Iceberg table properties in key-value format. Parent node: `iceberg`. Common properties: `format-version` (Iceberg format version, 1–3), `write.format.default` (write file format, such as `parquet`), and `write.target-file-size-bytes` (target file size).

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: `acs:osstables:{region}:{uid}:bucket/{bucketName}/table/{tableId}`.
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 (_), and cannot start or end with an underscore.
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.