CreateTable - Object Storage Service - Alibaba Cloud ドキュメントセンター

指定されたテーブルバケットの名前空間内に Iceberg テーブルを作成するには、CreateTable API を呼び出します。

権限

API	アクション	説明
CreateTable	oss:CreateTable	テーブルを作成するために必要な権限です。
	oss:PutTableData	metadata パラメーターが指定されている場合、データバケットへの書き込みに必要です。
	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	string	はい	acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket	テーブルバケットの ARN です。このパラメーターは URI 内にあり、形式は `acs:osstables:{region}:{uid}:bucket/{bucketName}` です。
namespace	string	はい	my_namespace	テーブルを含む名前空間の名前です。このパラメーターは URI 内にあります。
name	string	はい	my_table	テーブルの名前です。名前空間内で一意である必要があり、長さは 1～255 文字で、小文字、数字、アンダースコア (_) のみを使用し、先頭または末尾にアンダースコアを使用してはいけません。
format	string	はい	ICEBERG	テーブルフォーマットです。`ICEBERG` のみサポートされています。
encryptionConfiguration	object	いいえ	-	テーブルのサーバ側暗号化構成です。このパラメーターを指定しない場合、テーブルはテーブルバケットから暗号化構成を継承します。子ノード：`sseAlgorithm`、`kmsKeyArn`。
sseAlgorithm	string	`encryptionConfiguration` を指定する場合は必須です。	AES256	暗号化アルゴリズムです。`AES256` のみサポートされています。親ノード：`encryptionConfiguration`。
kmsKeyArn	string	いいえ	acs:kms:cn-hangzhou:1234567890:key/key-id	KMS キーの ARN です。現在のバージョンではこのパラメーターはサポートされておらず、空のままにしてください。親ノード：`encryptionConfiguration`。
metadata	object	いいえ	-	テーブルのメタデータ構成です。Iceberg テーブルのスキーマ、パーティショニングルール、書き込み順序、プロパティを含みます。子ノード：`iceberg`。
iceberg	object	`metadata` を指定する場合は必須です。	-	Iceberg テーブルのメタデータ構成です。親ノード：`metadata`。子ノード：`schema`、`partitionSpec`、`writeOrder`、および `properties`。
schema	object	いいえ	-	Iceberg テーブルのスキーマ定義で、テーブルのカラムを記述します。親ノード：`iceberg`。子ノード：`fields`。
fields	array	`schema` を指定する場合は必須です。	-	スキーマのフィールド定義の配列です。各要素はカラムのプロパティを記述します。 id：フィールド ID です。省略可能な整数です。この ID を明示的に指定し、スキーマ内で一意になるようにすることを推奨します。`partitionSpec` 内の `sourceId` はこの ID と一致する必要があります。 name：フィールド名です。このフィールドは必須です。 type：フィールドのデータの型です。このフィールドは必須です。サポートされる型の一覧については、「スキーマフィールドの型」セクションをご参照ください。 required：フィールドが必須かどうかを指定します。省略可能なブール値で、デフォルトは `false` です。`true` に設定すると、そのカラムに `NULL` 値を許可しません。親ノード：`schema`
partitionSpec	object	いいえ	-	テーブルのパーティショニングルールを定義します。親ノード：`iceberg`。以下の子ノードを含みます。 specId：パーティション仕様 ID です。省略可能な整数で、デフォルトは `0` です。 fields：パーティションフィールド定義の配列です。詳細は次の行をご参照ください。
fields	array			sourceId：必須です。スキーマ内のソースフィールドの ID です。この値はスキーマ内のフィールドの `id` と一致する必要があります。 transform：必須です。パーティション変換タイプです。サポートされる値は `identity`、`void`、`year`、`month`、`day`、`hour`、`bucket[N]`、および `truncate[N]` です。 fieldId：省略可能です。パーティションフィールド ID です。整数です。 name：必須です。パーティションフィールドの名前です。親ノード：`partitionSpec`
writeOrder	object	いいえ	-	書き込み時のデータの物理的なソート順序を定義します。親ノード：`iceberg`。以下の子ノードを含みます。 orderId：ソート順序 ID です。省略可能な整数で、デフォルトは `1` であり、`1` 以上である必要があります。 fields：ソートフィールド定義の配列です。詳細は次の行をご参照ください。
fields	array			sourceId：必須です。スキーマ内のソースフィールドの ID です。この値はスキーマ内のフィールドの `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	object	いいえ	-	Iceberg テーブルの構成プロパティで、キーと値のペア形式です。親ノードは iceberg です。一般的なプロパティには、`format-version`（Iceberg フォーマットバージョン。値の範囲は 1～3）、`write.format.default`（書き込みファイル形式。例：`parquet`）、および `write.target-file-size-bytes`（ターゲットファイルサイズ）があります。

レスポンスパラメーター

パラメーター	型	例	説明
tableARN	string	acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket/table/table-id	作成されたテーブルの ARN で、形式は `acs:osstables:{region}:{uid}:bucket/{bucketName}/table/{tableId}` です。
versionToken	string	abc123def456	テーブルのバージョントークンで、楽観的ロックに使用されます。

例

例 1：スキーマを持つテーブル

この例では、id および data の 2 つのフィールドを含む基本的なテーブルを作成します。

リクエスト例

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：ID パーティションを持つテーブル

この例では、region フィールドに対して 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": "region", "type": "string"},
               {"id": 3, "name": "ts", "type": "timestamptz"}
            ]
         },
         "partitionSpec": {
            "specId": 0,
            "fields": [
               {"sourceId": 2, "transform": "identity", "name": "region"}
            ]
         }
      }
   },
   "name": "partitioned_table"
}

例 3：日時およびバケットパーティションを持つテーブル

この例では、day 日時パーティションとバケットパーティションの両方を使用するテーブルを作成します。

リクエスト例

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：書き込み順序を持つテーブル

この例では、ts フィールドを降順、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：プロパティを指定したテーブル

この例では、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：完全な構成を持つテーブル

この例では、スキーマ、パーティション仕様、書き込み順序、テーブルプロパティ、および暗号化構成をすべて含むテーブルを作成します。

リクエスト例

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

スキーマフィールドの型

プリミティブ型

次の表は、Iceberg スキーマでサポートされるプリミティブ型を示しています。

型	最小バージョン	説明	例の値
boolean	V1	ブール値です。	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	固定精度の 10 進数で、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 ビットの汎用一意識別子 (UUID) です。	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 の型を使用するには、テーブルプロパティで "format-version": "3" を指定する必要があります。

変換で互換性のあるソース型

変換	フォーマット	説明	互換性のあるソース型
identity	identity	ID パーティションです。ソースフィールドの生の値でパーティション分割します。	すべてのプリミティブ型
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	void パーティションです。すべての値を null にマッピングします。通常、パーティションフィールドを削除しつつ、パーティション進化履歴を保持するために使用されます。	すべての型

SDK

次の SDK は CreateTable インターフェイスをサポートしています。

ossutil CLI

CreateTable API の ossutil コマンドについては、「create-table」をご参照ください。

エラーコード

エラーコード	HTTP ステータスコード	説明
BadRequestException	400	リクエストが無効または不正な形式です。
InvalidTableName	400	テーブル名が無効です。テーブル名は 1～255 文字で、小文字、数字、アンダースコア (_) のみを使用し、先頭または末尾にアンダースコアを使用してはいけません。
ForbiddenException	403	呼び出し元にこのリクエストを実行する権限がありません。
NotFoundException	404	要求されたリソースが存在しません。
ConflictException	409	このリクエストは以前の書き込み操作と競合しています。