CreateTable-对象存储(OSS)-阿里云帮助中心

注意事项

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，格式为`acs:osstables:{region}:{uid}:bucket/{bucketName}`，位于URI中。
namespace	字符串	是	my_namespace	表所在的命名空间名称，位于URI中。
name	字符串	是	my_table	表名称。长度为1~255个字符，仅允许小写字母、数字和下划线（_），不能以下划线开头或结尾，不能以oss、acs、aliyun、alibaba、aws为前缀，在同一Namespace下必须唯一。
format	字符串	是	ICEBERG	表格式。目前仅支持`ICEBERG`。
encryptionConfiguration	容器	否	-	表的服务端加密配置。如果不指定，默认继承Table Bucket级别的加密配置。子节点：sseAlgorithm、kmsKeyArn。
sseAlgorithm	字符串	是（当指定encryptionConfiguration时）	AES256	加密算法。目前仅支持`AES256`。父节点：encryptionConfiguration。
kmsKeyArn	字符串	否	acs:kms:cn-hangzhou:1234567890:key/key-id	KMS密钥ARN。当前版本暂不支持，请置空。父节点：encryptionConfiguration。
metadata	容器	否	-	表元数据配置，包含Iceberg表的结构定义、分区规则、写入排序规则和属性配置。子节点：iceberg。
iceberg	容器	是（当指定metadata时）	-	Iceberg格式的元数据配置。父节点：metadata。子节点：schema、partitionSpec、writeOrder、properties。
schema	容器	否	-	Iceberg表的Schema定义，描述表的列信息。父节点：iceberg。子节点：fields。
fields	数组	是（当指定schema时）	-	Schema字段定义列表，每个元素描述一个列的属性： id：字段ID，整数类型，选填。建议显式指定且在Schema内唯一；partitionSpec 的 sourceId 引用时需匹配该值。 name：字段名称，必填。 type：字段数据类型，必填。支持的类型详见本文Schema字段类型说明章节。 required：是否为必填字段，布尔类型，选填，默认为false。设为true时该列不允许NULL值。父节点：schema
partitionSpec	容器	否	-	分区规格定义，指定表的数据分区规则。父节点：iceberg。包含以下子参数： specId：分区规格ID，整数类型，默认为0，选填。 fields：分区字段列表，数组类型，详见下一行。
fields	数组			sourceId：引用schema中字段的id编号，必须与某个schema字段的id值匹配，必填。 transform：分区转换类型，必填。支持的值：identity、void、year、month、day、hour、bucket[N]、truncate[N]。 fieldId：分区字段ID，整数类型，选填。 name：分区字段名称，必填。父节点：partitionSpec
writeOrder	容器	否	-	写入排序规则定义，指定数据写入时的物理排序方式。父节点：iceberg。包含以下子参数： orderId：排序规则ID，整数类型，默认为1，必须大于等于1，选填。 fields：排序字段列表，数组类型，详见下一行。
fields	数组			sourceId：引用schema中字段的id编号，必须与某个schema字段的id值匹配，必填。 transform：排序转换类型，必填。支持的值：identity、void、year、month、day、hour、bucket[N]、truncate[N]。 direction：排序方向，取值为`asc`（升序）或`desc`（降序）。必填。 nullOrder：NULL值排序位置，取值为`nulls-first`（NULL排在前面）或`nulls-last`（NULL排在后面）。必填。父节点：writeOrder
properties	容器	否	-	Iceberg表的配置属性，键值对格式。父节点：iceberg。常用属性包括：`format-version`（Iceberg 格式版本，取值范围 1-3）、`write.format.default`（写入文件格式，如 `parquet`）、`write.target-file-size-bytes`（目标文件大小）。

响应参数

名称	数据类型	示例值	描述
tableARN	字符串	acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket/table/table-id	创建的表的ARN，格式为`acs:osstables:{region}:{uid}:bucket/{bucketName}/table/{tableId}`。
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"
}

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"。

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	请求与之前的写入操作存在冲突。