CREATE LOGICAL PARTITION TABLE - Hologres: Central de Documentação do Alibaba Cloud

As tabelas de partição lógica oferecem gerenciamento automático do ciclo de vida das partições: o Hologres cria partições quando os dados chegam e as remove quando ficam vazias. A tabela pai é uma tabela física; cada partição é um conceito lógico, não um objeto físico separado.

Use tabelas de partição lógica quando:

Seu conjunto de dados for grande e baseado em séries temporais ou categorias (logs diários, fluxos de eventos, dados de locatários).
Você quiser que o Hologres gerencie automaticamente a criação e a limpeza de partições, sem sobrecarga de DDL.
For necessário definir expiração por partição, camadas de armazenamento quente/frio ou geração seletiva de Binlog.

Prefira tabelas de partição física quando substituir partições inteiras com frequência usando TRUNCATE ou INSERT OVERWRITE. Essas operações são mais rápidas em partições físicas porque evitam exclusões em larga escala.

Tabelas de partição lógica exigem Hologres 3.1 ou posterior.

Limitações

Somente o particionamento LIST é suportado. RANGE e HASH não são suportados.
Uma chave de partição pode incluir uma ou duas colunas.
Tipos de dados suportados para chave de partição: INT, TEXT, VARCHAR, DATE, TIMESTAMP e TIMESTAMPTZ.
As chaves de partição devem ser NOT NULL.
A chave de partição de uma tabela de partição lógica suporta generated columns.
Uma única tabela de partição lógica suporta até 5.200 partições. Um banco de dados suporta até 200.000 partições lógicas no total.

Limites de importação em lote

Cenário	Limiar	Comportamento
Trabalho único de importação em lote	> 50 partições	Erro: `Bulkload partition count exceed limit, partition count is xxx, limit is xxx`
Gravações concorrentes do Fixed Plan (por tabela)	> 30 partições	Limitado — o Hologres aguarda alguns segundos e envia automaticamente
Gravações concorrentes do Fixed Plan (por tabela)	> 100 partições	Erro: `mem partition count exceed reject limit`

Limites de partições não persistidas (por nó worker)

Uma partição não persistida é aquela gravada na memória, mas ainda não liberada para o disco. A contagem é calculada como: partições do usuário × contagem de shards × contagem de índices por tabela. A contagem de shards inclui shards de réplica.

Limiar	Comportamento
> 500 partições não persistidas	Limitado — o Hologres aguarda alguns segundos e envia automaticamente
> 5.000 partições não persistidas	Erro: `mem partition count exceed reject limit`

Notas de uso

Granularidade da partição: Evite partições com menos de 100 milhões de linhas. Partições muito refinadas reduzem os benefícios de aceleração de consultas e aumentam o risco de acúmulo de arquivos pequenos. Por exemplo, particionar por dia é razoável para cargas de trabalho de alto volume; já particionar por id de cliente ou intervalos inferiores a uma hora geralmente é excessivo.
Padrão de gravação: Grave dados nas partições sequencialmente. Evite gravar em muitas partições simultaneamente.
Qualidade dos dados: Mantenha os dados de entrada limpos. Dados incorretos — como timestamps que não correspondem à meia-noite ao usar partições diárias — podem causar crescimento inesperado de partições.
Ciclo de vida da partição: Não crie nem exclua partições manualmente. As partições existem apenas enquanto contêm dados. Quando todos os dados de uma partição são excluídos, o Hologres remove a partição de forma assíncrona.
TRUNCATE e Binlog: O comando TRUNCATE não gera Binlog. Para desativar a geração de Binlog em uma sessão, execute SET hg_experimental_generate_binlog = off antes do TRUNCATE.
Alterações nas propriedades da tabela: Para modificar propriedades em uma tabela de partição lógica, use a sintaxe REBUILD. O backend divide a tarefa automaticamente e a executa sequencialmente por partição. Em operações de resharding (por exemplo, mover a tabela para outro Table Group), não use o procedimento armazenado HG_MOVE_TABLE_TO_TABLE_GROUP. Consulte o Table Group and Shard Count Operation Guide para obter a abordagem correta.

