CreateTable - Criar uma tabela Iceberg em um Table Bucket do OSS - Object Storage Service: Central de Documentação do Alibaba Cloud

Permissões

API	Action	Description
CreateTable	oss:CreateTable	Crie uma tabela.
	oss:PutTableData	Grava no bucket de dados. Obrigatório quando o parâmetro metadata é especificado.
	oss:PutTableEncryption	Obrigatório quando o parâmetro encryptionConfiguration é especificado.

Sintaxe da requisição

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

Parâmetros

Parameter	Type	Required	Example	Description
tableBucketARN	string	Yes	acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket	ARN do table bucket, especificado na URI. Formato: `acs:osstables:{region}:{uid}:bucket/{bucketName}`.
namespace	string	Yes	my_namespace	Namespace que contém a tabela. Especificado na URI.
name	string	Yes	my_table	Nome da tabela. Deve ser único no namespace, ter de 1 a 255 caracteres e conter apenas letras minúsculas, dígitos e underscores (_). Não pode começar nem terminar com underscore.
format	string	Yes	ICEBERG	Formato da tabela. Apenas `ICEBERG` é compatível.
encryptionConfiguration	object	No	-	Configuração de criptografia server-side. Se omitida, a tabela herda a criptografia do table bucket. Nós filhos: `sseAlgorithm`, `kmsKeyArn`.
sseAlgorithm	string	Sim, se `encryptionConfiguration` for especificado.	AES256	Algoritmo de criptografia. Apenas `AES256` é compatível. Nó pai: `encryptionConfiguration`.
kmsKeyArn	string	No	acs:kms:cn-hangzhou:1234567890:key/key-id	ARN da chave KMS. Incompatível com a versão atual; deve permanecer vazio. Nó pai: `encryptionConfiguration`.
metadata	object	No	-	Metadados da tabela Iceberg, incluindo schema, regras de particionamento, ordem de gravação e propriedades. Nó filho: `iceberg`.
iceberg	object	Sim, se `metadata` for especificado.	-	Metadados da tabela Iceberg. Nó pai: `metadata`. Nós filhos: `schema`, `partitionSpec`, `writeOrder` e `properties`.
schema	object	No	-	Definição de schema da tabela Iceberg. Nó pai: `iceberg`. Nó filho: `fields`.
fields	array	Sim, se `schema` for especificado.	-	Definições de colunas. Cada elemento descreve uma coluna: id: Inteiro opcional. Recomendado; deve ser único no schema. Referenciado por `sourceId` em `partitionSpec`. name: Obrigatório. Nome do campo. type: Obrigatório. Tipo de dados do campo. Os tipos compatíveis estão listados em Tipos de campos do schema. required: Booleano opcional. O padrão é `false`. Quando `true`, a coluna rejeita valores `NULL`. Nó pai: `schema`
partitionSpec	object	No	-	Regra de particionamento da tabela. Nó pai: `iceberg`. Nós filhos: specId: Inteiro opcional. O padrão é `0`. fields: Definições de campos de partição. Detalhes na próxima linha.
fields	array			sourceId: Obrigatório. Deve corresponder a um `id` de campo no schema. transform: Obrigatório. Tipo de transformação de partição. Valores compatíveis: `identity`, `void`, `year`, `month`, `day`, `hour`, `bucket[N]` e `truncate[N]`. fieldId: Inteiro opcional. name: Obrigatório. Nome do campo de partição. Nó pai: `partitionSpec`
writeOrder	object	No	-	Ordem de classificação física para gravações. Nó pai: `iceberg`. Nós filhos: orderId: Inteiro opcional. O padrão é `1`; deve ser no mínimo `1`. fields: Definições de campos de ordenação. Detalhes na próxima linha.
fields	array			sourceId: Obrigatório. Deve corresponder a um `id` de campo no schema. transform: Obrigatório. Tipo de transformação de ordenação. Valores compatíveis: `identity`, `void`, `year`, `month`, `day`, `hour`, `bucket[N]` e `truncate[N]`. direction: Obrigatório. `asc` (ascendente) ou `desc` (descendente). nullOrder: Obrigatório. `nulls-first` ou `nulls-last`. Nó pai: `writeOrder`
properties	object	No	-	Propriedades da tabela Iceberg no formato chave-valor. Nó pai: `iceberg`. Propriedades comuns: `format-version` (versão do formato Iceberg, 1–3), `write.format.default` (formato de arquivo de gravação, como `parquet`) e `write.target-file-size-bytes` (tamanho alvo do arquivo).

Parâmetros de resposta

Parameter	Type	Example	Description
tableARN	string	acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket/table/table-id	ARN da tabela criada. Formato: acs:osstables:{region}:{uid}:bucket/{bucketName}/table/{tableId}.
versionToken	string	abc123def456	Token de versão para bloqueio otimista.

Exemplos

Exemplo 1: Tabela com schema

Crie uma tabela com schema de dois campos: id e data.

Exemplo de requisição

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

Exemplo 2: Tabela com partição identity

Crie uma tabela com partição identity no campo region.

