Hologres:ANALYZE e AUTO ANALYZE

Por que as estatísticas são necessárias?

O otimizador depende de estatísticas de tabelas e colunas para gerar planos de execução adequados, incluindo:

• Contagem de linhas e de colunas

• Largura da coluna (Width)

• Número de valores distintos (NDV)

• Valores mais comuns (MCV) e suas frequências

• Histograma e outras características de distribuição

Essas informações orientam o otimizador a:

• Estimar o custo de execução do operador

• Reduzir o espaço de busca do plano de execução

• Selecionar a ordem de Join e os algoritmos de Join apropriados

• Estimar memória e paralelismo

Isso resulta em um plano de execução mais otimizado.

O comando ANALYZE é o método padrão para os usuários coletarem ativamente estatísticas de tabelas e colunas. Quando as estatísticas estão ausentes ou imprecisas, o plano de consulta pode degradar significativamente, causando, por exemplo, ordenação anormal de Join. Os sintomas incluem: OOM na consulta, tempo de execução longo ou alto consumo de CPU da instância.

O AUTO ANALYZE é o método padrão do sistema Hologres para coletar automaticamente estatísticas de tabelas e colunas. Como o AUTO ANALYZE é um processo assíncrono em segundo plano, há um atraso de dezenas de segundos a minutos entre a alteração dos dados da tabela e o momento em que o AUTO ANALYZE descobre, agenda e conclui a coleta automática de estatísticas. Portanto, em alguns cenários específicos, recomenda-se executar manualmente o ANALYZE para garantir a coleta oportuna das estatísticas.

Quando executar manualmente o ANALYZE

A execução manual é recomendada nos seguintes cenários:

• Após operações INSERT / UPDATE / DELETE que importam, atualizam ou excluem uma grande quantidade de dados em uma tabela que será consultada imediatamente, execute o ANALYZE na tabela após o INSERT / UPDATE / DELETE;

• Quando o desempenho de Join entre múltiplas tabelas degradar significativamente, execute o ANALYZE no nível de coluna nas colunas-chave de Join e nas colunas de Group By;

• Após executar CREATE FOREIGN TABLE ou IMPORT FOREIGN SCHEMA para uma tabela externa que será consultada imediatamente, execute o ANALYZE na nova tabela externa antes da consulta para coletar estatísticas iniciais;

• Após executar CREATE EXTERNAL DATABASE e o banco for consultado imediatamente, execute o ANALYZE nas tabelas do banco de dados externo antes da consulta;

• Quando ocorrer um dos seguintes erros ou sintomas:

  • Erro de OOM em Join de múltiplas tabelas: Query executor exceeded total memory limitation ... ou Query exceed per query memory limitation ...;

  • Erro em Join de múltiplas tabelas: Capacity error: BinaryArray cannot contain more than 2147483646 bytes ...;

  • Tarefas de importação ou consulta com duração anormalmente longa e utilização desigual de CPU.

  • EXPLAIN <SQL> mostra um operador Scan com contagem estimada de 1000 linhas: -> Seq Scan on tbl (cost=0.00..5.00 rows=1000 width=1). Isso indica que a tabela não possui estatísticas.

  • EXPLAIN <SQL> mostra um operador Scan com contagem estimada de 1 linha: -> Seq Scan on tbl (cost=0.00..1.00 rows=1 width=1). Isso indica que a tabela tem estimativa de 0 linhas. Se o resultado real do Scan não for 0 linhas, as estatísticas podem estar desatualizadas; recomenda-se um ANALYZE manual.

Nos cenários acima, geralmente recomenda-se executar manualmente o ANALYZE e observar se o desempenho se recupera antes de ajustar a configuração do AUTO ANALYZE.

Sintaxe básica e comportamento

• Coletar estatísticas para todas as colunas da tabela inteira

ANALYZE table_name;

• Coleta a contagem de linhas da tabela e obtém uniformemente Width, MCV, Histograma, NDV e outras estatísticas para todas as colunas regulares;

• Usa amostragem para estimar vários valores estatísticos. A operação inicia uma subconsulta SQL de amostragem dentro do processo ANALYZE.

• Por padrão, o ANALYZE amostra aleatoriamente 30.000 linhas da tabela para coleta e cálculo de estatísticas. Se a tabela tiver menos de 30.000 linhas, todas as linhas são amostradas.

• Coletar estatísticas apenas para colunas específicas (recomendado para colunas-chave)

ANALYZE table_name(col1, col2, ...);

• Calcula um NDV mais preciso para as colunas especificadas (geralmente usando a lógica APPROX_COUNT_DISTINCT). Esse método é mais preciso que a amostragem no nível da tabela, porém mais custoso;

• MCV, Histograma, Width e outras estatísticas ainda são obtidos por amostragem;

• Quando o ANALYZE é executado várias vezes na mesma coluna, a execução posterior sobrescreve as estatísticas antigas dessa coluna, mas não afeta outras colunas não especificadas.

Limitações e considerações

• Colunas que não serão analisadas

  • Tipos não suportados: Quando o tipo de uma coluna é um Tipo Definido pelo Usuário ou não está no conjunto de tipos que o Hologres suporta para estatísticas, a coleta é ignorada:

    • Os tipos de coluna que não suportam ANALYZE incluem: "char" (tipo de caractere único), BIT, VARBIT, BYTEA, NAME, JSON, TSVECTOR, TSQUERY, OID, XID, CID, INET, POINT, LINE, LSEG, BOX, CIRCLE, PATH, POLYGON, BITARRAY, VARBITARRAY, BYTEAARRAY, INT2ARRAY, MONEYARRAY, NUMERICARRAY, TIMEARRAY, TIMETZARRAY, TIMESTAMPTZARRAY, TIMESTAMPARRAY, ANYARRAY, REGCLASS, DATEARRAY ou outros tipos INTERNAL.

    • Quando o tipo da coluna não é suportado, tanto o ANALYZE manual quanto o AUTO ANALYZE são ignorados;

    • Para tabelas particionadas, tipos de coluna que não suportam mesclagem incremental de estatísticas de partição também não são analisados. Além dos tipos listados acima, os tipos não suportados incluem: BOOLARRAY, INT4ARRAY, TEXTARRAY, BPCHARARRAY, VARCHARARRAY, INT8ARRAY, FLOAT4ARRAY, FLOAT8ARRAY.

  • Colunas marcadas como excluídas: Colunas lógicas retidas após ALTER TABLE ... DROP COLUMN (attisdropped = true) não são analisadas;

  • Desativadas explicitamente por atributo de coluna:

    • Colunas com o atributo enable_analyze = false não são processadas pelo ANALYZE ou AUTO ANALYZE;

    • Colunas com o atributo enable_auto_analyze = false não são processadas pelo AUTO ANALYZE.

    • Para detalhes sobre esses atributos de coluna, consulte as seções subsequentes.

  • Estatísticas de coluna JSONB não habilitadas:

    • Se o tipo da coluna for JSONB e enable_jsonb_stats não estiver habilitado, as estatísticas JSONB não serão coletadas para essa coluna;

    • Se você precisar depender de estatísticas de coluna JSONB (por exemplo, condições de filtro JSON complexas), habilite primeiro enable_jsonb_stats nos atributos da coluna.

