CreateTable

調用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	請求與之前的寫入操作存在衝突。