Exemplo de requisição

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

Exemplo 3: Tabela com partições de tempo e bucket

Crie uma tabela com partições day e bucket.

Exemplo de requisição

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

Exemplo 4: Tabela com ordem de gravação

Crie uma tabela que classifica as gravações por ts em ordem decrescente e, em seguida, por id em ordem crescente.

Exemplo de requisição

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

Exemplo 5: Tabela com propriedades especificadas

Crie uma tabela com formato Iceberg V2, formato de gravação padrão e propriedades de tamanho alvo de arquivo.

Exemplo de requisição

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

Exemplo 6: Tabela com configuração completa

Crie uma tabela com schema, especificação de partição, ordem de gravação, propriedades e criptografia.

Exemplo de requisição

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

Exemplo de resposta

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

Tipos de campos do schema

Tipos primitivos

Tipos primitivos compatíveis com o schema Iceberg:

Type	Minimum version	Description	Example value
boolean	V1	Valor booleano.	true
int	V1	Inteiro assinado de 32 bits.	42
long	V1	Inteiro assinado de 64 bits.	1234567890
float	V1	Número de ponto flutuante IEEE 754 de 32 bits.	3.14
double	V1	Número de ponto flutuante IEEE 754 de 64 bits.	3.141592653589793
decimal(P,S)	V1	Número decimal de precisão fixa, onde P é a precisão (total de dígitos, até 38) e S é a escala (dígitos à direita do ponto decimal).	decimal(10,2) → 12345678.90
date	V1	Data de calendário sem hora ou fuso horário.	2025-04-10
time	V1	Hora do dia sem data ou fuso horário, com precisão de microssegundos.	14:30:00.000000
timestamp	V1	Timestamp sem fuso horário, com precisão de microssegundos.	2025-04-10T14:30:00.000000
timestamptz	V1	Timestamp com informações de fuso horário, armazenado em UTC com precisão de microssegundos.	2025-04-10T14:30:00.000000+00:00
timestamp_ns	V3	Timestamp sem fuso horário, com precisão de nanossegundos.	2025-04-10T14:30:00.000000000
timestamptz_ns	V3	Timestamp com informações de fuso horário, armazenado em UTC com precisão de nanossegundos.	2025-04-10T14:30:00.000000000+00:00
string	V1	String UTF-8 de comprimento variável.	hello world
uuid	V1	Identificador universalmente único de 128 bits.	550e8400-e29b-41d4-a716-446655440000
fixed[L]	V1	Array de bytes de comprimento fixo, onde L é o comprimento em bytes.	fixed[16]
binary	V1	Array de bytes de comprimento variável.	-

Os tipos V3 (timestamp_ns, timestamptz_ns, unknown, geometry, geography) exigem o format-version 3 do Iceberg. O OSS Tables usa V2 como padrão. Para usar tipos V3, defina "format-version": "3" nas propriedades da tabela.

Tipos de origem compatíveis para transformações

Transform	Format	Description	Compatible source types
identity	identity	Partição identidade. Particiona pelo valor bruto do campo de origem.	Todos os tipos primitivos
year	year	Particiona pelo ano de uma data ou timestamp de origem.	date, timestamp, timestamptz, timestamp_ns, timestamptz_ns
month	month	Particiona pelo ano e mês de uma data ou timestamp de origem.	date, timestamp, timestamptz, timestamp_ns, timestamptz_ns
day	day	Particiona pelo ano, mês e dia de uma data ou timestamp de origem.	date, timestamp, timestamptz, timestamp_ns, timestamptz_ns
hour	hour	Particiona pelo ano, mês, dia e hora de um timestamp de origem.	timestamp, timestamptz, timestamp_ns, timestamptz_ns
bucket[N]	bucket[N]	Bucketing por hash. Particiona os dados em N buckets aplicando hash ao valor do campo de origem e usando uma operação de módulo. N deve ser um inteiro positivo.	int, long, decimal, date, time, timestamp, timestamptz, timestamp_ns, timestamptz_ns, string, uuid, fixed[L], binary
truncate[N]	truncate[N]	Partição por truncamento. Trunca valores inteiros para uma largura de N ou valores de string para um comprimento de N caracteres. N deve ser um inteiro positivo.	int, long, decimal, string, binary
void	void	Partição nula. Mapeia todos os valores para null. Geralmente usado para remover um campo de partição preservando o histórico de evolução da partição.	Todos os tipos

SDK

CreateTable está disponível nestes SDKs:

ossutil CLI

O comando ossutil para CreateTable é create-table.

Códigos de erro

Error code	HTTP status code	Description
BadRequestException	400	A requisição é inválida ou malformada.
InvalidTableName	400	Nome de tabela inválido. O nome deve ter de 1 a 255 caracteres, conter apenas letras minúsculas, dígitos e underscores (_), e não pode começar nem terminar com underscore.
ForbiddenException	403	O chamador não tem permissão para fazer esta requisição.
NotFoundException	404	O recurso solicitado não existe.
ConflictException	409	A requisição entra em conflito com uma operação de gravação anterior.