• Limitações do ANALYZE para tabelas de data lake

  • Não há suporte para ANALYZE em Timestamp, Version, Branch, Snapshot ou Tag específicos individualmente.

Uso típico

• Uso típico recomendado

  • Execute o ANALYZE no nível de coluna em colunas de Join, colunas de Group By e colunas de condição de filtro:

ANALYZE tablename (order_id, user_id, dt);

• • Após importação ou atualização em lote, execute em tabelas significativamente afetadas:

ANALYZE tablename;

• • Execute em tabelas externas (FOREIGN TABLE / IMPORT FOREIGN SCHEMA / tabelas sob EXTERNAL DATABASE) antes da primeira consulta:

ANALYZE foreign_table;

• Ignorar coleta de estatísticas para colunas específicas definindo atributos de coluna

  • O Hologres permite controlar a execução do ANALYZE ou AUTO ANALYZE em uma coluna por meio de atributos no nível da coluna. Isso se aplica aos seguintes cenários:

    • Colunas muito largas (como Text muito longo) têm alto custo de coleta de estatísticas, e coletar estatísticas para elas oferece benefício limitado ou nulo ao plano de consulta;

    • Certas colunas nunca participam de Joins, filtragens ou agregações e não precisam de coleta de estatísticas;

    • Necessidade de reduzir o consumo de recursos do ANALYZE ou AUTO ANALYZE.

  • Os parâmetros de controle são as seguintes opções de coluna:

    • enable_analyze: Controla se a coluna participa do ANALYZE manual e do AUTO ANALYZE automático. O padrão é true;

    • enable_auto_analyze: Controla apenas se a coluna participa do AUTO ANALYZE automático. O padrão é true.

  • Método de definição (via comando ALTER TABLE):

-- Disable ANALYZE and AUTO ANALYZE for a specific column
ALTER TABLE t ALTER COLUMN bitmap_col SET (enable_analyze = false);

-- Disable AUTO ANALYZE for a specific column while still allowing manual ANALYZE
ALTER TABLE t ALTER COLUMN large_text_col SET (enable_auto_analyze = false);

-- Restore default behavior (re-enable)
ALTER TABLE t ALTER COLUMN bitmap_col RESET (enable_analyze);
ALTER TABLE t ALTER COLUMN large_text_col RESET (enable_auto_analyze);

• • Considerações:

    • Após definir enable_analyze = false, a coluna será ignorada automaticamente ao executar ANALYZE table_name;, mas ainda poderá ser coletada explicitamente via ANALYZE table_name(col); manual;

    • Após definir enable_auto_analyze = false, a coluna não será coletada pelo AUTO ANALYZE, mas ainda poderá ser coletada explicitamente via ANALYZE table_name(col); manual;

    • Se uma coluna tiver impacto significativo no plano de consulta (como colunas de Join ou colunas de condição de filtro), não é recomendável desativar sua coleta de estatísticas.

Cenários e limitações

• No Hologres V2.0 e posteriores, o ANALYZE incremental de partição está habilitado por padrão, sem necessidade de configuração manual. Para detalhes, consulte as notas de versão do produto;

• Quando habilitado, a execução de ANALYZE em uma partição filha tentará combinar suas estatísticas com as de outras partições filhas para produzir as estatísticas da tabela pai;

• O pré-requisito para mesclar as estatísticas da tabela pai é que, exceto pela partição filha atualmente analisada, todas as outras partições filhas sob a tabela pai já devem ter estatísticas (incluindo estatísticas de contagem de linhas e de colunas);

• Portanto, você pode:

  • Durante a configuração inicial, execute ANALYZE na tabela pai primeiro. O sistema detectará automaticamente as partições filhas que precisam de ANALYZE e as analisará uma a uma, mesclando finalmente os resultados nas estatísticas da tabela pai;

  • Quando novas partições forem adicionadas posteriormente, execute ANALYZE apenas nas partições filhas recém-adicionadas.

Exemplo breve

BEGIN;
DROP TABLE IF EXISTS t_parent;
CREATE TABLE t_parent(a int, b int) PARTITION BY LIST (a);
CREATE TABLE child1 PARTITION OF t_parent FOR VALUES IN (1);
CREATE TABLE child2 PARTITION OF t_parent FOR VALUES IN (2);
COMMIT;
insert into child1 values (1, 1), (1, 1), (1, 1), (1, 1), (1, 1), (1, 1), (1, 1), (1, 1), (1, 1), (1, 2);
insert into child2 values (2, 1), (2, 2), (2, 3), (2, 4), (2, 5), (2, 5), (2, 5), (2, 5), (2, 5), (2, 5);

-- child2 lacks statistics, so parent table statistics cannot be merged
dbname=# ANALYZE child1;
INFO:  auto merging of leaf partition stats to calculate root partition stats is not possible because partition child2 is not analyzed
ANALYZE

-- child1 already has statistics. After analyzing child2, parent table statistics can be automatically merged
dbname=# ANALYZE child2;
ANALYZE

dbname=# SELECT tablename,
       attname,
       null_frac         AS "NF",
       avg_width,
       n_distinct,
       most_common_vals  AS "MCV",
       most_common_freqs AS "MCV_FRAQ"
FROM   pg_stats
WHERE  tablename = 't_parent';

 tablename | attname | NF | avg_width | n_distinct |  MCV  |  MCV_FRAQ
