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

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		Especifica que a tarefa REBUILD executa de forma assíncrona. Após a execução, o sistema 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. Se houver 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 incluem: 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`). Permite converter entre armazenamento orientado a linhas, orientado a colunas e híbrido (linhas e colunas). Modificar o `table_group` ao qual a tabela pertence. Todas as demais propriedades da tabela podem ser modificadas. Para modificar índices bitmap (`bitmap_columns`) ou colunas de codificação de dicionário (`dictionary_encoding_columns`), use a instrução ALTER TABLE. O uso de REBUILD não é necessário.
WITH (<rebuild_parameter> [= <value>])		Define parâmetros relacionados à tarefa REBUILD. Parâmetros comuns: keep_source: Não requer valor. Se especificado, a tabela original não é excluída, mas renomeada para `tmp_rebuild_old_<query_id>_<unique_id>_<table_name>`. binlog_mode: Não requer valor. Permite reconstruir uma tabela com Binlog ativado. Para evitar perda de dados do Binlog, siga as etapas descritas na seção Exemplos. `rebuild_guc_hg_computing_resource='serverless'`: Utiliza recursos Serverless para executar a tarefa REBUILD. Isso evita o consumo de recursos da sua instância e aumenta a estabilidade da tarefa. `rebuild_guc_<guc_name>='<guc_value>'`: Outros parâmetros GUC podem ser definidos aqui. 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 enviar uma tarefa REBUILD, a instrução retorna um query_id. Use esse query_id para visualizar o status de execução da tarefa REBUILD. Caso o envio não retorne um query_id rapidamente, pode haver muitas tarefas assíncronas em execução na instância. Recomendamos aguardar o retorno do query_id antes de verificar o status da tarefa.
O uso do recurso REBUILD para modificar parâmetros de tabela envolve redistribuição subjacente de dados, o que consome recursos de computação. Por isso, recomenda-se executar tarefas REBUILD fora dos horários de pico ou utilizar recursos de computação serverless para garantir a estabilidade do negócio.
Durante uma tarefa REBUILD, a tabela fica temporariamente em estado somente leitura, bloqueando gravações. A partir do Hologres V4.1, o REBUILD utiliza a tecnologia Dynamic Table para atualizações incrementais, reduzindo significativamente a duração do período somente leitura. Essa otimização aplica-se apenas se a tabela atender às condições abaixo. Caso contrário, a tabela permanecerá somente leitura durante toda a execução da tarefa.
- A tabela de destino deve possuir uma chave primária antes da reconstrução, e a nova chave primária deve conter todas as colunas da chave primária original.
- A tabela de destino deve utilizar armazenamento orientado a colunas ou armazenamento híbrido (linhas e colunas) antes da reconstrução.
- A tabela de destino não deve conter colunas geradas após a reconstrução.
- Se a tabela de destino for uma tabela particionada física antes da reconstrução, sua chave de partição deve permanecer inalterada após o processo.
- Se a tabela de destino se tornar uma tabela particionada lógica após a reconstrução, ela poderá ter apenas uma chave de partição.
Para reduzir sobrecarga, combine várias alterações em uma única tarefa REBUILD.
Após a reconstrução de uma tabela particionada física, suas propriedades de gerenciamento de partição dinâmica não são herdadas. Reconfigure-as após a conclusão da tarefa. Essas propriedades incluem:
- A propriedade auto_partitioning da tabela particionada pai.
- Propriedades das partições filhas, como keep_alive.
- Após a reconstrução de uma tabela particionada física, quaisquer propriedades definidas independentemente em suas partições filhas não são herdadas. As partições filhas herdarão todas as propriedades da tabela pai, como bitmap_columns e dictionary_encoding_columns.
Não há suporte para REBUILD nos seguintes tipos de tabelas:
- Tabelas com propriedades específicas 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 com dependências de Dynamic Table ou view materializada. Tabelas com dependências de view padrão são suportadas.

Exemplos

Reconstrução em 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 NOT 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 Serverless resources to run the REBUILD task, set the distribution_key and clustering_key, and change to row-column hybrid storage.
ASYNC REBUILD TABLE rebuild_test 
WITH (
    rebuild_guc_hg_computing_resource = 'serverless'
)
SET (
    distribution_key = 'a',
    clustering_key = 'a',
    orientation = 'row,column'
);
-- Convert the 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);

Reconstrução em tabela com Binlog

A instrução REBUILD não preserva dados históricos do Binlog. Portanto, por padrão, não é possível executar REBUILD em uma tabela com Binlog ativado. Especifique o parâmetro binlog_mode e siga as etapas abaixo para garantir que o consumidor downstream tenha processado completamente todos os dados existentes do Binlog.

Execute a instrução REBUILD.

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

Em uma tarefa REBUILD com o parâmetro binlog_mode, a tarefa pausa automaticamente após a conclusão da etapa set_readonly. Consulte o progresso executando a seguinte instrução SQL. Neste ponto, a tabela está em modo somente leitura, impedindo novas gravações de dados 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 os clientes downstream terminarem de consumir os dados existentes do Binlog e interrompa essas tarefas de consumo. Em seguida, execute manualmente a seguinte instrução SQL para retomar a tarefa REBUILD.
```
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 de forma stateless e consuma o Binlog da nova tabela a partir de lsn = 0.

