Ingestion-time partitioned tables - MaxCompute: Central de Documentação do Alibaba Cloud

Tabelas particionadas por tempo de ingestão atribuem automaticamente as linhas recebidas a partições com base no momento da gravação no MaxCompute. Em vez de especificar manualmente uma chave de partição, declare a pseudocoluna _partitiontime e a expressão TRUNC_TIME. O MaxCompute captura o timestamp de gravação, trunca-o para a granularidade escolhida (hora, dia, mês ou ano) e gera a coluna de chave de partição automaticamente.

Por exemplo, ao criar uma tabela particionada por hora e gravar linhas nos seguintes horários:

Hora da ingestão de dados (UTC+8)	_partitiontime gerado (TIMESTAMP)	Chave de partição gerada (STRING)
2025-06-18 17:22:00	2025-06-18 17:00:00	2025-06-18 09:00:00
2025-06-18 17:40:00	2025-06-18 17:00:00	2025-06-18 09:00:00
2025-06-18 18:31:00	2025-06-18 18:00:00	2025-06-18 10:00:00

A função TRUNC_TIME converte o timestamp local para UTC antes do truncamento; portanto, a chave de partição STRING reflete o horário UTC. Consulte Comportamento do fuso horário para obter detalhes.

Para obter uma visão geral de todos os tipos de tabelas particionadas no MaxCompute, consulte Visão geral de tabelas particionadas.

Limitações

O sistema oferece suporte apenas a uma única coluna de partição. Não há suporte para particionamento multinível.
A coluna de partição sempre possui o tipo de dados STRING. Essa configuração é imutável.
O particionamento automático baseado no tempo de ingestão funciona apenas para gravações via MaxCompute SQL. Outros métodos de ingestão, como o conector Flink, não têm suporte.
Somente a função TRUNC_TIME tem suporte na expressão AUTO PARTITIONED BY.

Comportamento do fuso horário

A função TRUNC_TIME converte o timestamp de ingestão do fuso horário local do projeto para UTC antes de truncá-lo. O valor da chave de partição STRING permanece sempre em UTC, mesmo que o projeto seja executado em um fuso horário diferente.

Importante

Defina o fuso horário do projeto como UTC para evitar valores inesperados na chave de partição. Se o projeto utilizar um fuso horário diferente de UTC (por exemplo, Asia/Shanghai, UTC+8), o valor UTC truncado diferirá da hora local conforme o deslocamento do UTC. Os exemplos de consulta neste tópico usam Asia/Shanghai para ilustrar esse efeito. Por isso, _partitiontime e a coluna de chave de partição apresentam uma diferença de 8 horas nos resultados.

SET odps.sql.timezone=UTC;

Crie uma tabela particionada por tempo de ingestão

Sintaxe

CREATE [OR REPLACE] TABLE [IF NOT EXISTS] <table_name>
  (_partitiontime <data_type>, <col_name> <data_type> [, ...])
  [COMMENT <table_comment>]
AUTO PARTITIONED BY (<auto_partition_expression> [AS <auto_partition_column_name>])
TBLPROPERTIES('ingestion_time_partition'='true');

Parâmetros

Parâmetro	Obrigatório	Descrição
`table_name`	Sim	Nome da tabela a ser criada.
`_partitiontime`	Sim	Pseudocoluna que armazena o timestamp de ingestão truncado. O nome da coluna é fixo e imutável. Tipos de dados suportados: `TIMESTAMP` e `TIMESTAMP_NTZ`.
`col_name`	Sim	Nome de uma coluna regular.
`data_type`	Sim	Tipo de dados da coluna.
`table_comment`	Não	Comentário para a tabela.
`TBLPROPERTIES('ingestion_time_partition'='true')`	Sim	Marca a tabela como particionada por tempo de ingestão.
`auto_partition_expression`	Sim	Expressão que deriva a chave de partição. Apenas TRUNC_TIME tem suporte. O MaxCompute captura automaticamente o tempo de ingestão e o passa para `TRUNC_TIME` para gerar o valor da chave de partição.
`auto_partition_column_name`	Não	Nome da coluna de partição gerada. O padrão é `_pt_col_0_`. Se esse nome já estiver em uso, o sistema usará `_pt_col_1_`, `_pt_col_2_` e assim por diante. A coluna gerada possui o tipo de dados STRING e não permite modificação direta.

Exemplos

Exemplo 1: Particionamento por hora

A instrução a seguir cria a tabela ingestion_sale_detail_hourly. Durante a gravação de dados, o MaxCompute trunca o tempo de ingestão para a hora, preenche _partitiontime e armazena o resultado em UTC na coluna de partição sale_time.

-- The system captures the write time, truncates it to the hour,
-- and stores the UTC value as the sale_time partition key.
CREATE TABLE IF NOT EXISTS ingestion_sale_detail_hourly (
  shop_name    STRING,
  total_price  DOUBLE,
  _partitiontime TIMESTAMP
)
AUTO PARTITIONED BY (TRUNC_TIME(_partitiontime, 'hour') AS sale_time)
TBLPROPERTIES('ingestion_time_partition'='true');