Criar uma tabela de partição lógica

Sintaxe

-- Create a logical partition parent table
CREATE TABLE [IF NOT EXISTS] [<schema_name>.]<table_name> ([
  {
   <column_name> <column_type> [ <column_constraints>, [...]]
   | <table_constraints>
   [, ...]
  }
])
LOGICAL PARTITION BY LIST(<partition_column_1> [, <partition_column_2>])
[WITH(
  <property_name> = <property_value>
 [, ...]
)];

As partições são criadas e removidas automaticamente com base nos dados. Não crie nem exclua partições manualmente.

Parâmetros

Parâmetro	Descrição
`schema_name`	O schema que contém a tabela. Omita se as tabelas pai e filha estiverem no mesmo schema.
`table_name`	O nome da tabela de partição pai.
`column_name`	O nome de uma coluna.
`column_type`	O tipo de dados da coluna.
`column_constraints`	Restrições no nível da coluna.
`table_constraints`	Restrições no nível da tabela.
`partition_column`	A chave de partição. Especifique uma ou duas colunas.
`property_name`	O nome de uma propriedade da tabela.
`property_value`	O valor a ser atribuído à propriedade da tabela.

Propriedades da tabela

Essas propriedades são definidas na tabela pai e aplicam-se a todas as partições. Como a tabela pai é uma tabela física e as partições são conceitos lógicos, não é possível definir essas propriedades diretamente em partições individuais.

Propriedade	Padrão	Valores válidos	Observações
`partition_time_format`	Nenhum	Ver Observações	Obrigatório apenas quando a chave de partição for TEXT. Suportado desde o Hologres V4.2. Valores válidos: `YYYYMMDDHH24`: granularidade horária, por exemplo `2024112221`. `YYYYMMDD`: granularidade diária, por exemplo `20241122`. `YYYYMM`: granularidade mensal, por exemplo `202411`. `YYYYQ`: granularidade trimestral, por exemplo `20241`, `20242`, `20243`, `20244`. `YYYY`: granularidade anual, por exemplo `2023`, `2024`. `YYYY-MM-DD-HH24`: horária com delimitadores, por exemplo `2024-11-22-21`. `YYYY-MM-DD`: diária com delimitadores, por exemplo `2024-11-22`. `YYYY-MM`: mensal com delimitadores, por exemplo `2024-11`. `YYYY-Q`: trimestral com delimitadores, por exemplo `2024-1`. Nota Defina esta propriedade antes de `partition_expiration_time` e `partition_keep_hot_window` na cláusula `WITH`.
`partition_expiration_time`	Nenhum (sem limpeza automática)	`'30 day'`, `'12 month'`, etc.	Use a mesma unidade de tempo da sua chave de partição. Nota Somente chaves de partição de coluna única são suportadas. Para chaves de partição do tipo tempo (DATE, TIMESTAMP, TIMESTAMPTZ), nenhuma configuração de `partition_time_format` é necessária. O Hologres V4.2 e posteriores suportam chaves de partição TEXT. Defina `partition_time_format` para especificar como os valores TEXT codificam o tempo.
`partition_keep_hot_window`	Todos os dados permanecem quentes	`'30 day'`, `'12 month'`, etc.	Os dados fora desta janela são movidos para armazenamento frio de forma assíncrona. Consulte Data tiering storage. Nota Somente chaves de partição de coluna única são suportadas. Para chaves de partição do tipo tempo (DATE, TIMESTAMP, TIMESTAMPTZ), nenhuma configuração de `partition_time_format` é necessária. O Hologres V4.2 e posteriores suportam chaves de partição TEXT. Defina `partition_time_format` para especificar como os valores TEXT codificam o tempo.
`partition_require_filter`	`FALSE`	`TRUE`, `FALSE`	Se definido como `TRUE`, as consultas na tabela pai devem incluir uma condição de filtro de partição. Consultas sem essa condição falharão.
`binlog_level`	`'none'`	`'none'`, `'replica'`	Ativa ou desativa o Binlog para a tabela pai. Consulte Subscribe to Hologres binary logging.
`binlog_ttl`	`2592000` (30 dias, em segundos)	Inteiro (segundos)	O tempo de vida (TTL) para dados do Binlog.
`partition_generate_binlog_window`	Nenhum (todos os dados geram Binlog)	`'3 day'`, `'12 hour'`, etc.	Apenas dados em partições criadas dentro da janela geram Binlog. Aplica-se somente a tabelas com uma única chave de partição baseada em tempo.
Outras propriedades (índices, `orientation`, etc.)	—	—	Tabelas de partição lógica suportam `distribution_key`, `clustering_key`, `orientation`, `time_to_live_in_seconds` e outras propriedades padrão. Consulte CREATE TABLE e o Scenario-based table creation optimization guide. Propriedades de gerenciamento dinâmico de partições de tabelas de partição física não são suportadas. Consulte Dynamic partition management.

