Rebuild - Hologres: Central de Documentação do Alibaba Cloud

O Hologres permite modificar algumas estruturas, propriedades de tabela e propriedades de coluna por meio da sintaxe ALTER TABLE. No entanto, essa sintaxe não oferece suporte a propriedades que afetam o armazenamento da tabela. A partir do Hologres V3.1, há suporte para a sintaxe REBUILD, que possibilita a modificação flexível de diversos parâmetros de uma tabela. Este tópico descreve como usar o REBUILD no Hologres.

Sintaxe

Formato da instrução

ASYNC REBUILD TABLE [ IF EXISTS ] <table_name>
    [ WITH ( <rebuild_parameter> [= <value>] [, ... ] )]  
    <action> [, ... ];
    
WHERE action IS ONE OF:
    ADD [ COLUMN ] <column_name> <data_type> [ column_constraint [ ... ] ]
    ALTER [ COLUMN ] <column_name> [ SET DATA ] TYPE <data_type> [ USING <expression> ]
    ALTER [ COLUMN ] <column_name> SET DEFAULT <expression>
    ALTER [ COLUMN ] <column_name> DROP DEFAULT
    ALTER [ COLUMN ] <column_name> { SET | DROP } NOT NULL
    ALTER PRIMARY KEY (<column_name> [, ...])
    TO [LOGICAL] PARTITION [BY LIST(<column_name> [, <column_name>])]
    SET ( <parameter> [= <value>] [, ... ] )

WHERE rebuild_parameter IS ONE OF:
    keep_source
    binlog_mode
    rebuild_guc_<guc_name> = '<guc_value>'

Parâmetros

Parâmetro	Subitem	Descrição
ASYNC		A tarefa REBUILD executa de forma assíncrona. Após a execução, retorna um `query_id`. Use esse `query_id` para monitorar o status de execução da tarefa. Atualmente, não há suporte para execução síncrona.
table_name		Nome da tabela de destino a reconstruir.
column_name		Nome da coluna da tabela de destino.
data_type		Tipo de dados da coluna.
action	ADD COLUMN	Adiciona uma coluna. Permite adicionar colunas NOT NULL e definir valores padrão.
	ALTER COLUMN TYPE	Modifica o tipo de dados de uma coluna.
	ALTER COLUMN SET/DROP DEFAULT	Define ou remove o valor padrão de uma coluna. Valores NULL nos dados existentes permanecem inalterados.
	ALTER COLUMN SET/DROP NOT NULL	Define ou remove a restrição NOT NULL de uma coluna.
	ALTER PRIMARY KEY	Modifica a chave primária da tabela. Em caso de conflito de dados com a nova chave primária, o sistema reportará um erro durante a execução assíncrona. Monitore o status de execução da tarefa regularmente.
	TO [LOGICAL] PARTITION	Converte a tabela em uma tabela particionada lógica ou física. Cenários suportados: Converter uma tabela padrão em uma tabela particionada física. Especifique uma chave de partição. Converter uma tabela padrão em uma tabela particionada lógica. Especifique uma chave de partição. Modificar a chave de partição de uma tabela particionada física. Converter uma tabela particionada física em uma tabela particionada lógica. A modificação da chave de partição é opcional. Não é possível converter uma tabela particionada lógica em uma tabela particionada física.
	SET ( <parameter> [= <value>])	Modifica propriedades da tabela. Cenários comuns: Modificar a chave de distribuição `distribution_key`. Modificar a chave de segmento `event_time_column`. Modificar o índice de clusterização `clustering_key`. Modificar o formato de armazenamento da tabela `orientation`: alternar entre armazenamento orientado a linhas, orientado a colunas e híbrido (linha-coluna). Modificar o `table_group` da tabela. Todas as demais propriedades da tabela também podem ser modificadas. Para modificar índices bitmap `bitmap_columns` ou colunas de codificação de dicionário `dictionary_encoding_columns`, utilize a sintaxe ALTER TABLE em vez de REBUILD.
WITH (<rebuild_parameter> [= <value>])		Defina parâmetros relacionados à tarefa REBUILD. Parâmetros comuns: keep_source: Não requer definição de valor. Após a conversão, o sistema mantém a tabela original e a renomeia para `tmp_rebuild_old_<query_id>_<unique_id>_<table_name>`. `binlog_mode`: Permite executar `REBUILD` em uma tabela com Binlog ativado. Para evitar perda de dados do Binlog, siga o procedimento descrito na seção Exemplos. `rebuild_guc_hg_computing_resource='serverless'`: Execute a tarefa `REBUILD` usando recursos serverless. Essa opção evita o consumo de recursos da instância e aumenta a estabilidade da tarefa. `rebuild_guc_<guc_name>='<guc_value>'`: Especifique outros parâmetros GUC para a tarefa. Para mais informações, consulte Parâmetros GUC.

Precauções

