Hologres:Compactar arquivos de dados

Pré-requisitos e limitações

• A full compaction requer Hologres V2.1 ou posterior. Para atualizar, consulte Upgrade an instance ou get online support para solicitar uma atualização.

• Apenas tabelas orientadas a colunas e tabelas híbridas linha-coluna oferecem suporte à full compaction.

• Em tabelas híbridas linha-coluna, a full compaction aplica-se apenas à parte do column store.

Sintaxe

SELECT hologres.hg_full_compact_table(
  '<schema_name.table_name>'
  [,'max_file_size_mb=<value>']
);

Parâmetros

Exemplos

Execute a full compaction em public.lineitem:

SELECT hologres.hg_full_compact_table('public.lineitem');

Execute a full compaction em public.lineitem com tamanho máximo de arquivo de saída de 256 MB:

SELECT hologres.hg_full_compact_table(
  'public.lineitem',
  'max_file_size_mb=256'
);

Pré-requisitos e limitações

• Essas propriedades de tabela exigem Hologres V4.0 ou posterior. Em versões anteriores, defini-las não tem efeito. Atualize a instância primeiro.

• Tais propriedades aplicam-se apenas a tabelas orientadas a colunas e tabelas híbridas linha-coluna. Em uma tabela híbrida linha-coluna, elas afetam apenas a parte do column store. Defini-las em uma tabela orientada a linhas não produz efeito.

• O auto compaction não precisa de intervenção manual na maioria dos casos. Exceto por online_config_compaction_semaphore, as propriedades avançadas interagem com as configurações de concorrência de maneiras difíceis de prever. Altere-as apenas para resolver um problema específico, preferencialmente com orientação do suporte técnico, e restaure os padrões em seguida.

Definir, consultar e redefinir propriedades de tabela

Defina propriedades de compactação no nível da tabela com SET_TABLE_PROPERTY. Todo nome de propriedade carrega o prefixo online_config_, e todo valor é passado como string. Um novo valor aplica-se às tarefas de compactação agendadas após a alteração; as tarefas já em execução não são afetadas. Não é necessário reiniciar a instância ou reconstruir a tabela.

-- Syntax
CALL SET_TABLE_PROPERTY('<schema_name>.<table_name>', 'online_config_<property_name>', '<value>');

-- Pause compaction scheduling on public.orders
CALL SET_TABLE_PROPERTY('public.orders', 'online_config_compaction_semaphore', '0');

CALL SET_TABLE_PROPERTY('public.orders', 'online_config_compaction_semaphore', 'reset');

SELECT property_key, property_value
FROM hologres.hg_table_properties
WHERE table_namespace = '<schema_name>'
  AND table_name = '<table_name>'
  AND property_key LIKE 'online_config_%';

Controlar a concorrência da compactação

A propriedade online_config_compaction_semaphore é a primeira a ser ajustada. Ela limita as tarefas de compactação simultâneas por tablet, não por tabela — sendo o tablet a unidade contra a qual a compactação é agendada. Uma tabela possui um ou mais tablets em cada shard; em uma tabela híbrida linha-coluna, as partes row store e column store são tablets separados. O teto teórico para toda a tabela é, portanto, aproximadamente tablet_count × property_value, embora o limite de concorrência no nível do worker e os recursos disponíveis geralmente o restrinjam a um valor menor.

O que realmente acontece ao definir o valor como 0

• Novas tarefas de compactação para a tabela deixam de ser agendadas.

• As tarefas já em execução não são canceladas. Elas terminam normalmente.

• Tarefas que já foram selecionadas para esta tabela e estão aguardando execução ainda ocupam slots de concorrência no nível do worker. Definir muitas tabelas como 0 simultaneamente priva a compactação em outras tabelas.

• Depois de aumentar o valor acima de 0, as tarefas na fila são retomadas, mas não há garantia de que um backlog nunca agendado será processado automaticamente — especialmente se a tabela não receber novas gravações. Execute VACUUM uma vez para forçar o processamento do backlog. Para entender o que o VACUUM faz e não faz, consulte Examples.

Para restaurar a concorrência e mesclar o backlog:

CALL SET_TABLE_PROPERTY('public.orders', 'online_config_compaction_semaphore', '2');
VACUUM public.orders;

Tabelas particionadas lógicas