-----------+---------+----+-----------+------------+-------+------------
 t_parent  | a       |  0 |         4 |          2 | {1,2} | {0.5,0.5}
 t_parent  | b       |  0 |         4 |       -0.2 | {1,5} | {0.45,0.3}
(2 rows)

-- After this, when new partitions are added, you only need to ANALYZE the child partition. Parent table statistics will be automatically merged through sampling the child partition only.

ANALYZE na tabela pai

Às vezes, várias partições filhas de uma tabela particionada sofreram alterações de dados e você não deseja executar o ANALYZE em cada partição filha individualmente. Nesse caso, execute um único ANALYZE na tabela pai.

Quando o ANALYZE incremental de partição está habilitado, a execução manual do ANALYZE na tabela pai faz com que o sistema selecione adaptativamente as partições filhas que precisam de atualizações de estatísticas, em vez de analisar cegamente todas as partições filhas. Esse mecanismo reduz significativamente o custo do ANALYZE para grandes tabelas particionadas, garantindo a precisão das estatísticas.

-- Execute ANALYZE on the parent table
ANALYZE partition_parent_table;

INFO:  will analyze 5 part tables first (stats changed 3, unable-to-merge 2)

ANALYZE para tabelas particionadas lógicas

Uma tabela particionada lógica é um tipo de tabela de partição exclusivo do Hologres. Ao contrário das tabelas particionadas padrão do PostgreSQL (que criam tabelas filhas físicas via PARTITION BY), uma tabela particionada lógica permanece fisicamente como uma única tabela e particiona os dados apenas logicamente com base nos valores da coluna de partição, oferecendo capacidades de gerenciamento de partição mais flexíveis.

A lógica do ANALYZE para tabelas particionadas lógicas é essencialmente a mesma que para tabelas particionadas físicas. A única diferença é que as partições filhas de uma tabela particionada lógica não são tabelas separadas, mas, assim como as partições filhas físicas, cada uma ainda possui suas próprias estatísticas de contagem de linhas e de colunas independentes.

-- Create a logical partitioned table
CREATE TABLE user_events (
    user_id INT NOT NULL,
    event_type TEXT NOT NULL,
    event_date DATE NOT NULL,
    event_data INT
)
LOGICAL PARTITION BY LIST(user_id, event_date);

-- Insert data into different logical partitions
INSERT INTO user_events SELECT 1, 'login', '2024-11-01', i FROM generate_series(1, 1000) i;
INSERT INTO user_events SELECT 1, 'logout', '2024-11-02', i FROM generate_series(1, 1000) i;
INSERT INTO user_events SELECT 2, 'purchase', '2024-11-03', i FROM generate_series(1, 1000) i;
INSERT INTO user_events SELECT 3, 'view', '2024-11-04', i FROM generate_series(1, 1000) i;

-- Execute ANALYZE on the parent table
ANALYZE VERBOSE user_events;

INFO:  will analyze 4 logical partitions first
INFO:  analyzing hologres table "public.user_events" PARTITION (user_id=1,event_date='2024-11-01')
INFO:  analyzing hologres table "public.user_events" PARTITION (user_id=1,event_date='2024-11-02')
INFO:  analyzing hologres table "public.user_events" PARTITION (user_id=2,event_date='2024-11-03')
INFO:  analyzing hologres table "public.user_events" PARTITION (user_id=3,event_date='2024-11-04')
INFO:  try to merge root partition
INFO:  automatically merging leaf partition stats to calculate root partition stats

-- Execute ANALYZE on a single logical partition
ANALYZE user_events PARTITION (user_id=1, event_date='2024-11-01');

-- Execute ANALYZE on multiple logical partitions
ANALYZE user_events
    PARTITION (user_id=1, event_date='2024-11-01')
    PARTITION (user_id=2, event_date='2024-11-03');

-- Execute ANALYZE on specific columns of a specified logical partition
ANALYZE user_events
    PARTITION (user_id=1, event_date='2024-11-01') (user_id, event_type);

SELECT
    unique_name,
    schema_name,
    table_name,
    total_rows,
    sample_rows,
    nattr
FROM hologres_statistic.hg_table_statistic
WHERE table_name = 'user_events'
ORDER BY unique_name;

| unique_name | schema_name | table_name | total_rows | sample_rows | nattr |
|-------------|-------------|------------|------------|-------------| ----- |
| user_events | public | user_events | 4000 | 0 | 4 |
| user_events.a1b2c3d4e5f6... | public | user_events | 1000 | 1000 | 4 |
| user_events.f6e5d4c3b2a1... | public | user_events | 1000 | 1000 | 4 |
| user_events.1234567890ab... | public | user_events | 1000 | 1000 | 4 |
| user_events.abcdef123456... | public | user_events | 1000 | 1000 | 4 |

Configuração e escopo

-- Check whether AUTO ANALYZE is enabled for the current database
SHOW hg_enable_start_auto_analyze_worker;

-- Disable (use only for temporary troubleshooting)
ALTER DATABASE dbname SET hg_enable_start_auto_analyze_worker = OFF;

-- Reset to the default value ON (recommended)
ALTER DATABASE dbname RESET hg_enable_start_auto_analyze_worker;

ALTER TABLE my_table SET (autovacuum_enabled = false);

-- Recommended: reset to restore the default
ALTER TABLE my_table RESET (autovacuum_enabled);

-- Or explicitly set to true (not recommended)
ALTER TABLE my_table SET (autovacuum_enabled = true);

SELECT relname, reloptions FROM pg_class WHERE relname = 'my_table';

 relname  |         reloptions
----------+----------------------------
 my_table | {autovacuum_enabled=false}
(1 row)

-- Disable AUTO ANALYZE for a specific column while still allowing manual ANALYZE
ALTER TABLE t ALTER COLUMN large_text_col SET (enable_auto_analyze = false);

-- Restore default behavior (re-enable)
ALTER TABLE t ALTER COLUMN large_text_col RESET (enable_auto_analyze);

Lógica de acionamento do AUTO ANALYZE

O AUTO ANALYZE combina vários tipos de sinais para determinar se as estatísticas precisam ser atualizadas para uma determinada tabela:

1. Volume de Alteração de Dados

   • Aplica-se apenas a tabelas regulares do Hologres (exclui tabelas externas);

   • Em intervalos de 1 minuto, coleta a contagem de linhas de operações INSERT/UPDATE/DELETE observadas pelo FE em cada tabela. Se a alteração exceder o limiar, um AUTO ANALYZE é acionado (resposta rápida);

   • Em intervalos de 10 minutos, recupera as contagens de linhas alteradas por inserção/atualização/exclusão do mecanismo de armazenamento. Se a alteração exceder o limiar, um AUTO ANALYZE é acionado (calibração precisa);

2. Alterações de Schema

   • Aplica-se apenas a tabelas regulares do Hologres (exclui tabelas externas);

   • Em intervalos de 1 minuto, coleta tabelas com as seguintes alterações e executa o AUTO ANALYZE:

     • ADD / DROP COLUMN;

     • Tabelas particionadas (incluindo tabelas de partição lógica) ATTACH / DETACH partições filhas.

3. Estatísticas Ausentes / Impossibilidade de Mesclar Estatísticas da Tabela de Partição Pai

   • Aplica-se tanto a tabelas regulares do Hologres quanto a tabelas externas;

   • Em intervalos de 1 minuto, coleta tabelas/colunas com estatísticas ausentes e partições filhas que não atendem às condições para mesclagem incremental de estatísticas.

4. Tabelas Externas

   • Aplica-se apenas a tabelas externas introduzidas através de CREATE FOREIGN TABLE, IMPORT FOREIGN SCHEMA ou o mecanismo Auto Load em contextos fora de External Database;

   • Atualmente suporta apenas AUTO ANALYZE para tabelas externas do MaxCompute;

   • Em intervalos de 4 horas, verifica periodicamente todas as tabelas externas no banco de dados. Entre duas verificações, se houver alterações de dados externos (o critério é que o last_modify_timestamp da tabela externa correspondente caia entre os dois intervalos de verificação), um AUTO ANALYZE é acionado.

5. Estatísticas de Fallback

   • Durante a janela da 1:00 às 5:00 da manhã, um AUTO ANALYZE de "fallback" é realizado em tabelas que têm alterações contínuas, mas não acionaram o limiar (>5000 alterações de linhas, <10% de volume de alteração), para capturar desvios na distribuição de dados nas colunas (por exemplo, campos do tipo data gravados após a meia-noite do dia seguinte são completamente diferentes do dia anterior, resultando em mudanças na distribuição).

6. Tabelas de Acesso Frequente (apenas External Database)

   • Após habilitar o parâmetro enable_auto_analyze em um External Database, o sistema Hologres começa a rastrear tabelas acessadas recentemente desde a última inicialização do sistema e as adiciona à lista de observação;

   • Em intervalos de 1 hora, tabelas na lista de observação que são "acessadas frequentemente recentemente" acionam um AUTO ANALYZE;

   • Note que, após uma reinicialização do sistema, a lista de tabelas acessadas é limpa e a gravação recomeça.

AUTO ANALYZE para External Database

• A partir do Hologres V3.0, o Hologres suporta o recurso External Database. Ao criar um External Database, habilite o AUTO ANALYZE (desabilitado por padrão, consulte as notas de versão para detalhes):

-- Enable AUTO ANALYZE when creating an External Database
-- Reference: https://www.alibabacloud.com/help/zh/hologres/developer-reference/create-external-database
CREATE EXTERNAL DATABASE <ext_database_name> WITH
  metastore_type 'maxcompute'
  mc_project 'project_name'
  enable_auto_analyze 'true';

-- Enable AUTO ANALYZE for an existing External Database
ALTER EXTERNAL DATABASE dbname WITH enable_auto_analyze 'true';

• O escopo de metastore_type suportado pelo AUTO ANALYZE no External Database é: dlf, dlf-paimon, dlf-rest, maxcompute.

• Os formatos de tabela suportados pelo AUTO ANALYZE no External Database incluem: MaxCompute, Paimon, Iceberg.

• O AUTO ANALYZE no External Database usa a identidade do Owner do External Database por padrão e emprega autenticação Time-based One-Time Password (TOTP) para executar tarefas de ANALYZE. Se o Owner não tiver permissões suficientes na tabela, o sistema não conseguirá executar as tarefas do AUTO ANALYZE com sucesso.

• Para que uma tabela externa em um External Database seja elegível para o AUTO ANALYZE, as seguintes condições devem ser atendidas:

  • A configuração do External Database hg_enable_start_auto_analyze_worker = on; (o padrão é on)

  • O atributo do External Database enable_auto_analyze está definido como true (não configurado por padrão, o que significa false, consulte as notas de versão para detalhes)

  • O Owner do External Database deve ter permissões de consulta para o Projeto de data lake (se aplicável) e para a tabela

  • A tabela deve ter sido acessada pelo menos uma vez nos últimos 3 dias

    • O AUTO ANALYZE sob External Database monitora apenas tabelas externas que foram acessadas pelo menos uma vez;

    • Após uma reinicialização do sistema, se uma tabela externa for acessada pelo menos uma vez, o sistema AUTO ANALYZE a adiciona à lista de observação e aciona periodicamente o AUTO ANALYZE para essas tabelas;

Limites de recursos do AUTO ANALYZE

Para evitar que as tarefas de AUTO ANALYZE em segundo plano impactem as tarefas do usuário em primeiro plano, o Hologres estabeleceu os seguintes limites de recursos para o recurso AUTO ANALYZE:

• Quando as tarefas do AUTO ANALYZE são executadas, o limite de memória padrão por worker é 4 GB. Se o volume de dados da tabela for muito grande, a amostragem pode exceder o limite de memória, causando falha no SQL de amostragem do AUTO ANALYZE. Nesses casos, apenas as informações de contagem de linhas podem ser coletadas, e as informações de distribuição de colunas (MCV, Histograma, NDV, etc.) não podem ser coletadas. Ajuste auto_analyze_work_memory_mb para alterar esse comportamento. Quanto maior a especificação da instância, maior o limite de memória disponível para o AUTO ANALYZE.

• A concorrência no nível da instância para tarefas de AUTO ANALYZE agendadas simultaneamente normalmente não excede 4 e, em casos extremos, não excede 6.

• Para tarefas de AUTO ANALYZE de partições filhas sob a mesma tabela particionada, a concorrência máxima de agendamento simultâneo é 3.