Há suporte apenas para execução assíncrona (ASYNC), que não exige ocupação prolongada da conexão.
Após o envio de uma tarefa REBUILD, a execução ocorre rapidamente e retorna o query_id da tarefa. Use esse query_id para visualizar o status de execução de uma tarefa REBUILD. Se a tarefa não for concluída com sucesso algum tempo após o envio, pode haver um grande volume de tarefas de agendamento assíncrono em execução na instância atual. Recomendamos aguardar e verificar novamente o status de execução após o retorno do query_id.
O uso do recurso REBUILD para modificar parâmetros de tabela envolve redistribuição subjacente de dados, o que consome recursos computacionais. Por isso, execute tarefas REBUILD fora dos horários de pico ou utilize recursos de computação serverless para garantir a estabilidade do negócio.
Durante uma tarefa REBUILD, a tabela fica somente leitura e não aceita gravações. A partir do Hologres V4.1, o REBUILD utiliza a tecnologia Dynamic Table para atualizações incrementais, reduzindo significativamente a janela de somente leitura. Para evitar indisponibilidade prolongada de gravação, a tabela de destino deve atender aos seguintes requisitos:
- A tabela deve possuir uma chave primária antes da operação REBUILD, e a nova chave primária deve incluir todas as colunas da chave primária original.
- Antes da operação REBUILD, a tabela deve usar armazenamento orientado a colunas ou armazenamento híbrido (linha-coluna).
- Após a operação REBUILD, a tabela não deve conter colunas geradas.
- Se a tabela for uma tabela particionada física antes da operação REBUILD, sua chave de partição deve permanecer inalterada.
- Caso a tabela se torne uma tabela particionada lógica após a operação REBUILD, ela poderá ter apenas uma chave de partição.
Para reduzir sobrecarga, modifique vários parâmetros em uma única tarefa REBUILD.
Após a reconstrução de uma tabela particionada física, suas propriedades de gerenciamento dinâmico de partições não são herdadas. Defina manualmente as seguintes propriedades após a conclusão da reconstrução:
- Propriedade auto_partitioning da tabela pai.
- Atributo keep_alive e outros atributos da tabela filha.
- Ao reconstruir uma tabela particionada física, quaisquer propriedades definidas independentemente nas tabelas filhas não são herdadas e retornam às configurações da tabela pai, como bitmap_columns e dictionary_encoding_columns.
Não há suporte para REBUILD nas seguintes tabelas:
- Tabelas com configurações especiais de propriedades de coluna, como otimização de armazenamento colunar para colunas JSONB, ou restrições de coluna, como colunas vetoriais.
- Tabelas com índice de texto completo ou índice secundário global.
- Tabelas que contêm colunas do tipo de dados Serial ou Bigserial.
- Tabelas referenciadas por uma Dynamic Table ou por uma view materializada. Tabelas referenciadas por views comuns têm suporte.

Exemplos

Reconstruir uma tabela sem Binlog

-- Create a table and import data.
CREATE TABLE rebuild_test (
    a TEXT,
    b TEXT,
    ds TEXT
);

INSERT INTO rebuild_test VALUES ('1', '1', '2025-04-01'), ('2', '2', '2025-04-02'), ('3', '3', '2025-04-03');

-- Add a non-null column with a default value.
ASYNC REBUILD TABLE rebuild_test ADD COLUMN c text NOT NULL DEFAULT 'a';

-- Change the primary key to column a.
ASYNC REBUILD TABLE rebuild_test ALTER PRIMARY KEY (a);

-- Use a serverless resource to run the REBUILD task, set the distribution_key and clustering_key for the table, and change the storage to row-column hybrid.
ASYNC REBUILD TABLE rebuild_test 
WITH (
    rebuild_guc_hg_computing_resource = 'serverless'
)
SET (
    distribution_key = 'a',
    clustering_key = 'a',
    orientation = 'row,column'
);

-- Convert a non-partitioned table to a logical partitioned table, set the partition key to ds, and add a NOT NULL constraint to the ds column.
ASYNC REBUILD TABLE rebuild_test 
    ALTER COLUMN ds SET NOT NULL,
    TO LOGICAL PARTITION BY LIST(ds);

Reconstruir uma tabela com Binlog

O comando REBUILD não preserva dados históricos do Binlog. Por esse motivo, não há suporte padrão para REBUILD em tabelas com Binlog ativado. Especifique o parâmetro binlog_mode e siga as etapas abaixo para garantir que os sistemas downstream tenham consumido totalmente os dados históricos do Binlog.

Execute o comando REBUILD.

ASYNC REBUILD TABLE rebuild_test 
WITH (
  binlog_mode
)
<YOUR_ACTION>;

Quando o parâmetro binlog_mode estiver definido para uma tarefa REBUILD, a tarefa pausará automaticamente após a conclusão da etapa set_readonly. Execute uma consulta SQL para verificar o progresso. Nesse ponto, o sistema definiu a tabela como somente leitura, impedindo novas gravações e a geração de novos dados no Binlog.