Para uma tabela particionada lógica, o Hologres aumenta a concorrência proporcionalmente ao número de partições ativas. O teto para uma única unidade de agendamento é min(online_config_partition_table_compaction_semaphore_max, active_partition_count × online_config_compaction_semaphore), limitado a 8 por padrão. O valor de active_partition_count é medido em tempo de execução e não é uma propriedade configurável.

Riscos

• Não mantenha o valor em 0 por muito tempo. A contagem de arquivos e as linhas excluídas continuam se acumulando, o desempenho das consultas e o uso de armazenamento degradam e, quanto maior o backlog, mais pesada será a mesclagem eventual.

• Evite definir 0 ou aumentar o valor em muitas tabelas simultaneamente. Todas as tabelas compartilham o orçamento de concorrência no nível do worker: uma pausa em massa permite que tarefas na fila ocupem esse orçamento, e um aumento em massa causa filas globais e picos de recursos.

• Altere uma tabela e uma propriedade por vez, no menor incremento útil, e observe um ciclo completo de negócios antes da próxima mudança.

Propriedades avançadas

As propriedades a seguir alteram a forma como a compactação seleciona arquivos e a frequência de acionamento. Elas interagem com as configurações de concorrência, portanto, altere-as apenas para um problema diagnosticado específico — idealmente com orientação do suporte técnico — e restaure os padrões posteriormente.

Exemplos

Exemplo 1: Pausar a compactação para um carregamento em massa

-- 1. Record the current state. An empty result means no override is set.
SELECT property_key, property_value FROM hologres.hg_table_properties
WHERE table_namespace = 'public' AND table_name = 'orders'
  AND property_key = 'online_config_compaction_semaphore';

-- 2. Stop scheduling new compaction tasks.
CALL SET_TABLE_PROPERTY('public.orders', 'online_config_compaction_semaphore', '0');

-- 3. Run the bulk load. Watch CPU, I/O, and load throughput while it runs.

-- 4. Restore the property. Choose one of the following based on step 1.
-- 4a. Step 1 returned no rows:
CALL SET_TABLE_PROPERTY('public.orders', 'online_config_compaction_semaphore', 'reset');
-- 4b. Step 1 returned a value. Write that value back:
-- CALL SET_TABLE_PROPERTY('public.orders', 'online_config_compaction_semaphore', '<original_value>');

-- 5. Merge the backlog. Run this during a low-write period.
VACUUM public.orders;

Exemplo 2: Limpar arquivos pequenos residuais

Utilize este método quando cada nível tiver menos arquivos do que o limiar de acionamento, mas a tabela acumulou dezenas de arquivos pequenos que nunca são mesclados.

CALL SET_TABLE_PROPERTY('public.orders', 'online_config_ignore_level_compaction', 'true');
VACUUM public.orders;
-- Restore the default once the file count drops. Leaving it on inflates compaction
-- frequency and CPU and I/O usage on continuously written tables.
CALL SET_TABLE_PROPERTY('public.orders', 'online_config_ignore_level_compaction', 'reset');

Exemplo 3: Produzir arquivos mesclados maiores

Recomendado quando um tablet contém um grande volume de dados distribuído por muitos arquivos.

CALL SET_TABLE_PROPERTY('public.orders', 'online_config_orc_max_total_size_to_merge_mb', '512');
VACUUM public.orders;
-- Restore the default once the file count drops.
CALL SET_TABLE_PROPERTY('public.orders', 'online_config_orc_max_total_size_to_merge_mb', 'reset');

Verificar se uma alteração teve efeito

1. Os nomes das propriedades não são validados. Qualquer nome após o prefixo online_config_ é aceito e a instrução é bem-sucedida. Um nome com erro ortográfico não corresponde a nenhuma configuração, então a alteração silenciosamente não produz efeito. Para evitar isso:

   • Copie os nomes das propriedades das tabelas neste tópico em vez de digitá-los.

   • Confirme a gravação consultando hologres.hg_table_properties.

   • Verifique se o comportamento realmente mudou monitorando a contagem e o tamanho dos arquivos. Uma instrução bem-sucedida, por si só, não prova nada.

2. Tabelas particionadas herdam propriedades apenas na criação. Executar SET_TABLE_PROPERTY em uma tabela pai não afeta as partições filhas existentes. A propriedade é gravada apenas no pai, e como o pai não contém dados, o comportamento de compactação nas partições existentes permanece inalterado. As partições filhas copiam as propriedades do pai uma única vez, quando são criadas — incluindo partições criadas automaticamente pelo particionamento dinâmico — e alterações posteriores no pai não são propagadas. Para alterar o comportamento de compactação em uma tabela particionada, execute SET_TABLE_PROPERTY em cada partição filha alvo e verifique cada uma delas. Defina a propriedade também no pai se desejar que futuras partições a herdem.