Execute DESC ingestion_sale_detail_hourly; para inspecionar a tabela. A saída mostra sale_time como uma coluna de partição STRING:

+------------------------------------------------------------------------------------+
| Owner:                    ALIYUN$test****                                          |
| Project:                   xxxxxxx                                                 |
| Schema:                    default                                                 |
| TableComment:                                                                      |
+------------------------------------------------------------------------------------+
| CreateTime:               2025-06-16 14:59:40                                      |
| LastDDLTime:              2025-06-16 14:59:40                                      |
| LastModifiedTime:         2025-06-16 14:59:40                                      |
+------------------------------------------------------------------------------------+
| InternalTable: YES      | Size: 0                                                  |
+------------------------------------------------------------------------------------+
| Native Columns:                                                                    |
+------------------------------------------------------------------------------------+
| Field           | Type       | Label | Comment                                     |
+------------------------------------------------------------------------------------+
| shop_name       | string     |       |                                             |
| total_price     | double     |       |                                             |
| _partitiontime  | timestamp  |       |                                             |
+------------------------------------------------------------------------------------+
| Partition Columns:                                                                 |
+------------------------------------------------------------------------------------+
| sale_time       | string     |                                                     |
+------------------------------------------------------------------------------------+

Exemplo 2: Particionamento por dia

Quando a granularidade é day, o MaxCompute também gera a pseudocoluna _partitiondate do tipo DATE junto com _partitiontime.

CREATE TABLE IF NOT EXISTS ingestion_sale_detail_daily (
  shop_name    STRING,
  total_price  DOUBLE,
  _partitiontime TIMESTAMP
)
AUTO PARTITIONED BY (TRUNC_TIME(_partitiontime, 'day') AS sale_date)
TBLPROPERTIES('ingestion_time_partition'='true');

Para visualizar _partitiondate , inclua-a explicitamente na consulta: SELECT *, _partitiondate FROM ingestion_sale_detail_daily; Para inspecionar a lógica de geração de partição, use a instrução SHOW CREATE TABLE .

Gravar dados em uma tabela particionada por tempo de ingestão

Os exemplos abaixo gravam nas tabelas ingestion_sale_detail_hourly e ingestion_sale_detail_daily criadas em Crie uma tabela particionada por tempo de ingestão.

Se você omitir _partitiontime da instrução INSERT, o MaxCompute usará a hora atual de gravação. Caso forneça um valor, trunque-o para a mesma granularidade definida na instrução CREATE TABLE.

Exemplo 1: Permitir que o sistema atribua a partição

Omita _partitiontime. O MaxCompute usa o timestamp de gravação atual e o trunca para a hora.

INSERT INTO ingestion_sale_detail_hourly (shop_name, total_price)
VALUES
  ('shanghai_shop', 10001.1),
  ('chongqin_shop', 20002.2),
  ('hangzhou_shop', 30003.3),
  ('shenzhen_shop', 40004.4);

Exemplo 2: Especifique o tempo de ingestão explicitamente

Trunque o valor para a granularidade declarada (horária, neste caso).

Válido — 2025-06-15 14:00:00 está em um limite de hora exata:

INSERT INTO ingestion_sale_detail_hourly (shop_name, total_price, _partitiontime)
VALUES
  ('beijing_shop', 50005.5, TIMESTAMP '2025-06-15 14:00:00'),
  ('chengdu_shop', 60006.6, TIMESTAMP '2025-06-14 05:00:00');

Inválido — 2025-06-15 14:30:00 não está em um limite de hora exata:

INSERT INTO ingestion_sale_detail_hourly (shop_name, total_price, _partitiontime)
VALUES ('beijing_shop', 50005.5, TIMESTAMP '2025-06-15 14:30:00');

Erro retornado:

FAILED: ODPS-0130071:[0,0] Semantic analysis exception - physical plan generation failed:
SQL Runtime Unretryable Error: ODPS-0121095:Invalid argument - illegal ingestion time: 2025-06-15 14:30:00

Exemplo 3: Tabela particionada diariamente — especifique apenas _partitiontime

Para tabelas particionadas diariamente, forneça apenas _partitiontime. Não é possível especificar _partitiondate em uma instrução INSERT.

Válido — 2025-06-18 00:00:00 é o início do dia:

INSERT INTO ingestion_sale_detail_daily (shop_name, total_price, _partitiontime)
VALUES ('beijing_shop', 50005.5, TIMESTAMP '2025-06-18 00:00:00');

Inválido — 2025-06-18 14:00:00 não é o início do dia:

INSERT INTO ingestion_sale_detail_daily (shop_name, total_price, _partitiontime)
VALUES ('beijing_shop', 50005.5, TIMESTAMP '2025-06-18 14:00:00');