Propriedades da partição

Estas propriedades aplicam-se a partições individuais. Modifique-as com ALTER LOGICAL PARTITION TABLE.

Propriedade	Padrão	Valores válidos	Comportamento
`keep_alive`	`FALSE`	`TRUE`, `FALSE`	Se `TRUE`, a partição nunca é limpa automaticamente, mesmo que `partition_expiration_time` esteja definido na tabela pai.
`storage_mode`	Não definido (segue `partition_keep_hot_window` da pai)	`'hot'`, `'cold'`	Substitui `partition_keep_hot_window` da tabela pai para esta partição específica.
`generate_binlog`	Não definido (segue `partition_generate_binlog_window` da pai)	`'on'`, `'off'`	Substitui `partition_generate_binlog_window` da tabela pai para esta partição específica.

Exemplos

Exemplo 1: Coluna regular como chave de partição

CREATE TABLE public.hologres_logical_parent_1 (
    a TEXT,
    b INT,
    c TIMESTAMP,
    ds DATE NOT NULL,
    PRIMARY KEY (b, ds))
LOGICAL PARTITION BY LIST (ds)
WITH (
    orientation = 'column',
    distribution_key = 'b',
    partition_expiration_time = '30 day',
    partition_keep_hot_window = '15 day',
    partition_require_filter = TRUE,
    binlog_level = 'replica',
    partition_generate_binlog_window = '3 day'
);

Exemplo 2: Coluna gerada como chave de partição

A chave de partição ds é derivada da coluna c usando date_trunc. Isso atribui automaticamente cada linha à partição diária correta sem exigir que o chamador calcule o valor da partição. Para mais informações, consulte Hologres generated columns.

CREATE TABLE public.hologres_logical_parent_2 (
    a TEXT,
    b INT,
    c TIMESTAMP,
    ds TIMESTAMP GENERATED ALWAYS AS (date_trunc('day', c)) STORED NOT NULL,
    PRIMARY KEY (b, ds))
LOGICAL PARTITION BY LIST (ds)
WITH (
    orientation = 'column',
    distribution_key = 'b',
    partition_expiration_time = '30 day',
    partition_keep_hot_window = '15 day',
    partition_require_filter = TRUE,
    binlog_level = 'replica',
    partition_generate_binlog_window = '3 day'
);

Exemplo 3: Duas colunas como chaves de partição

CREATE TABLE public.hologres_logical_parent_3 (
    a TEXT,
    b INT,
    yy TEXT NOT NULL,
    mm TEXT NOT NULL)
LOGICAL PARTITION BY LIST (yy, mm)
WITH (
    orientation = 'column',
    distribution_key = 'b',
    partition_require_filter = TRUE
);

Gerenciar dados

Granularidade de bloqueio