postgres=# SELECT step, status, progress FROM hologres.rebuild_progress('<query_id>');
             step              | status | progress 
-------------------------------+--------+----------
 prepare                       | done   | 1/1
 create_tmp_table              | done   | 1/1
 get_src_table_snapshot        | done   | 1/1
 insert                        | done   | 1/1
 set_readonly                  | done   | 1/1
 check_snapshot                |        | 0/1
 re-insert                     |        | -
 check_additional_child_table  |        | -
 create_additional_child_table |        | -
 insert_additional_child_table |        | -
 swap                          |        | 0/1
(11 rows)

Aguarde até que o cliente downstream termine de consumir todos os dados existentes do Binlog. Em seguida, retome manualmente a tarefa REBUILD executando a seguinte instrução SQL. Durante esse processo, a tabela de source permanece no modo somente leitura e não gera novos dados no Binlog.
```
RESUME '<query_id>';
```
Após a conclusão da tarefa REBUILD, o Binlog é ativado automaticamente para a nova tabela. Reinicie a tarefa de consumo de Binlog downstream e comece a consumir a partir de lsn = 0.

Monitoramento e O&M

Visualize o status de execução de uma tarefa REBUILD

A tarefa REBUILD executa de forma assíncrona. Após o envio bem-sucedido, ela retorna um status de sucesso e um query_id. Consulte a tabela de sistema hologres.rebuild_progress para visualizar o status das subtarefas assíncronas. A operação REBUILD na tabela só é considerada concluída quando todas as subtarefas forem bem-sucedidas. Comando:

SELECT * FROM hologres.rebuild_progress('<rebuild_query_id>');

A tabela a seguir descreve as colunas da tabela de sistema.

Nome da coluna	Descrição
job_name	O query_id da tarefa REBUILD.
step_id	ID da etapa. As subtarefas do REBUILD executam sequencialmente conforme os IDs de etapa.
step	Nome da etapa: prepare: Prepara a tarefa. create_tmp_table: Crie uma tabela temporária. get_src_table_snapshot: Obtém um snapshot de dados da tabela original. insert: Importa dados históricos para a tabela temporária. set_readonly: Define a tabela a reconstruir como somente leitura, interrompendo gravações de dados. check_snapshot: Compara o snapshot de dados atual da tabela com aquele obtido na Etapa 3. Se houver diferença, o processo avança para a etapa `re-insert`. re-insert: Importa dados incrementais. check_additional_child_table: Verifica se os usuários criaram novas tabelas filhas desde o início do REBUILD. Esta etapa aplica-se apenas a tabelas particionadas físicas. create_additional_child_table: Crie possíveis novas tabelas filhas para a tabela temporária. Esta etapa aplica-se apenas a tabelas particionadas físicas. insert_additional_child_table: Importa dados históricos para as novas tabelas filhas temporárias. Esta etapa aplica-se apenas a tabelas particionadas físicas. swap: Substitui a tabela original pela tabela temporária.
status	Status da subtarefa. done: Concluída. doing: Em andamento. NULL: Execução desta etapa desnecessária ou ainda indeterminada. error: Falha na execução. Verifique a mensagem de erro no campo message.
progress	Progresso da subtarefa: `m/n`. Neste formato, `n` representa o número total de subetapas a executar e `m` representa o número de subetapas já executadas. Esse total geralmente tem correlação positiva com o número de partições.
start_time	Horário de início da subtarefa.
end_time	Horário de término da subtarefa.
queryid	O query_id da subtarefa.
pid	ID do processo de serviço.
message	Mensagem da subtarefa. Se a subtarefa reportar um erro, o sistema registrará a mensagem de erro neste campo.

A figura a seguir mostra um exemplo de resultado.

opopo

Parar e reiniciar tarefas REBUILD

Pare a tarefa assíncrona REBUILD.
```
SUSPEND '<query_id>';
```
Retome a tarefa assíncrona definida como CANCEL.
```
RESUME '<query_id>';
```

Tratar exceções de tarefas REBUILD

Se uma tarefa REBUILD for interrompida por um erro ou parada manualmente pelo comando SUSPEND, retome-a com o comando RESUME ou siga estas etapas para encerrar a tarefa e restaurar a tabela de source.

Execute o comando a seguir para limpar as tabelas temporárias criadas durante o processo REBUILD.
```
CALL hg_clean_rebuild_tmp_tables('<query_id>');
```
Caso a tarefa tenha sido interrompida após a tabela de source tornar-se somente leitura, execute o comando apropriado para reativar as gravações.
- Para versões do Hologres anteriores à V4.1:
```
ALTER TABLE <table_name> SET (readonly = false);
```
- Para Hologres V4.1 e posteriores:
```
ALTER TABLE <table_name> SET RESET (ddl_options,write_options);
```