ANALYZE — coleta estatísticas sobre um banco de dados
ANALYZE [ (opção[, ...] ) ] [tabela_e_colunas[, ...] ] ondeopçãopode ser uma entre: VERBOSE [booleano] SKIP_LOCKED [booleano] BUFFER_USAGE_LIMITtamanhoetabela_e_colunasé: [ ONLY ]nome_da_tabela[ * ] [ (nome_da_coluna[, ...] ) ]
O comando ANALYZE coleta estatísticas sobre
o conteúdo das tabelas do banco de dados, e armazena os resultados
no catálogo do sistema pg_statistic.
Posteriormente, o planejador de consultas usa estas estatísticas para
ajudar a determinar os planos de execução mais eficientes para as
consultas.
Sem a lista de
tabela_e_colunas,
o comando ANALYZE processa cada tabela e visão
materializada no banco de dados corrente, que o usuário corrente tem
permissão para analisar.
Com a lista, o comando ANALYZE processa apenas
esta(s) tabela(s).
Além disso, é possível fornecer uma lista de nomes de colunas para a
tabela, caso em que são coletadas estatísticas apenas dessas colunas.
VERBOSE
Ativa a exibição de mensagens de progresso no nível
INFO.
SKIP_LOCKED
Especifica que o comando ANALYZE não deve
aguardar por nenhum bloqueio conflitante ser liberado ao iniciar
o trabalho em uma relação: se a relação não puder ser bloqueada
imediatamente, a relação será ignorada.
Note que mesmo com esta opção, o comando ANALYZE
ainda pode ficar bloqueado ao abrir os índices da relação, ou
ao acessar linhas de amostra de partições, filhas em herança da
tabela, e alguns tipos de tabelas estrangeiras.
Além disso, embora o comando ANALYZE normalmente
processe todas as partições das tabelas particionadas especificadas,
esta opção fará com que o comando ANALYZE ignore
todas as partições, se houver um bloqueio conflitante na tabela
particionada.
BUFFER_USAGE_LIMIT
Especifica o tamanho da área de memória
(Estratégia de Acesso ao Buffer)
usada pelo comando ANALYZE.
Este tamanho é usado para calcular o número de
buffers compartilhados que serão
reutilizados como parte dessa estratégia.
0 desativa a
Estratégia de Acesso ao Buffer.
Quando esta opção não é especificada, o comando
ANALYZE usa o valor de
vacuum_buffer_usage_limit.
Configurações mais altas podem permitir que o comando
ANALYZE seja executado mais rapidamente,
mas uma configuração muito grande pode fazer com que muitas
outras páginas úteis sejam removidas dos
buffers compartilhados.
O valor mínimo é 128 kB e o valor máximo é
16 GB.
booleano
Especifica se a opção selecionada deve ser ativada ou desativada.
Pode ser escrito TRUE, ON, ou
1, para ativar a opção, e FALSE,
OFF, ou 0, para desativá-la.
O valor booleano
também pode ser omitido, caso em que é assumido como
TRUE.
tamanho
Especifica uma quantidade de memória em kilobytes.
Os tamanhos também podem ser especificados como uma cadeia de
caracteres contendo o tamanho numérico seguido por qualquer
uma das seguintes unidades de memória: B (bytes),
kB (kilobytes), MB (megabytes),
GB (gigabytes) ou TB (terabytes).
nome_da_tabela
O nome (opcionalmente qualificado pelo esquema) da
tabela ou visão materializada a ser analisada.
Se omitido, todas as tabelas regulares, tabelas particionadas
e visões materializadas no banco de dados corrente serão analisadas
(mas não as tabelas estrangeiras).
Se for especificado ONLY antes do nome da
tabela, somente esta tabela será analisada.
Se não for especificado ONLY, a tabela e todas
as suas tabelas filhas ou partições herdadas (se houver) serão
analisadas.
Opcionalmente, pode ser especificado * após
o nome da tabela para indicar explicitamente que as tabelas
filhas de herança (ou partições) devem ser analisadas.
nome_da_colunaO nome da coluna específica a ser analisada. Por padrão, todas as colunas.
Quando é especificado VERBOSE, o comando
ANALYZE emite mensagens de progresso, indicando
qual tabela está sendo processada no momento.
Também são mostradas várias estatísticas sobre as tabelas.
Para analisar uma tabela, normalmente é necessário possuir o
privilégio MAINTAIN na tabela.
Entretanto, os donos de bancos de dados têm permissão para analisar
todas as tabelas em seus bancos de dados, exceto os catálogos
compartilhados.
O comando ANALYZE irá ignorar quaisquer tabelas
que o usuário que fez a chamada não tenha permissão para analisar.
As tabelas estrangeiras são analisadas apenas quando explicitamente
selecionadas.
Nem todos os empacotadores de dados estrangeiros oferecem suporte
ao comando ANALYZE.
Se o empacotador da tabela não oferecer suporte ao comando
ANALYZE, este mostrará uma advertência,
e não fará nada.
Na configuração padrão do PostgreSQL,
o processo de limpeza automática (veja Autovacuum)
cuida da análise automática das tabelas quando elas são carregadas
pela primeira vez com dados, e conforme mudam durante a operação regular.
Quando a limpeza automática está desativada, é uma boa ideia executar
o comando ANALYZE periodicamente, ou logo após
fazer mudanças importantes no conteúdo da tabela.
Estatísticas precisas ajudarão o planejador a escolher o plano de
consulta mais apropriado e, assim, melhorar a velocidade do
processamento da consulta.
Uma estratégia comum em bancos de dados usados principalmente para
leitura, é executar os comandos VACUUM e
ANALYZE uma vez por dia durante um horário de
baixo uso.
(Isto não será suficiente se houver muita atividade de atualização.)
Enquanto o comando ANALYZE estiver em execução, o
search_path será temporariamente alterado para
pg_catalog, pg_temp.
O comando ANALYZE requer apenas um bloqueio
de leitura na tabela a ser analisada, portanto, pode ser executado
em paralelo com outras atividades na tabela que não sejam de
DDL.
As estatísticas coletadas pelo comando ANALYZE
geralmente incluem uma lista de alguns dos valores mais repetidos
em cada coluna, e um histograma mostrando a distribuição aproximada
dos dados em cada coluna.
Um deles, ou os dois, podem ser omitidos se o comando
ANALYZE não considerar interessante (por exemplo,
em uma coluna de chave de unicidade não há valores repetidos), ou se
o tipo de dados da coluna não der suporte aos operadores apropriados.
Há mais informações sobre as estatísticas em
Tarefas de rotina de manutenção de banco de dados.
Para tabelas grandes, o comando ANALYZE obtém uma
amostra aleatória do conteúdo da tabela, em vez de examinar cada linha.
Isto permite que até mesmo tabelas muito grandes sejam analisadas
em um curto espaço de tempo.
Note, no entanto, que as estatísticas são apenas aproximadas, mudando
ligeiramente cada vez que o comando ANALYZE é
executado, mesmo que o conteúdo real da tabela não tenha mudado.
Isto pode resultar em pequenas alterações nos custos estimados pelo
planejador mostrados no comando EXPLAIN.
Em raras situações, este não-determinismo fará com que as opções
de planos de consulta do planejador sejam alteradas após a execução
do comando ANALYZE.
Para evitar isto, deve ser aumentado o quantitativo de estatísticas
coletadas pelo comando ANALYZE, conforme descrito
abaixo.
A extensão da análise pode ser controlada ajustando a variável de
configuração default_statistics_target,
ou coluna por coluna definindo o quantitativo de estatísticas por
coluna com ALTER TABLE ...
ALTER COLUMN ... SET STATISTICS.
O quantitativo define o número máximo de entradas na lista de
valores mais repetidos, e o número máximo de classes no histograma.
O quantitativo padrão é 100, mas pode ser ajustado para cima ou para
baixo para compensar a precisão das estimativas do planejador em
relação ao tempo gasto pelo comando ANALYZE,
e a quantidade de espaço ocupado na tabela
pg_statistic .
Em particular, definir o quantitativo de estatísticas como zero
desativa a coleta de estatísticas para esta coluna.
Pode ser útil fazer isto em colunas que nunca são usadas como parte
das cláusulas de consulta WHERE,
GROUP BY ou ORDER BY,
já que o planejador não terá uso para estatísticas nessas colunas.
O maior quantitativo de estatísticas entre as colunas que estão sendo
analisadas determina o número de linhas da tabela amostradas para
preparar as estatísticas.
Aumentar o quantitativo causa um aumento proporcional no tempo e
espaço necessários para executar o comando ANALYZE.
Um dos valores estimados pelo comando ANALYZE
é o número de valores distintos que aparecem em cada coluna.
Por ser examinado apenas um subconjunto das linhas, esta estimativa
às vezes pode ser bastante imprecisa, mesmo com o maior quantitativo
de estatísticas possível.
Se esta imprecisão levar a planos de consulta ruins, um valor mais
preciso pode ser determinado manualmente e instalado usando
ALTER TABLE ... ALTER COLUMN
... SET (n_distinct = ...).
Se a tabela que está sendo analisada tiver uma ou mais filhas,
o comando ANALYZE irá coletar as estatísticas
duas vezes: uma vez apenas nas linhas da tabela mãe, e uma segunda
vez nas linhas da tabela mãe com todas as suas filhas.
Este segundo conjunto de estatísticas é necessário ao planejar
consultas que percorrem toda a árvore de herança.
Entretanto, o processo trabalhador de auto-limpeza
(daemon autovacuum)
só irá considerar inserções ou atualizações na própria tabela mãe
ao decidir se deve acionar uma análise automática para esta tabela.
Se esta tabela sofrer inserções ou atualizações raramente,
as estatísticas de herança não estarão atualizadas, a menos que
se execute o comando ANALYZE manualmente.
Para tabelas particionadas, o comando ANALYZE
coleta estatísticas por meio de amostragem de linhas de todas as
partições.
Por padrão, o comando ANALYZE também irá coletar
e atualizar recursivamente as estatísticas de cada partição.
Pode ser usada a palavra-chave ONLY para
desativar este comportamento.
O processo trabalhador de auto-limpeza não processa tabelas
particionadas, nem irá processar as mães da herança
quando apenas as filhas forem modificadas.
Geralmente é necessário executar periodicamente o comando
ANALYZE manualmente para manter as estatísticas
da hierarquia da tabela atualizadas.
Se quaisquer tabelas filhas ou partições forem tabelas estrangeiras,
cujos empacotadores de dados estrangeiros não oferecem suporte ao
comando ANALYZE, estas tabelas serão ignoradas
durante a coleta de estatísticas de herança.
Se a tabela que está sendo analisada estiver inteiramente vazia,
o comando ANALYZE não irá registrar novas
estatísticas para esta tabela.
Todas as estatísticas existentes serão mantidas.
Cada processo servidor executando o comando
ANALYZE irá relatar seu progresso na visão
pg_stat_progress_analyze.
Veja Relatório de progresso do ANALYZE para obter detalhes.
Não existe o comando ANALYZE no padrão
SQL.
A seguinte sintaxe era usada antes da versão 11 do PostgreSQL e ainda tem suporte:
ANALYZE [ VERBOSE ] [ tabela_e_colunas [, ...] ]