Operação	Tipo de bloqueio	Observações
Importação ou atualização em lote para uma partição especificada; INSERT OVERWRITE; TRUNCATE para uma partição especificada	Bloqueio de partição	Ao executar usando recursos de instância local ou grupo de computação: bloqueio de partição. Outras partições permanecem inalteradas. Ao executar usando recursos Serverless: bloqueio de tabela antes da V4.2; bloqueio de partição a partir da V4.2.
Importação ou atualização em lote sem especificar partição; TRUNCATE sem especificar partição; qualquer DELETE	Bloqueio de tabela	Outras operações de gerenciamento de dados aguardam até que o bloqueio seja liberado.
Gravação, atualização ou exclusão do Fixed Plan	Bloqueio de linha	Conflita com importação em lote, atualização ou exclusão. Não conflita com outras operações do Fixed Plan.

Escolher um método de limpeza de dados

Método	Quando usar	Tipo de bloqueio	Observações
`DELETE`	Para excluir seletivamente linhas que correspondem a uma condição	Bloqueio de tabela	Mais lento para grandes conjuntos de dados
`TRUNCATE` (nível de partição)	Remover todos os dados de uma ou mais partições específicas	Bloqueio de partição	Mais rápido que DELETE; não gera Binlog; não suportado em DML de grupo de computação — use o grupo de computação líder
`TRUNCATE` (nível de tabela)	Remover todos os dados da tabela pai	Bloqueio de tabela	Mais rápido para limpeza completa; não gera Binlog
`INSERT OVERWRITE`	Substituir todos os dados de uma partição por novos dados	Bloqueio de partição (por partição)	Síncrono; se múltiplas partições forem especificadas, elas serão processadas em paralelo — divida em tarefas sequenciais para reduzir o uso de CPU e memória

Gravar na tabela pai

As operações de gravação, atualização e limpeza de dados funcionam da mesma forma que em tabelas padrão. O Hologres cria ou remove partições automaticamente com base nos dados.

-- Write data; Hologres creates partitions automatically
INSERT INTO public.hologres_logical_parent_2
VALUES
    ('a', 1, '2025-03-16 10:00:00'),
    ('b', 2, '2025-03-17 11:00:00'),
    ('c', 3, '2025-03-18 12:00:00'),
    ('d', 4, '2025-03-19 13:00:00'),
    ('e', 5, '2025-03-20 14:00:00');

-- Delete rows (table lock)
DELETE FROM public.hologres_logical_parent_2 WHERE ds = '2025-03-20';

-- Truncate the entire parent table (no Binlog generated)
SET hg_experimental_generate_binlog = off;
TRUNCATE public.hologres_logical_parent_2;

Gravar em uma partição específica

-- Import into a specified partition
INSERT INTO public.hologres_logical_parent_1
PARTITION (ds = '2025-03-16')
VALUES
    ('a', 1, '2025-03-16 10:00:00', '2025-03-16');

-- Rows that don't match the specified partition are silently skipped (no error)
INSERT INTO public.hologres_logical_parent_1
PARTITION (ds = '2025-03-16')
VALUES
    ('a', 1, '2025-03-16 10:00:00', '2025-03-16'),
    ('b', 2, '2025-03-17 11:00:00', '2025-03-17');

Limpar dados da partição

-- Delete rows from specific partitions (table lock)
DELETE FROM public.hologres_logical_parent_1 WHERE ds = '2025-03-16' or ds = '2025-03-17';

-- Truncate specific partitions (partition lock, no Binlog generated)
-- Not supported in compute group DML; run in the leader compute group.
SET hg_experimental_generate_binlog = off;
TRUNCATE public.hologres_logical_parent_1 PARTITION (ds = '2025-03-16') PARTITION (ds = '2025-03-17');

Sobrescrever uma partição

O Hologres 3.1 e versões posteriores suportam a sintaxe nativa INSERT OVERWRITE para tabelas de partição lógica. Consulte INSERT OVERWRITE.

Importante

O INSERT OVERWRITE é síncrono. Se você especificar múltiplas partições lógicas, o Hologres as processará em paralelo, o que aumenta o uso de CPU e memória. Divida sobrescritas de múltiplas partições em tarefas sequenciais.

Consultar tabelas de partição lógica