• Por padrão, o AUTO ANALYZE coleta estatísticas para as primeiras 256 colunas. Se uma tabela tiver mais de 256 colunas, apenas as primeiras 256 são coletadas (para tabelas particionadas, as colunas de partição têm prioridade e serão coletadas mesmo que estejam além da posição 256). Ajuste hg_experimental_auto_analyze_max_columns_count para alterar esse valor.

• As subconsultas SQL de amostragem das tarefas do AUTO ANALYZE são executadas usando um Background Pool de baixa prioridade com concorrência limitada no nível de execução de consulta. Isso faz com que as tarefas do AUTO ANALYZE demorem mais que o ANALYZE manual, o que não deve ser uma preocupação para os usuários.

• Para tabelas externas, o AUTO ANALYZE coleta estatísticas de coluna apenas para colunas de partição (ex.: MCV). Ele não realiza amostragem para coletar estatísticas de colunas diferentes das colunas de partição.

Parâmetros configuráveis do AUTO ANALYZE

Por padrão, o recurso AUTO ANALYZE do Hologres não requer modificações de parâmetros.

Em cenários de negócios raros (como gravações/atualizações de dados pouco frequentes, cargas de trabalho de consulta que não precisam de estatísticas ou aumentos de carga do sistema causados pelo AUTO ANALYZE), os usuários podem modificar certos parâmetros padrão para ajustar o comportamento do AUTO ANALYZE para fins de intervenção ou ajuste parcial de desempenho.

-- Superuser: modify the default AUTO ANALYZE parameters at the database level
ALTER DATABASE dbname SET <GUC> = <values>;

Configuração

Como habilitar a estimativa rápida de contagem de linhas:

-- Disable (use only for temporary troubleshooting or when statistics are not needed for the entire database)
ALTER DATABASE dbname SET hg_experimental_get_fast_num_of_rows = OFF;

-- V3.2 and later: enable (reset to the default value)
ALTER DATABASE dbname RESET hg_experimental_get_fast_num_of_rows;

-- V3.1 and earlier: enable
ALTER DATABASE dbname SET hg_experimental_get_fast_num_of_rows = ON;

Limites de uso

• A estimativa rápida de contagem de linhas aplica-se a tabelas regulares (incluindo tabelas particionadas), tabelas externas em External Database e outros cenários.

• A contagem de linhas estimada pelo recurso de estimativa rápida não é garantida como completamente precisa. Por exemplo, por motivos de desempenho, em tabelas particionadas do Hologres, apenas as estatísticas de contagem de linhas de até 60 partições (por padrão) são usadas para estimar a contagem geral de linhas da tabela particionada.

• Na V4.1.15 e anteriores, a estimativa rápida de contagem de linhas não está habilitada por padrão para tipos de tabela externa (Foreign Table). Ela pode ser habilitada através do parâmetro hg_experimental_enable_foreign_table_get_fast_num_of_rows. Está habilitada por padrão na V4.1.16 e posteriores.

• Para tipos de tabela externa, a estimativa rápida de contagem de linhas suporta apenas tabelas externas do MaxCompute, tabelas externas do Paimon e tabelas externas do Iceberg.

Exemplos

1. Exemplo de hg_experimental_get_fast_num_of_rows

Se uma tabela não tiver estatísticas, habilitar a estimativa rápida de contagem de linhas pode fornecer contagens de linhas mais precisas. (Habilitado por padrão no Hologres V3.2 e posteriores)

-- V3.2+
create table test_tbl (a int);
insert into test_tbl select * from generate_series (1, 999);

-- Accurate row count estimation (rows=999)
explain select count(1) from test_tbl ;
                                       QUERY PLAN
----------------------------------------------------------------------------------------
 Final Aggregate  (cost=0.00..5.00 rows=1 width=8)
   ->  Gather  (cost=0.00..5.00 rows=10 width=8)
         ->  Partial Aggregate  (cost=0.00..5.00 rows=10 width=8)
               ->  Local Gather  (cost=0.00..5.00 rows=20 width=8)
                     ->  Partial Aggregate  (cost=0.00..5.00 rows=20 width=8)
                           ->  Seq Scan on test_tbl  (cost=0.00..5.00 rows=999 width=1)

A seguir, um caso real de produção:

Sem esse recurso habilitado, se uma tabela não tiver estatísticas, o nó Scan no plano de consulta mostrará rows=1000 (indicando que não há estatísticas disponíveis e o plano é gerado com base na estimativa padrão de 1000 linhas).

Após habilitar esse recurso, se uma tabela não tiver estatísticas, as linhas do nó Scan no plano de consulta não serão iguais a 1000 (o sistema chamou os metadados do mecanismo de armazenamento subjacente para obter a contagem de linhas da tabela).

Parâmetros configuráveis para estimativa rápida de contagem de linhas

Como identificar registros de ANALYZE e AUTO ANALYZE no query log

O ANALYZE e o AUTO ANALYZE, juntamente com suas instruções SQL de amostragem, são registrados separadamente no Query Log.

Os registros de execução têm as seguintes características no Query Log:

O ANALYZE e seu SQL de amostragem são associados através dos comentários no campo query ou através de extended_info->>'source_query_id'.

SELECT query_id,
       extended_info->>'src_query_id' as "source query id",
       application_name,
       status,
       duration
FROM   hologres.hg_query_log
WHERE  query_start >= now() - interval '1 hour'
  AND  application_name IN ('AutoAnalyze', 'Hologres SQL Generated BY AUTO ANALYZE')
ORDER BY query_start DESC
LIMIT  2;
      query_id       |   source query id   |            application_name            | status  | duration
---------------------+---------------------+----------------------------------------+---------+----------
 1004019226350863009 | 1004019226350778807 | Hologres SQL Generated BY AUTO ANALYZE | SUCCESS |      119
 1004019226350778807 |                     | AutoAnalyze                            | SUCCESS |     3276

Exemplos de consulta

• Visualizar registros recentes de execução do AUTO ANALYZE

SELECT usename,
       status,
       duration,
       query_start,
       query_end,
       query,
       application_name
FROM   hologres.hg_query_log
WHERE  query_start >= now() - interval '1 hour'
  AND  application_name IN ('AutoAnalyze')
ORDER BY query_start DESC
LIMIT  20;

       query_id,
       extended_info->>'src_query_id' as "source query id"

