CreateTable - Create an Iceberg table in an OSS Table Bucket - Object Storage Service

Permissions

API	Action	Description
CreateTable	oss:CreateTable	Créez une table.
	oss:PutTableData	Écrivez dans le bucket de données. Requis lorsque le paramètre metadata est spécifié.
	oss:PutTableEncryption	Requis lorsque le paramètre encryptionConfiguration est spécifié.

Request syntax

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

Parameters

Parameter	Type	Required	Example	Description
tableBucketARN	string	Yes	acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket	L'ARN du table bucket, spécifié dans l'URI. Format : `acs:osstables:{region}:{uid}:bucket/{bucketName}`.
namespace	string	Yes	my_namespace	Le namespace contenant la table. Spécifié dans l'URI.
name	string	Yes	my_table	Le nom de la table. Il doit être unique au sein du namespace, comporter entre 1 et 255 caractères et contenir uniquement des lettres minuscules, des chiffres et des traits de soulignement (_). Il ne peut pas commencer ni se terminer par un trait de soulignement.
format	string	Yes	ICEBERG	Le format de la table. Seul `ICEBERG` est pris en charge.
encryptionConfiguration	object	No	-	Configuration du chiffrement côté serveur. Si ce paramètre est omis, la table hérite du chiffrement du table bucket. Nœuds enfants : `sseAlgorithm`, `kmsKeyArn`.
sseAlgorithm	string	Yes, if `encryptionConfiguration` is specified.	AES256	L'algorithme de chiffrement. Seul `AES256` est pris en charge. Nœud parent : `encryptionConfiguration`.
kmsKeyArn	string	No	acs:kms:cn-hangzhou:1234567890:key/key-id	L'ARN de la clé KMS. Non pris en charge dans la version actuelle ; doit rester vide. Nœud parent : `encryptionConfiguration`.
metadata	object	No	-	Métadonnées de la table Iceberg, incluant le schéma, les règles de partitionnement, l'ordre d'écriture et les propriétés. Nœud enfant : `iceberg`.
iceberg	object	Yes, if `metadata` is specified.	-	Métadonnées de la table Iceberg. Nœud parent : `metadata`. Nœuds enfants : `schema`, `partitionSpec`, `writeOrder` et `properties`.
schema	object	No	-	Définition du schéma de la table Iceberg. Nœud parent : `iceberg`. Nœud enfant : `fields`.
fields	array	Yes, if `schema` is specified.	-	Définitions des colonnes. Chaque élément décrit une colonne : id : Entier facultatif. Recommandé ; doit être unique au sein du schéma. Référencé par `sourceId` dans `partitionSpec`. name : Obligatoire. Le nom du champ. type : Obligatoire. Le type de données du champ. Les types pris en charge sont répertoriés dans Schema Field Types. required : Booléen facultatif. La valeur par défaut est `false`. Lorsque la valeur est `true`, la colonne rejette les valeurs `NULL`. Nœud parent : `schema`
partitionSpec	object	No	-	Règle de partitionnement de la table. Nœud parent : `iceberg`. Nœuds enfants : specId : Entier facultatif. La valeur par défaut est `0`. fields : Définitions des champs de partition. Détails à la ligne suivante.
fields	array			sourceId : Obligatoire. Doit correspondre à un `id` de champ dans le schéma. transform : Obligatoire. Le type de transformation de partition. Les valeurs prises en charge sont `identity`, `void`, `year`, `month`, `day`, `hour`, `bucket[N]` et `truncate[N]`. fieldId : Entier facultatif. name : Obligatoire. Le nom du champ de partition. Nœud parent : `partitionSpec`
writeOrder	object	No	-	Ordre de tri physique pour les écritures. Nœud parent : `iceberg`. Nœuds enfants : orderId : Entier facultatif. La valeur par défaut est `1` ; doit être au moins égal à `1`. fields : Définitions des champs de tri. Détails à la ligne suivante.
fields	array			sourceId : Obligatoire. Doit correspondre à un `id` de champ dans le schéma. transform : Obligatoire. Le type de transformation de tri. Les valeurs prises en charge sont `identity`, `void`, `year`, `month`, `day`, `hour`, `bucket[N]` et `truncate[N]`. direction : Obligatoire. `asc` (croissant) ou `desc` (décroissant). nullOrder : Obligatoire. `nulls-first` ou `nulls-last`. Nœud parent : `writeOrder`
properties	object	No	-	Propriétés de la table Iceberg au format clé-valeur. Nœud parent : `iceberg`. Propriétés courantes : `format-version` (version du format Iceberg, 1–3), `write.format.default` (format de fichier d'écriture, tel que `parquet`) et `write.target-file-size-bytes` (taille cible du fichier).

Response parameters

Parameter

Type

Example

Description

tableARN

string

acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket/table/table-id

L'ARN de la table créée. Format : acs:osstables:{region}:{uid}:bucket/{bucketName}/table/{tableId}.

versionToken

string

abc123def456

Jeton de version pour le verrouillage optimiste.

Examples

Example 1: Table with a schema

Créez une table avec un schéma à deux champs : id et data.

Request example

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

Example 2: Table with an identity partition

Créez une table avec une partition d'identité sur le champ region.

Request example

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

Example 3: Table with time and bucket partitions

Créez une table avec des partitions day et bucket.

Request example

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

Example 4: Table with a write order

Créez une table qui trie les écritures par ts décroissant, puis par id croissant.

Request example

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

Example 5: Table with specified properties

Créez une table avec le format Iceberg V2, le format d'écriture par défaut et les propriétés de taille de fichier cible.

Request example

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

Example 6: Table with a full configuration

Créez une table avec un schéma, une spécification de partition, un ordre d'écriture, des propriétés et un chiffrement.

Request example

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

Response example

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 field types

Primitive types

Types primitifs pris en charge par le schéma Iceberg :

Type

Minimum version

Description

Example value

boolean

V1

Une valeur booléenne.

true

int

V1

Un entier signé 32 bits.

42

long

V1

Un entier signé 64 bits.

1234567890

float

V1

Un nombre à virgule flottante IEEE 754 32 bits.

3,14

double

V1

Un nombre à virgule flottante IEEE 754 64 bits.

3.141592653589793

decimal(P,S)

V1

Un nombre décimal à précision fixe, où P est la précision (le nombre total de chiffres, jusqu'à 38) et S est l'échelle (le nombre de chiffres à droite de la virgule décimale).

decimal(10,2) → 12345678.90

date

V1

Une date calendaire sans heure ni fuseau horaire.

2025-04-10

time

V1

Une heure de la journée sans date ni fuseau horaire, avec une précision à la microseconde.

14:30:00.000000

timestamp

V1

Un horodatage sans fuseau horaire, avec une précision à la microseconde.

2025-04-10T14:30:00.000000

timestamptz

V1

Un horodatage avec informations de fuseau horaire, stocké en UTC avec une précision à la microseconde.

2025-04-10T14:30:00.000000+00:00

timestamp_ns

V3

Un horodatage sans fuseau horaire, avec une précision à la nanoseconde.

2025-04-10T14:30:00.000000000

timestamptz_ns

V3

Un horodatage avec informations de fuseau horaire, stocké en UTC avec une précision à la nanoseconde.

2025-04-10T14:30:00.000000000+00:00

string

V1

Une chaîne UTF-8 de longueur variable.

hello world

uuid

V1

Un identifiant universel unique de 128 bits.

550e8400-e29b-41d4-a716-446655440000

fixed[L]

V1

Un tableau d'octets de longueur fixe, où L est la longueur en octets.

fixed[16]

binary

V1

Un tableau d'octets de longueur variable.

-

Les types V3 (timestamp_ns, timestamptz_ns, unknown, geometry, geography) nécessitent la version 3 du format Iceberg. OSS Tables utilise par défaut la version V2. Pour utiliser les types V3, définissez « format-version » : « 3 » dans les propriétés de la table.

Compatible source types for transforms

Transform

Format

Description

Compatible source types

identity

Partition d'identité. Partitionne selon la valeur brute du champ source.

Tous les types primitifs

year

Partitionne par année à partir d'une date ou d'un horodatage source.

date, timestamp, timestamptz, timestamp_ns, timestamptz_ns

month

Partitionne par année et mois à partir d'une date ou d'un horodatage source.

date, timestamp, timestamptz, timestamp_ns, timestamptz_ns

day

Partitionne par année, mois et jour à partir d'une date ou d'un horodatage source.

date, timestamp, timestamptz, timestamp_ns, timestamptz_ns

hour

Partitionne par année, mois, jour et heure à partir d'un horodatage source.

timestamp, timestamptz, timestamp_ns, timestamptz_ns

bucket[N]

Hachage en buckets. Partitionne les données en N buckets en hachant la valeur du champ source et en utilisant une opération modulo. N doit être un entier positif.

int, long, decimal, date, time, timestamp, timestamptz, timestamp_ns, timestamptz_ns, string, uuid, fixed[L], binary

truncate[N]

Partition par troncature. Tronque les valeurs entières à une largeur de N ou les valeurs de chaîne à une longueur de N caractères. N doit être un entier positif.

int, long, decimal, string, binary

void

Partition nulle. Mappe toutes les valeurs sur null. Généralement utilisé pour supprimer un champ de partition tout en préservant l'historique d'évolution des partitions.

Tous les types

SDK

CreateTable est disponible dans les SDK suivants :

ossutil CLI

La commande ossutil pour CreateTable est create-table.

Error codes

Error code

HTTP status code

Description

BadRequestException

400

La requête est invalide ou mal formée.

InvalidTableName

400

Nom de table invalide. Un nom de table doit comporter entre 1 et 255 caractères, contenir uniquement des lettres minuscules, des chiffres et des traits de soulignement (_), et ne peut pas commencer ni se terminer par un trait de soulignement.

ForbiddenException

403

L'appelant ne dispose pas des autorisations nécessaires pour effectuer cette requête.

NotFoundException

404

La ressource demandée n'existe pas.

ConflictException

409

La requête entre en conflit avec une opération d'écriture précédente.