-- Query with a partition filter condition
SELECT * FROM public.hologres_logical_parent_1 WHERE ds = '2025-03-16';

-- Query without a partition filter condition
-- Requires partition_require_filter = FALSE on the parent table
SELECT * FROM public.hologres_logical_parent_1;

Se partition_require_filter estiver definido como TRUE, consultas sem uma condição de filtro de partição falharão.

Visualizar metadados

O Hologres fornece tabelas de sistema e funções para consultar metadados de tabelas de partição lógica.

Objeto	Finalidade
`hologres.hg_table_properties`	Visualize propriedades da tabela
`hologres.hg_list_logical_partition('<table_name>')`	Listar todas as partições em uma tabela de partição lógica
`hologres.hg_logical_partitioned_table_properties`	Listar todas as partições lógicas e suas propriedades na instância atual
`hologres.hg_partition_file_status('<table_name>')`	Consultar tamanhos de armazenamento quente e frio e contagens de arquivos para todas as partições (Hologres 3.1.4 e posterior)

Verificar se uma tabela é uma tabela de partição lógica:

SELECT *
FROM hologres.hg_table_properties
WHERE
    table_name = '<table_name>'
    AND property_key = 'is_logical_partitioned_table'
    AND property_value = 'true';

Listar todas as partições:

SELECT * FROM hologres.hg_list_logical_partition('<schema_name>.<table_name>');

Listar configurações de propriedades da partição:

Esta consulta retorna apenas configurações que diferem entre as partições filhas e a tabela pai. Um resultado vazio significa que nenhuma substituição no nível da partição está definida.

SELECT *
FROM hologres.hg_logical_partitioned_table_properties
WHERE
    table_namespace = '<schema_name>'
    AND table_name = '<table_name>'
ORDER BY partition DESC;

Visualize tamanhos de armazenamento quente e frio:

SELECT * FROM hologres.hg_partition_file_status('<schema_name>.<table_name>');

As partições lógicas também são compatíveis com system tables padrão do Hologres.

Visualize o DDL de uma tabela de partição lógica:

SELECT hg_dump_script('<schema_name>.<table_name>');

Visualize propriedades da tabela pai:

SELECT *
FROM hologres.hg_table_properties
WHERE
    table_namespace = '<schema_name>'
    AND table_name = '<table_name>';

Visualize a maior partição:

Como a limpeza de dados e a limpeza de partições são assíncronas, MAX_PT pode retornar resultados incorretos se a maior partição tiver sido esvaziada. Use INSERT OVERWRITE para excluir dados e evitar esse problema.

SELECT MAX_PT('<schema_name>.<table_name>');

Verificar se alguma tabela de partição excede o limite de partições:

CREATE OR REPLACE PROCEDURE check_logical_partition_count()
LANGUAGE 'plpgsql'
AS $$
DECLARE
    table_max_partition_count bigint;
    table_partition_count bigint;
    exceeded_logical_partition_limit boolean;
    row_record record;
BEGIN
    SELECT substring(result FROM '^[^:]*: (\d+)')::INTEGER INTO table_max_partition_count
        FROM hg_admin_command('get_global_flag', 'flag=table_max_partition_count') AS result;

    RAISE NOTICE 'table_max_partition_count=%', table_max_partition_count;

    FOR row_record IN
        SELECT table_namespace, table_name
            FROM hologres.hg_table_properties
            WHERE property_key = 'is_logical_partitioned_table' AND (property_value = 'true' OR property_value = 't')
    LOOP
        SELECT count(*) INTO table_partition_count
            FROM hologres.hg_list_logical_partition(quote_ident(row_record.table_namespace) || '.' || quote_ident(row_record.table_name));
        IF table_partition_count > table_max_partition_count THEN
            RAISE NOTICE 'table %.% partition count exceeds limit (% > %)', row_record.table_namespace, row_record.table_name, table_partition_count, table_max_partition_count;
        END IF;
    END LOOP;
END;
$$;

CALL check_logical_partition_count();

Hologres:CREATE LOGICAL PARTITION TABLE