CreateTable - Create an Iceberg table in an OSS Table Bucket - Object Storage Service: Central de Documentação do Alibaba Cloud

Notas de uso

O nome da tabela deve ter de 1 a 255 caracteres e conter apenas letras minúsculas, dígitos e underscores (_). Não pode começar ou terminar com underscore, nem iniciar com oss, acs, aliyun, alibaba ou aws.
Antes de criar a tabela, verifique se o Table Bucket e o namespace de destino existem.

Permissões

API	Action	Description
CreateTable	oss:CreateTable	Cria 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 solicitação

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

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 ou terminar com underscore, nem iniciar com oss, acs, aliyun, alibaba ou aws.
format	string	Yes	ICEBERG	Formato da tabela. Apenas `ICEBERG` é compatível.
encryptionConfiguration	object	No	-	Configuração de criptografia no lado do servidor. 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. Não compatível na 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 do 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 dos 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. Os valores compatíveis são `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 pelo menos `1`. fields: Definições dos 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. Os valores compatíveis são `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 um schema

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

Exemplo de solicitação

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

Exemplo 2: Tabela com uma partição de identidade

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

Exemplo de solicitação

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

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

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

Exemplo de solicitação

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

Exemplo 4: Tabela com uma ordem de gravação

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

Exemplo de solicitação

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

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 solicitação

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

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 solicitação

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

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 com sinal de 32 bits.	42
long	V1	Inteiro com sinal 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 (número total de dígitos, até 38) e S é a escala (número de 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 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 source compatíveis para transformações

Transform	Format	Description	Compatible source types
identity	identity	Partição de identidade. Particiona pelo valor bruto do campo de source.	Todos os tipos primitivos
year	year	Particiona pelo ano de uma data ou timestamp de source.	date, timestamp, timestamptz, timestamp_ns, timestamptz_ns
month	month	Particiona pelo ano e mês de uma data ou timestamp de source.	date, timestamp, timestamptz, timestamp_ns, timestamptz_ns
day	day	Particiona pelo ano, mês e dia de uma data ou timestamp de source.	date, timestamp, timestamptz, timestamp_ns, timestamptz_ns
hour	hour	Particiona pelo ano, mês, dia e hora de um timestamp de source.	timestamp, timestamptz, timestamp_ns, timestamptz_ns
bucket[N]	bucket[N]	Agrupamento por hash. Particiona os dados em N buckets aplicando hash ao valor do campo de source 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 de 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 solicitaçã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 (_), não pode começar ou terminar com underscore e não pode iniciar com oss, acs, aliyun, alibaba ou aws.
ForbiddenException	403	O chamador não tem permissão para fazer esta solicitação.
NotFoundException	404	O recurso solicitado não existe.
ConflictException	409	A solicitação entra em conflito com uma operação de gravação anterior.