Erro retornado:

FAILED: ODPS-0130071:[0,0] Semantic analysis exception - physical plan generation failed:
SQL Runtime Unretryable Error: ODPS-0121095:Invalid argument - illegal ingestion time: 2025-06-18 14:00:00

Inválido — especifique _partitiondate diretamente:

INSERT INTO ingestion_sale_detail_daily (shop_name, total_price, _partitiondate)
VALUES ('beijing_shop', 50005.5, DATE '2025-06-15');

Erro retornado:

FAILED: ODPS-0130071:[1,64] Semantic analysis exception - column _partitiondate cannot be resolved;
Did you mean _partitiontime ?

Consultar uma tabela particionada por tempo de ingestão

Os exemplos abaixo consultam as tabelas criadas em Crie uma tabela particionada por tempo de ingestão.

Considere dois comportamentos importantes:

SELECT * not retorna _partitiontime, _partitiondate nem a coluna de partição gerada. Especifique-as explicitamente para incluí-las no resultado.

Use _partitiontime nas cláusulas WHERE para acionar a eliminação de partições (partition pruning). As expressões de filtro a seguir acionam a eliminação de partições em tabelas particionadas por tempo de ingestão. Para obter a lista completa de expressões de eliminação suportadas, consulte Tabelas particionadas automaticamente com base em funções de tempo.

Granularidade	Exemplo de filtro
Hora	`WHERE _partitiontime >= TIMESTAMP '2025-06-18 07:00:00' AND _partitiontime < TIMESTAMP '2025-06-18 08:00:00'`
Mês	`WHERE _partitiontime >= TIMESTAMP '2025-06-01 00:00:00' AND _partitiontime < TIMESTAMP '2025-07-01 00:00:00'`
Ano	`WHERE _partitiontime >= TIMESTAMP '2025-01-01 00:00:00' AND _partitiontime < TIMESTAMP '2026-01-01 00:00:00'`

Exemplo 1: SELECT básico — pseudocolunas ficam ocultas por padrão

SELECT * FROM ingestion_sale_detail_hourly;

-- Result:
+---------------+-------------+
| shop_name     | total_price |
+---------------+-------------+
| shanghai_shop | 10001.1     |
| chongqin_shop | 20002.2     |
| hangzhou_shop | 30003.3     |
| shenzhen_shop | 40004.4     |
| chengdu_shop  | 60006.6     |
| beijing_shop  | 50005.5     |
+---------------+-------------+

Exemplo 2: Incluir pseudocolunas e colunas de partição explicitamente

O fuso horário do projeto está definido como Asia/Shanghai (UTC+8). Como TRUNC_TIME converte para UTC antes de truncar, sale_time (a chave de partição) fica 8 horas atrás de _partitiontime.

Consulte a tabela particionada por hora:

SELECT *, _partitiontime, sale_time FROM ingestion_sale_detail_hourly;

-- Result:
+---------------+-------------+---------------------+---------------------+
| shop_name     | total_price | _partitiontime      | sale_time           |
+---------------+-------------+---------------------+---------------------+
| shanghai_shop | 10001.1     | 2025-06-18 15:00:00 | 2025-06-18 07:00:00 |
| chongqin_shop | 20002.2     | 2025-06-18 15:00:00 | 2025-06-18 07:00:00 |
| hangzhou_shop | 30003.3     | 2025-06-18 15:00:00 | 2025-06-18 07:00:00 |
| shenzhen_shop | 40004.4     | 2025-06-18 15:00:00 | 2025-06-18 07:00:00 |
| beijing_shop  | 50005.5     | 2025-06-15 14:00:00 | 2025-06-15 06:00:00 |
| chengdu_shop  | 60006.6     | 2025-06-14 05:00:00 | 2025-06-13 21:00:00 |
+---------------+-------------+---------------------+---------------------+

Consulte a tabela particionada por dia:

SELECT *, _partitiontime, _partitiondate, sale_date FROM ingestion_sale_detail_daily;

-- Result:
+--------------+-------------+---------------------+----------------+-----------+
| shop_name    | total_price | _partitiontime      | _partitiondate | sale_date |
+--------------+-------------+---------------------+----------------+-----------+
| beijing_shop | 50005.5     | 2025-06-18 00:00:00 | 2025-06-18     | 2025-06-18|
+--------------+-------------+---------------------+----------------+-----------+

Veja também

Tabelas particionadas automaticamente com base em funções de tempo — regras de eliminação de partições e expressões de filtro suportadas
Referência da função TRUNC_TIME — granularidades suportadas e detalhes da conversão para UTC
Visão geral de tabelas particionadas — comparação entre tabelas particionadas por tempo de ingestão, tabelas padrão e tabelas particionadas automaticamente
SHOW CREATE TABLE — visualize a lógica de geração de partição para qualquer tabela particionada por tempo de ingestão