3. Feche o ciclo com observação. Consulte hologres.hg_table_file_status para obter a contagem atual de arquivos e seus tamanhos, hologres.hg_partition_file_status para uma visualização por partição de uma tabela particionada lógica, e hologres.hg_table_info (gerado uma vez por dia) para revisar tendências. Um ajuste bem-sucedido mostra uma queda na contagem total de arquivos e um aumento no tamanho médio dos arquivos. O uso de armazenamento pode subir brevemente enquanto os arquivos mesclados aguardam limpeza; isso é esperado.

   SELECT * FROM hologres.hg_table_file_status('<schema_name>.<table_name>'::regclass);

Pré-requisitos e limitações

• A compactação remota requer Hologres V5.0 ou posterior.

• Tabelas orientadas a linhas, orientadas a colunas e híbridas linha-coluna oferecem suporte à compactação remota. No entanto, algumas estratégias internas de compactação não podem ser descarregadas, e essas tarefas ainda são executadas localmente.

• A compactação remota abrange apenas a fase de mesclagem de arquivos. As leituras e gravações de dados ainda são executadas no virtual warehouse principal.

• Por padrão, uma tarefa de compactação remota com falha não retorna para execução local. A tarefa falha diretamente e o agendador em segundo plano tenta executá-la novamente automaticamente. Para restaurar o comportamento de fallback, defina o parâmetro global enable_compaction_offload_fallback como true.

Configurar compaction_resource

A propriedade de tabela compaction_resource define o virtual warehouse que executa tarefas de compactação para uma única tabela. A alteração entra em vigor imediatamente, sem necessidade de reiniciar a instância.

Sintaxe

-- Offload compaction for a table to a specific virtual warehouse
CALL SET_TABLE_PROPERTY('<SCHEMA_NAME>.<TABLE_NAME>', 'compaction_resource', '<WAREHOUSE_NAME>');

-- Run compaction on the local virtual warehouse again (default)
CALL SET_TABLE_PROPERTY('<SCHEMA_NAME>.<TABLE_NAME>', 'compaction_resource', 'local');

Exemplos

-- Offload compaction for public.orders to the virtual warehouse named readonly
CALL SET_TABLE_PROPERTY('public.orders', 'compaction_resource', 'readonly');

-- Query the current setting
SELECT property_key, property_value
FROM hologres.hg_table_properties
WHERE table_namespace = 'public'
  AND table_name = 'orders'
  AND property_key = 'compaction_resource';

Um resultado vazio, ou um valor de local, significa que a tabela executa a compactação localmente.

Visualizar o status da compactação

Chame hologres.hg_show_compactions() para listar tarefas de compactação em execução e concluídas, incluindo aquelas executadas remotamente.

-- List all compaction records
SELECT * FROM hologres.hg_show_compactions();

-- List the compaction records that ran remotely
SELECT table_name, status, compaction_reason, execution_location,
       warehouse_name, start_time, end_time, extended_cost, last_error
FROM hologres.hg_show_compactions()
WHERE execution_location = 'warehouse'
ORDER BY start_time DESC;

A função retorna os seguintes campos.

Exemplos

O exemplo a seguir descarrega a compactação de uma tabela para um virtual warehouse remoto e, em seguida, aciona a full compaction manualmente.

-- 1. Make sure the target virtual warehouse exists. Create it in the Hologres
--    console or through the API. This example uses one named readonly.

-- 2. Configure the table to use remote compaction.
CALL SET_TABLE_PROPERTY('public.lineitem', 'compaction_resource', 'readonly');

-- 3. Trigger full compaction. The merge phase runs on the readonly virtual warehouse.
SELECT hologres.hg_full_compact_table('public.lineitem');

-- 4. Wait for compaction to finish.
SELECT hologres.hg_wait_table_full_compact('public.lineitem');

-- 5. Review the remote compaction records.
SELECT table_name, status, compaction_reason, execution_location,
       warehouse_name, start_time, end_time, extended_cost,
       extended_stats, last_error
FROM hologres.hg_show_compactions()
WHERE table_name = 'lineitem'
  AND execution_location = 'warehouse'
ORDER BY start_time DESC;