AI 助理
文档备案控制台
官方文档
输入文档关键字查找
首页

CreateTable

更新时间：
复制为 MD 格式
产品详情
我的收藏

调用CreateTable接口在指定Table Bucket的命名空间下创建一张Iceberg表。

权限说明

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个字符，仅允许小写字母、数字和下划线（_），不能以下划线开头或结尾，在同一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个字符，仅允许小写字母、数字和下划线（_），且不能以下划线开头或结尾。

ForbiddenException

403

调用者无权执行此请求。

NotFoundException

404

请求的资源不存在。

ConflictException

409

请求与之前的写入操作存在冲突。

上一篇：Table下一篇：GetTable