调用CreateTable接口在指定Table Bucket的命名空间下创建一张Iceberg表。
注意事项
该接口仅支持 Iceberg 表，不支持 Lance 表。如需创建 Lance 表，请通过 Lance REST Namespace API 或 Lance 生态（Spark、Trino 等计算引擎）完成。
Table名称长度为1~255个字符，只允许小写字母、数字和下划线（_），不能以下划线开头或结尾，不能以oss、acs、aliyun、alibaba、aws为前缀。
创建Table前，需要确保目标Table Bucket和Namespace已存在。
权限说明
API | Action | 说明 |
CreateTable | oss:CreateTable | 创建表基础权限。 |
oss:PutTableData | 如果指定了metadata参数，需要写databucket，必须有此权限。 | |
oss:PutTableEncryption | 如果指定了encryptionConfiguration，必须有此权限。 |
请求语法
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"
}
}
}
}请求参数
名称 | 数据类型 | 是否必选 | 示例值 | 描述 |
tableBucketARN | 字符串 | 是 | acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket | Table Bucket的ARN，格式为 |
namespace | 字符串 | 是 | my_namespace | 表所在的命名空间名称，位于URI中。 |
name | 字符串 | 是 | my_table | 表名称。长度为1~255个字符，仅允许小写字母、数字和下划线（_），不能以下划线开头或结尾，不能以oss、acs、aliyun、alibaba、aws为前缀，在同一Namespace下必须唯一。 |
format | 字符串 | 是 | ICEBERG | 表格式。目前仅支持 |
encryptionConfiguration | 容器 | 否 | - | 表的服务端加密配置。如果不指定，默认继承Table Bucket级别的加密配置。子节点：sseAlgorithm、kmsKeyArn。 |
sseAlgorithm | 字符串 | 是（当指定encryptionConfiguration时） | AES256 | 加密算法。目前仅支持 |
kmsKeyArn | 字符串 | 否 | acs:kms:cn-hangzhou:1234567890:key/key-id | KMS密钥ARN。当前版本暂不支持，请置空。父节点：encryptionConfiguration。 |
metadata | 容器 | 否 | - | 表元数据配置，包含Iceberg表的结构定义、分区规则、写入排序规则和属性配置。子节点：iceberg。 |
iceberg | 容器 | 是（当指定metadata时） | - | Iceberg格式的元数据配置。父节点：metadata。子节点：schema、schemaV2、partitionSpec、writeOrder、properties。 |
schema | 容器 | 否 | - | Iceberg表的Schema定义，描述表的列信息。父节点：iceberg。子节点：fields。 |
fields | 数组 | 是（当指定schema时） | - | Schema字段定义列表，每个元素描述一个列的属性：
父节点：schema |
schemaV2 | 容器 | 否 | - | Iceberg表的Schema V2定义，描述表的字段信息。除基础类型外，schemaV2还支持描述struct（结构体）、list（列表）、map（键值映射）类型及其嵌套组合。父节点：iceberg。子节点：type、fields、schema-id、identifier-field-ids。同一次请求中，schema和schemaV2只能选择一个；已有的schema请求可以继续使用。 |
type | 字符串 | 是（当指定schemaV2时） | struct | schemaV2最外层的类型，固定为struct，表示整张表由一组字段组成。父节点：schemaV2。 |
fields | 数组 | 是（当指定schemaV2时） | - | Schema V2字段定义列表，每个元素描述一个字段：
父节点：schemaV2 |
schema-id | 整数 | 否 | 0 | 这一份表结构的标识，选填。通常可以省略；建表后以服务端生成的表元数据为准。父节点：schemaV2。 |
identifier-field-ids | 数组 | 否 | [10] | 指定用于标识记录的字段编号列表，元素为字段id（整数），选填。本身不提供自动去重或唯一性校验。父节点：schemaV2。 |
partitionSpec | 容器 | 否 | - | 分区规格定义，指定表的数据分区规则。父节点：iceberg。包含以下子参数：
|
fields | 数组 |
父节点：partitionSpec | ||
writeOrder | 容器 | 否 | - | 写入排序规则定义，指定数据写入时的物理排序方式。父节点：iceberg。包含以下子参数：
|
fields | 数组 |
父节点：writeOrder | ||
properties | 容器 | 否 | - | Iceberg表的配置属性，键值对格式。父节点：iceberg。常用属性包括： |
响应参数
名称 | 数据类型 | 示例值 | 描述 |
tableARN | 字符串 | acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket/table/table-id | 创建的表的ARN，格式为 |
versionToken | 字符串 | abc123def456 | 表的版本token，用于后续乐观锁控制。 |
使用示例
示例1：带schema建表
创建一张仅包含schema定义的基础表，包含id和data两个字段。
请求示例
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"}
]
}
}
}
}示例2：带分区规格建表（identity分区）
创建一张按category字段进行identity分区的表。
请求示例
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"
}
示例3：带时间分区和bucket分区建表
创建一张同时使用day时间分区和bucket哈希分区的表。
请求示例
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"
}
示例4：带写入排序规则建表
创建一张指定写入排序规则的表，按timestamp升序、id降序排序。
请求示例
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"
}
示例5：指定properties建表
创建一张指定表属性（properties）的表，指定Iceberg格式版本为V2，并设置写入文件格式和目标文件大小。
请求示例
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"
}
}
}
}示例6：创建完整配置的表
创建一张包含完整配置的表：schema定义、分区规则、写入排序规则、表属性和加密配置。
请求示例
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"
}
返回示例
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"
}示例7：使用schemaV2建表（包含复杂类型）
创建一张包含struct、list、map复杂类型字段的订单表：order_id为订单号（long），customer为客户信息（struct，包含name和level两个子字段），tags为标签列表（list，元素为字符串），attributes为附加属性（map，键和值均为字符串）。该请求已通过实际建表验证。
请求示例
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字段类型说明
原始类型
以下为Iceberg Schema支持的原始数据类型：
类型 | 最低版本 | 说明 | 示例值 |
boolean | V1 | 布尔值，true或false。 | true |
int | V1 | 32位有符号整数。 | 42 |
long | V1 | 64位有符号整数。 | 1234567890 |
float | V1 | 32位IEEE 754浮点数。 | 3.14 |
double | V1 | 64位IEEE 754浮点数。 | 3.141592653589793 |
decimal(P,S) | V1 | 固定精度的十进制数。P为精度（总位数，最大38），S为标度（小数位数）。 | decimal(10,2) → 12345678.90 |
date | V1 | 日历日期，不含时间和时区。 | 2025-04-10 |
time | V1 | 时间，不含日期和时区，微秒精度。 | 14:30:00.000000 |
timestamp | V1 | 不带时区的时间戳，微秒精度。 | 2025-04-10T14:30:00.000000 |
timestamptz | V1 | 带时区的时间戳，微秒精度，存储为UTC。 | 2025-04-10T14:30:00.000000+00:00 |
timestamp_ns | V3 | 不带时区的时间戳，纳秒精度。 | 2025-04-10T14:30:00.000000000 |
timestamptz_ns | V3 | 带时区的时间戳，纳秒精度，存储为UTC。 | 2025-04-10T14:30:00.000000000+00:00 |
string | V1 | 任意长度的UTF-8字符串。 | hello world |
uuid | V1 | 通用唯一标识符，128位。 | 550e8400-e29b-41d4-a716-446655440000 |
fixed[L] | V1 | 固定长度的字节数组，L为字节长度。 | fixed[16] |
binary | V1 | 任意长度的字节数组。 | - |
版本约束说明：标注为V3的类型（timestamp_ns、timestamptz_ns、unknown、geometry、geography）仅在Iceberg format-version为3时支持。当前OSS Tables默认使用V2，如需使用V3类型，需在properties中指定"format-version": "3"。
复杂类型（适用于 schemaV2）
schemaV2中，字段的type可以是基础类型名称字符串，例如“long”、“string”，也可以是描述复杂类型的JSON对象。复杂类型包括struct、list和map。
以下示例均为单个字段的定义，可放入metadata.iceberg.schemaV2.fields数组中。完整请求的写法参见本文使用示例章节的示例7。
struct（结构体）
struct用于把多个有固定名称的子字段放在一起。通过fields数组定义子字段，每个子字段仍包含id、name、type等属性。
下面定义一个customer字段，其中包含name（姓名）和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（列表）
list用于存放同一种类型的多个元素。element指定元素类型，element-id指定元素在表结构中的编号，element-required指定元素是否必填（true表示元素不允许为NULL）。
下面定义一个字符串列表tags，可用于存放多个标签；element-required: false表示列表中的元素允许为NULL：
{
"id": 30,
"name": "tags",
"required": false,
"type": {
"type": "list",
"element-id": 31,
"element": "string",
"element-required": false
}
}map（键值映射）
map用于存放一组键值对。key和value分别指定键和值的类型，key-id和value-id分别指定两者在表结构中的编号。value-required指定值是否必填（true表示值不允许为NULL）；键不允许为NULL。
下面定义一个attributes字段，其键和值都是字符串；value-required: false表示值允许为NULL：
{
"id": 40,
"name": "attributes",
"required": false,
"type": {
"type": "map",
"key-id": 41,
"key": "string",
"value-id": 42,
"value": "string",
"value-required": false
}
}复杂类型支持继续嵌套：struct子字段的type、list的element、map的key和value，均可使用基础类型字符串或复杂类型对象。例如，list的element可以是一个struct对象。
字段本身和它内部的元素可以有不同的可空性。例如，tags的required: false允许整个标签列表为NULL；element-required: false则允许列表中的某个元素为NULL。这两个属性分别控制不同层级。
Transformer支持的源字段类型
Transform | 格式 | 说明 | 兼容的源字段类型 |
identity | identity | 原值分区，直接使用源字段值作为分区值。 | 所有原始类型 |
year | year | 提取年份作为分区值。 | date、timestamp、timestamptz、timestamp_ns、timestamptz_ns |
month | month | 提取年月作为分区值。 | date、timestamp、timestamptz、timestamp_ns、timestamptz_ns |
day | day | 提取年月日作为分区值。 | date、timestamp、timestamptz、timestamp_ns、timestamptz_ns |
hour | hour | 提取年月日时作为分区值。 | timestamp、timestamptz、timestamp_ns、timestamptz_ns |
bucket[N] | bucket[N] | 哈希分桶，将源字段值哈希后取模分为N个桶。N为正整数。 | int、long、decimal、date、time、timestamp、timestamptz、timestamp_ns、timestamptz_ns、string、uuid、fixed[L]、binary |
truncate[N] | truncate[N] | 截断分区。对整数按宽度N截断，对字符串取前N个字符。N为正整数。 | int、long、decimal、string、binary |
void | void | 空分区，所有值映射为null。常用于删除分区字段但保留分区演进历史。 | 所有类型 |
SDK
CreateTable接口所对应的各语言SDK如下：
命令行工具ossutil
CreateTable接口所对应的ossutil命令，请参见create-table。
错误码
错误码 | HTTP状态码 | 描述 |
BadRequestException | 400 | 请求无效或格式错误。 |
InvalidTableName | 400 | 表名不合法。表名长度必须为1~255个字符，仅允许小写字母、数字和下划线（_），不能以下划线开头或结尾，且不能以oss、acs、aliyun、alibaba、aws为前缀。 |
ForbiddenException | 403 | 调用者无权执行此请求。 |
NotFoundException | 404 | 请求的资源不存在。 |
ConflictException | 409 | 请求与之前的写入操作存在冲突。 |