Converter uma tabela regular em uma liquid table

A partir do Hologres V4.2, é possível usar o REBUILD para converter uma tabela regular em uma liquid table, ou converter uma liquid table de volta para uma tabela regular.

--- Convert a regular table to a liquid table.
ASYNC REBUILD TABLE normal_table 
SET (
  liquid_table = 'true'
);

--- Convert a liquid table to a regular table.
ASYNC REBUILD TABLE liquid_table 
SET (
  liquid_table = 'false'
);

Monitoramento e O&M

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

As tarefas REBUILD executam de forma assíncrona. Quando uma tarefa é enviada com sucesso, a instrução retorna um status de sucesso e um query_id. Consulte a view de sistema hologres.rebuild_progress para monitorar o status das subtarefas assíncronas. A operação REBUILD só é considerada concluída quando todas as subtarefas forem bem-sucedidas. Execute o seguinte 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 de acordo com os IDs das etapas.
step	Nome da etapa: prepare: Prepara a tarefa. create_tmp_table: Cria 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: Verifica se o snapshot de dados atual corresponde ao obtido na etapa get_src_table_snapshot. Se houver diferença, o sistema executa a etapa `re-insert`. re-insert: Importa dados incrementais. check_additional_child_table: Verifica se novos usuários criaram tabelas filhas desde o início do REBUILD até o momento atual. Esta etapa aplica-se apenas a tabelas particionadas físicas. create_additional_child_table: Cria 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: Não é necessário executar esta etapa ou ainda não é possível determinar se ela precisa ser executada. error: Falha na execução. Verifique a mensagem de erro no campo message.
progress	Progresso da subtarefa, exibido como `m/n`, onde m é o número de subetapas concluídas e n é o total. A contagem total (n) geralmente corresponde ao número de partições da tabela.
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 service.
message	Mensagem da subtarefa. Se a subtarefa reportar um erro, o sistema registrará a mensagem de erro neste campo.

Parar e reiniciar tarefas REBUILD

Suspenda uma tarefa assíncrona REBUILD.
```
SUSPEND '<query_id>';
```
Retome a tarefa assíncrona marcada como CANCEL.
```
RESUME '<query_id>';
```

Exceções em tarefas de reconstrução

Se uma tarefa REBUILD for interrompida por um erro ou suspensa manualmente, você poderá retomá-la com o comando RESUME ou encerrar a tarefa e limpar o ambiente seguindo estas etapas:

Execute o seguinte comando para limpar as tabelas temporárias criadas durante o processo REBUILD.
```
CALL hg_clean_rebuild_tmp_tables('<query_id>');
```
Caso a tabela tenha sido definida como somente leitura, execute o comando apropriado para restaurar o acesso de gravação.
- Para versões do Hologres anteriores à V4.1, execute o seguinte comando.
```
ALTER TABLE <table_name> SET (readonly = false);
```
- Para Hologres V4.1 e posteriores, execute o seguinte comando.
```
ALTER TABLE <table_name> RESET (ddl_options,write_options);
```