• Visualizar o histórico de execução do AUTO ANALYZE de uma tabela específica

SELECT status,
       duration,
       query_start,
       query
FROM   hologres.hg_query_log
WHERE  query_start >= now() - interval '1 day'
  AND  application_name IN ('AutoAnalyze')
  AND  query LIKE '%my_table_name%'
ORDER BY query_start DESC;

• Resumir a visão geral da execução do AUTO ANALYZE nos últimos 3 dias

SELECT query_date,
       status,
       COUNT(*)          AS task_count,
       AVG(duration)     AS avg_duration_ms,
       MAX(duration)     AS max_duration_ms
FROM   hologres.hg_query_log
WHERE  query_start >= CURRENT_DATE::timestamptz - interval '2 day'
  AND  application_name IN ('AutoAnalyze')
  AND  command_tag = 'ANALYZE'
  AND  (status = 'SUCCESS' OR (
            message NOT LIKE '%does not exist%'
        AND message NOT LIKE '%retry later%'))
GROUP BY query_date, status
ORDER BY query_date DESC;

• Visualizar tarefas falhas do AUTO ANALYZE no último dia

SELECT query_start,
       duration,
       message,
       query
FROM   hologres.hg_query_log
WHERE  query_start >= now() - interval '1 day'
  AND  application_name IN ('AutoAnalyze', 'Hologres SQL Generated BY AUTO ANALYZE')
  AND  status != 'SUCCESS'
  AND  (message NOT LIKE '%does not exist%'
        AND message NOT LIKE '%retry later%')
ORDER BY query_start DESC;

Observações

• Como as conexões do AUTO ANALYZE são iniciadas com uma identidade de administrador interno, usuários regulares precisam da função pg_read_all_stats ou privilégios de administrador de banco de dados para visualizar registros completos de execução do AUTO ANALYZE.

• Se você notar que não há registros do AUTO ANALYZE no Query Log por um longo período, verifique se a configuração do AUTO ANALYZE está habilitada.

Visualizando estatísticas de tabela (hologres_statistic.hg_table_statistic)

As estatísticas de tabela são armazenadas na tabela hologres_statistic.hg_table_statistic e também podem ser observadas nas tabelas do sistema.

1. Consulte esta tabela para obter as estatísticas do ANALYZE mais recente.

SELECT schema_name,                -- Table schema
       table_name,                 -- Table name
       user_name,                  -- User who last ran ANALYZE
       schema_version,             -- Table schema version at last ANALYZE
       total_rows,                 -- Row count at last ANALYZE
       sample_rows,                -- Sample rows used at last ANALYZE
       analyze_timestamp,          -- Completion time of last ANALYZE
       analyze_count               -- Total ANALYZE count so far
FROM   hologres_statistic.hg_table_statistic
WHERE  unique_name = hologres.hg_internal_statistic_unique_name ('schemaname', 'tablename')
ORDER BY analyze_timestamp DESC;

-- Sample output
 schema_name | table_name |    user_name     | schema_version | total_rows | sample_rows |  analyze_timestamp  | analyze_count
-------------+------------+------------------+----------------+------------+-------------+---------------------+---------------
 public      | test_fnr   |   BASIC$test_fnr |             -1 |        999 |         999 | 2026-03-02 22:05:29 |             2
(1 row)

V3.1 e anteriores:

• Cada tabela tem de 0 a n registros na tabela hologres_statistic.hg_table_statistic. 0 registros significa que o ANALYZE nunca foi realizado, e 1 ou mais registros significam que o ANALYZE foi executado.

• Se houver dois ou mais registros, o schema_version dos dois registros deve ser diferente, pois alterações no schema da tabela (como ADD COLUMN, CALL SET_TABLE_PROPERTY, etc.) geram uma nova versão, o que adiciona um novo registro de estatísticas. O registro correspondente ao schema_version antigo não é mais usado.

• O seguinte resultado de consulta de exemplo mostra que a mesma tabela tem 2 registros, e o schema_version do segundo registro é inferior ao do primeiro. O segundo registro é, portanto, inválido e não será usado, e você não precisa prestar atenção nele. O Hologres atualmente não limpa registros históricos expirados na tabela hg_table_statistic, e os usuários não precisam se preocupar com dados antigos.

 schema_name | table_name |    user_name     | schema_version | total_rows | sample_rows |  analyze_timestamp  | analyze_count
-------------+------------+------------------+----------------+------------+-------------+---------------------+---------------
 public      | test_fnr   |   BASIC$test_fnr |             13 |        999 |         999 | 2026-03-01 18:05:29 |             2
 public      | test_fnr   |   BASIC$test_fnr |             12 |        999 |         999 | 2026-03-01 08:05:29 |             1
(1 row)

V3.1 e posteriores:

• Cada tabela tem de 0 a 1 registro na tabela hologres_statistic.hg_table_statistic. 0 registros significa que o ANALYZE nunca foi realizado, e 1 registro significa que o ANALYZE foi executado.

• O schema_version é definido uniformemente como -1 (representando Deprecated).

• Isso significa que muitas operações DDL não invalidam mais as estatísticas. Por exemplo, CALL SET_TABLE_PROPERTY não reacinará o AUTO ANALYZE, e as estatísticas existentes continuarão a ser usadas. Comparado ao Hologres V3.0 e anteriores, a frequência de acionamento do AUTO ANALYZE é significativamente reduzida.

1. Consultando contagem de linhas e outras estatísticas

As informações de contagem de linhas são registradas no campo reltuples da tabela pg_class.

-- relallvisible > 0: the table has row count statistics
-- relallvisible = 0: the row count is unknown; do not rely on reltuples
-- relallvisible < 0: the table has no statistics
SELECT relallvisible, reltuples FROM pg_class WHERE relname = 'test_table';

1. Consultando estatísticas de coluna

Consultando a view pg_stats, obtenha as estatísticas de todas as colunas da tabela atual. Por exemplo, para obter as estatísticas da coluna ds de test_table:

select * from pg_stats where tablename = 'test_table' and attname = 'ds';

 schemaname | tablename  | attname | inherited | null_frac | avg_width | n_distinct | most_common_vals | most_common_freqs | histogram_bounds | correlation | most_common_elems | most_common_elem_freqs | elem_count_histogram
