CreateTable

Usage notes

Note

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: `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, or start with oss, acs, aliyun, alibaba, or aws.
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`, `schemaV2`, `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`
schemaV2	object	No	-	The schema V2 definition of the Iceberg table. In addition to primitive types, schemaV2 describes struct, list, and map fields, including nested combinations of these types. Parent node: `iceberg`. Child nodes: `type`, `fields`, `schema-id`, and `identifier-field-ids`. `schema` and `schemaV2` are mutually exclusive: only one of them can be specified in a request, and existing requests that use `schema` continue to work.
type	string	Yes, if `schemaV2` is specified.	struct	The type of the top-level `schemaV2` object. Fixed to `struct`, which indicates that the table consists of a group of fields. Parent node: `schemaV2`.
fields	array	Yes, if `schemaV2` is specified.	-	Field definitions. Each element describes one field: id: Required integer. Used to reference the field in the table schema. name: Required. The field name. type: Required. The field data type. Primitive types are strings and are the same as the field types supported by `schema`. For more information, see Schema Field Types in this topic. Complex types (struct, list, and map) are JSON objects that describe the internal structure by using the following attributes. For more information and examples, see Complex types (for schemaV2) in this topic: struct: uses `fields` to list sub-fields. Sub-fields use the same attributes, such as `id`, `name`, and `type`. list: uses `element` to specify the type of the elements, `element-id` to specify the element ID, and `element-required` to specify whether the elements are required (when `true`, the elements cannot be NULL). map: uses `key` and `value` to specify the types of the keys and values, `key-id` and `value-id` to specify their IDs, and `value-required` to specify whether the values are required (when `true`, the values cannot be NULL). Keys cannot be NULL. required: Optional boolean that specifies whether the field must have a value. Defaults to `false`. When `true`, the field cannot be NULL. doc: Optional. The description of the field. Parent node: `schemaV2`
schema-id	integer	No	0	The ID of the schema. Optional and can typically be omitted. After the table is created, the table metadata generated on the server prevails. Parent node: `schemaV2`.
identifier-field-ids	array	No	[10]	The list of field IDs that identify a record. The elements are integers. Optional. This parameter does not provide automatic deduplication or uniqueness validation. Parent node: `schemaV2`.
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"
}

Example 7: Table with struct, list, and map fields created by using schemaV2

Creates an orders table that contains struct, list, and map fields: order_id (long) is the order ID, customer (struct) is the customer information that consists of the name and level sub-fields, tags (list) is a list of string tags, and attributes (map) is a map of string key-value pairs. This request has been verified in an actual table creation test.

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": "orders_nested",
   "format": "ICEBERG",
   "metadata": {
      "iceberg": {
         "schemaV2": {
            "type": "struct",
            "schema-id": 0,
            "identifier-field-ids": [
               10
            ],
            "fields": [
               {
                  "id": 10,
                  "name": "order_id",
                  "type": "long",
                  "required": true
               },
               {
                  "id": 20,
                  "name": "customer",
                  "required": false,
                  "type": {
                     "type": "struct",
                     "fields": [
                        {
                           "id": 21,
                           "name": "name",
                           "type": "string",
                           "required": false
                        },
                        {
                           "id": 22,
                           "name": "level",
                           "type": "int",
                           "required": false
                        }
                     ]
                  }
               },
               {
                  "id": 30,
                  "name": "tags",
                  "required": false,
                  "type": {
                     "type": "list",
                     "element-id": 31,
                     "element": "string",
                     "element-required": false
                  }
               },
               {
                  "id": 40,
                  "name": "attributes",
                  "required": false,
                  "type": {
                     "type": "map",
                     "key-id": 41,
                     "key": "string",
                     "value-id": 42,
                     "value": "string",
                     "value-required": false
                  }
               }
            ]
         },
         "properties": {
            "format-version": "2"
         }
      }
   }
}

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.

Complex types (for schemaV2)

In schemaV2, the type of a field can be a string that specifies a primitive type, such as "long" or "string", or a JSON object that describes a complex type. Complex types include struct, list, and map.

The following examples show the definitions of individual fields. You can add these field definitions to the metadata.iceberg.schemaV2.fields array. For a complete request, see Example 7 in the Examples section.

struct

A struct groups multiple sub-fields that have fixed names. You define the sub-fields in the fields array. Each sub-field uses the same attributes, such as id, name, and type.

The following example defines a customer field that contains two sub-fields: name and level:

{
  "id": 20,
  "name": "customer",
  "required": false,
  "type": {
    "type": "struct",
    "fields": [
      {"id": 21, "name": "name", "type": "string", "required": false},
      {"id": 22, "name": "level", "type": "int", "required": false}
    ]
  }
}

list

A list stores multiple elements of the same type. element specifies the type of the elements, element-id specifies the ID of the elements in the table schema, and element-required specifies whether the elements are required (when true, the elements cannot be NULL).

The following example defines a tags field that is a list of strings for storing multiple tags. element-required: false indicates that the elements in the list can be NULL:

{
  "id": 30,
  "name": "tags",
  "required": false,
  "type": {
    "type": "list",
    "element-id": 31,
    "element": "string",
    "element-required": false
  }
}

map

A map stores a set of key-value pairs. key and value specify the types of the keys and values, and key-id and value-id specify their IDs in the table schema. value-required specifies whether the values are required (when true, the values cannot be NULL). Keys cannot be NULL.

The following example defines an attributes field in which both the keys and values are strings. value-required: false indicates that the values can be NULL:

{
  "id": 40,
  "name": "attributes",
  "required": false,
  "type": {
    "type": "map",
    "key-id": 41,
    "key": "string",
    "value-id": 42,
    "value": "string",
    "value-required": false
  }
}

Complex types can be nested. The type of a struct sub-field, the element of a list, and the key and value of a map can each be a primitive type string or a complex type object. For example, the element of a list can be a struct object.

A field and the elements inside the field can have different nullability. For example, required: false for the tags field allows the entire tag list to be null, whereas element-required: false allows an element in the list to be null. The two attributes control different levels.

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.