------------+------------+---------+-----------+-----------+-----------+------------+------------------+-------------------+------------------+-------------+-------------------+------------------------+----------------------
 public     | test_table | ds      | f         |         0 |         4 |          1 | {20241104}       | {1}               |                  |             |                   |                        |
(1 row)

Visualizando tabelas com estatísticas ausentes

O Hologres fornece a view HG_STATS_MISSING (o nome real da view pode variar conforme a versão) para verificar tabelas no banco de dados atual que estão sem estatísticas, facilitando a identificação de objetos que precisam de ANALYZE complementar.

Problemas comuns e solução de problemas

1. Possíveis razões para 0 registros retornados da tabela hologres_statistic.hg_table_statistic:

• O ANALYZE nunca foi executado (nem manualmente nem pelo AUTO ANALYZE);

• O AUTO ANALYZE não está funcionando ou a tabela não atendeu às condições de acionamento;

Ações recomendadas:

• Primeiro, execute manualmente:

ANALYZE schema_name.table_name;

• Se a tabela ainda não puder ser coberta pelo AUTO ANALYZE por um longo período, verifique a configuração do AUTO ANALYZE e os parâmetros GUC ou entre em contato com o suporte técnico.

1. Possíveis razões para um analyze_timestamp obviamente desatualizado:

• O AUTO ANALYZE foi desabilitado ou restrito (como autovacuum_enabled = false);

• O AUTO ANALYZE tem recursos insuficientes ou falhou (pode ser investigado em conjunto com logs/monitoramento);

Ações recomendadas:

• Execute o ANALYZE manualmente uma vez e observe os resultados;

• Verifique:

  • Se hg_enable_start_auto_analyze_worker está habilitado;

  • Se autovacuum_enabled = false foi definido erroneamente ou se restrições GUC relacionadas são muito rigorosas;

  • Verifique se há erros relacionados a tarefas do AUTO ANALYZE no Query Log.

1. Estimativa anormal de contagem de linhas em planos de consulta (significativamente pequena ou grande demais)

• Verifique se a tabela correspondente está sem estatísticas ou com estatísticas desatualizadas;

• Verifique se as colunas de predicado têm estatísticas (pg_stats) e execute o ANALYZE no nível de coluna em colunas críticas;

• Verifique se o recurso de estimativa rápida de contagem de linhas foi desabilitado ou não habilitado.

1. Estatísticas pai-filho inconsistentes para tabelas particionadas ou estatísticas ausentes na tabela pai

• Sintoma: A tabela pai da partição não tem registros em hologres_statistic.hg_table_statistic, ou total_rows é significativamente menor que a soma de todas as contagens de linhas das tabelas filhas, ou a distribuição MCV das estatísticas da coluna de partição da tabela pai está desatualizada (por exemplo, a coluna ds em pg_stats está sem a distribuição de ontem);

• Pontos de solução de problemas:

  • Verifique se o ANALYZE / AUTO ANALYZE incremental de partição foi desabilitado;

SHOW hg_experimental_enable_incremental_analyze;
SHOW hg_experimental_enable_incremental_auto_analyze;

• Use a view HG_STATS_MISSING para verificar se há tabelas filhas que não podem ser mescladas;

• Verifique se há erros relacionados a tarefas do AUTO ANALYZE no Query Log;

• Execute manualmente ANALYZE child_table; em tabelas filhas com estatísticas ausentes ou execute ANALYZE partition_parent_table; na tabela pai fora do horário de pico para permitir que o sistema preencha e mescle as estatísticas.

1. Certas colunas não têm estatísticas em pg_stats

• Sintoma: A tabela tem a coluna, mas as estatísticas correspondentes da coluna não podem ser encontradas na view pg_stats.

• Pontos de solução de problemas:

  • Verifique se as estatísticas foram desabilitadas através de atributos de coluna (enable_analyze = false ou enable_auto_analyze = false);

SELECT attoptions
  FROM pg_attribute
 WHERE attrelid = 'tablename'::regclass::oid
   AND attname = 'columnname';
-[ RECORD 1 ]----------------------
attoptions | {enable_analyze=false}

• Confirme se a coluna participou do ANALYZE (manual ou AUTO ANALYZE). Se necessário, execute ANALYZE table_name(col_name); no nível da coluna;

SELECT query_id,
       application_name,
       status,
       query_start,
       query
FROM   hologres.hg_query_log
WHERE  query_start >= now() - interval '1 hour'
  AND  application_name IN ('Hologres SQL Generated BY ANALYZE', 'Hologres SQL Generated BY AUTO ANALYZE')
  AND  query like '%tablename%'
ORDER BY query_start DESC
LIMIT  2;

• Se a coluna é de um tipo especial (bytea, jsonb).

• Se a tabela executou o AUTO ANALYZE, mas nenhuma coluna tem estatísticas, considere se a tarefa do AUTO ANALYZE foi executada anormalmente. Por exemplo, verifique se o AUTO ANALYZE atingiu o tempo limite. Como auto_analyze_work_statement_timeout tem padrão de 1 hora, se a tarefa do AUTO ANALYZE em hologres.hg_query_log tiver uma duração >= 3600000, nesse caso, apenas as informações de contagem de linhas são coletadas sem estatísticas de coluna.

1. O AUTO ANALYZE foi executado, mas o plano de consulta não melhorou significativamente

• Sintoma: Registros do AUTO ANALYZE para uma tabela específica podem ser vistos em hologres.hg_query_log, mas o plano de consulta real ainda usa estimativas de contagem de linhas obviamente irracionais ou ordem de Join;

• Pontos de solução de problemas:

  • Verifique se o AUTO ANALYZE atingiu o tempo limite. Como auto_analyze_work_statement_timeout tem padrão de 1 hora, se a tarefa do AUTO ANALYZE em hologres.hg_query_log tiver uma duração >= 3600s, nesse caso, apenas as informações de contagem de linhas são coletadas sem estatísticas de coluna.

  • Verifique se há Hints, ordens de Join fixas ou GUCs legados no nível de sessão (como enable_nestloop, etc.) interferindo nas escolhas do otimizador;

  • Execute um ANALYZE manual em tabelas/colunas críticas e execute a consulta novamente. Se ainda não houver melhoria, recomenda-se investigar mais a fundo em conjunto com o Query Log, logs do FE ou relatando ao suporte técnico.

1. Problemas de OOM / limite de memória excedido causados por estatísticas

• Sintoma: Um Join complexo de múltiplas tabelas reporta erro Query executor exceeded total memory limitation ..., ou o plano seleciona uma estratégia de Join extremamente irracional (como uma tabela grande dirigindo um Nested Loop de tabela grande, etc.);

• Pontos de solução de problemas:

  • Confirme se as tabelas relacionadas estão sem estatísticas ou com estatísticas severamente desatualizadas (combinando registros em hg_table_statistic e registros de execução do AUTO ANALYZE);

  • Execute ANALYZE no nível de coluna em colunas de Join e colunas de filtro. Se necessário, aumente a precisão da amostragem ou habilite o recurso de estimativa rápida de contagem de linhas;

  • Se o problema ocorrer apenas em certas distribuições de dados extremas ou cenários de pico, consulte o suporte técnico para avaliar se são necessários ajustes no modelo de estatísticas ou GUCs relacionados (como limiares do AUTO ANALYZE, limites de memória, etc.).

ANALYZE manual e computação Serverless

• hg_serverless_computing_enable_analyze_statement

  • Descrição: Controla se instruções ANALYZE manuais podem ser executadas através de tarefas Serverless;

  • Comportamento:

    • Quando definido como on (padrão), o sistema permite que instruções ANALYZE sejam descarregadas para recursos de computação Serverless para execução, minimizando o impacto das tarefas de estatísticas na própria instância;

    • Quando definido como off, o ANALYZE é executado nos recursos locais da instância.

  • Recomendações típicas:

    • Em instâncias Serverless, o padrão é on, permitindo que apenas recursos Serverless concluam tarefas de estatísticas;

    • Ao solucionar problemas ou quando houver requisitos especiais para uso de recursos, defina temporariamente como off para executar explicitamente o ANALYZE em recursos locais.

AUTO ANALYZE e computação Serverless

Ao gerar tarefas de AUTO ANALYZE, o sistema determina se deve usar recursos Serverless e como controlar o comportamento da tarefa Serverless com base nos seguintes GUCs:

• hg_auto_analyze_run_with_serverless_computing

  • Descrição: Se deve executar tarefas de AUTO ANALYZE através de recursos de computação Serverless. O padrão é off para instâncias regulares e on para instâncias Serverless.

  • Comportamento:

    • Quando definido como on, as tarefas de AUTO ANALYZE enviarão computações de amostragem para o pool de recursos Serverless;

    • Quando definido como off, o AUTO ANALYZE continua a concluir as estatísticas através dos recursos locais da instância.

-- Set at the database level
ALTER DATABASE datname SET hg_auto_analyze_run_with_serverless_computing = on;

• hg_auto_analyze_serverless_computing_query_priority

  • Descrição: A prioridade das tarefas Serverless de AUTO ANALYZE, variando de 1~5. Valores maiores indicam maior prioridade. O padrão é 2;

  • Comportamento:

    • Quando o AUTO ANALYZE Serverless está habilitado, o sistema define a prioridade correspondente para cada tarefa de estatísticas através de SET hg_experimental_serverless_tasks_query_priority = <value>;;

    • Isso é aplicável ao compartilhar um pool de recursos com outras tarefas Serverless (como ETL e consultas offline) para controlar a capacidade de preempção das tarefas de estatísticas na fila geral;

  • Recomendações:

    • Em ambientes de produção, normalmente é mantido em uma prioridade média (como o padrão 2 ou moderadamente aumentado para 3) para evitar competir por muitos recursos com jobs de negócios principais;

    • Para cenários com requisitos extremamente altos de atualidade de estatísticas e recursos Serverless suficientes, a prioridade pode ser adequadamente aumentada.

• hg_auto_analyze_serverless_computing_enable_persisted_snapshot

  • Descrição: Se deve usar um snapshot persistente (persisted snapshot) em tarefas Serverless de AUTO ANALYZE, ou seja, controlar se deve pular flush adicional através de SET hg_experimental_enable_persisted_snapshot = on/off;;

  • O padrão é off para instâncias não-Serverless e on para instâncias Serverless.

  • Comportamento:

    • Quando definido como on, as tarefas de estatísticas tentarão reutilizar o snapshot persistente, reduzindo a necessidade de acionar um flush. Isso é mais adequado para estatísticas de alta frequência ou cenários com um grande número de tabelas particionadas;

    • Quando definido como off, as tarefas de estatísticas tentarão usar um snapshot mais atualizado, o que é adequado para cenários com maiores requisitos de consistência ou isolamento de versão específico.

  • Recomendações:

    • Não ajuste a menos que seja necessário.

Recomendações de uso para cenários de computação Serverless

1. Priorize o uso de Serverless Computing para lidar com tarefas pesadas de ANALYZE

   • Ao realizar ANALYZE em tabelas ou tabelas externas com volumes de dados muito grandes, recomenda-se habilitar:

     • ANALYZE manual: set hg_computing_resource = 'serverless'; ANALYZE my_table;;

     • AUTO ANALYZE: ALTER DATABASE mydb SET hg_auto_analyze_run_with_serverless_computing = on;;

   • Isso migra a pressão de computação de estatísticas para o pool de recursos Serverless, reduzindo a interferência em consultas online na instância.

   • Defina a prioridade da tarefa Serverless de AUTO ANALYZE com base na importância do negócio

     • Em instâncias Serverless, para bancos de dados de negócios críticos que são sensíveis à atualidade das estatísticas e dependem das estatísticas mais recentes, aumente adequadamente hg_auto_analyze_serverless_computing_query_priority;

     • Em instâncias regulares, usar recursos locais para o AUTO ANALYZE geralmente é suficiente.

   • Siga o princípio de "teste em pequenos passos" antes de ajustar parâmetros

     • Os GUCs relacionados ao Serverless Computing também são parâmetros avançados. Antes de fazer ajustes, recomenda-se primeiro verificar em um ambiente de teste ou staging:

       • Observe o enfileiramento e a duração de execução das tarefas de estatísticas no pool de recursos Serverless;

       • Monitore o impacto na latência e no uso de recursos das consultas de negócios principais;

     • Após confirmar que não há efeitos colaterais significativos, implemente no ambiente de produção por banco de dados ou em fases.