Descrição

O comando CLUSTER instrui o PostgreSQL a agrupar a tabela especificada por nome_da_tabela com base no índice especificado por nome_do_índice. O índice já deverá estar presente na tabela.

Quando a tabela é agrupada, ela é reordenada fisicamente com base nas informações do índice. O agrupamento é uma operação de uma só vez: quando a tabela é atualizada posteriormente, as alterações não são agrupadas. Ou seja, nenhuma tentativa é feita para armazenar linhas novas ou atualizadas de acordo com sua ordem no índice. (Se for desejado, pode-se reagrupar periodicamente executando o comando novamente. Além disso, definir o parâmetro de armazenamento fillfactor da tabela para menos de 100% pode ajudar a preservar a ordem de agrupamento durante as atualizações, porque as linhas atualizadas são mantidas na mesma página, se houver espaço suficiente disponível.)

Quando a tabela é agrupada, o PostgreSQL lembra por qual índice ela foi agrupada. A forma CLUSTER nome_da_tabela reagrupa a tabela usando o mesmo índice de antes. Também podem ser usadas as formas CLUSTER ou SET WITHOUT CLUSTER do comando ALTER TABLE para definir o índice a ser usado para futuras operações de agrupamento, ou para limpar qualquer configuração anterior.

O comando CLUSTER sem nome_da_tabela reagrupa todas as tabelas previamente agrupadas no banco de dados corrente para as quais o usuário que o executa possui privilégios. Esta forma do comando CLUSTER não pode ser executada dentro de um bloco de transação.

Quando a tabela está sendo agrupada, é adquirido um bloqueio ACCESS EXCLUSIVE nela. Isto evita que quaisquer outras operações de banco de dados (leituras e escritas) operem na tabela até que o comando CLUSTER esteja concluído.

Parâmetros

Notas

Para agrupar uma tabela, é necessário possuir o privilégio MAINTAIN na tabela.

Nos casos onde são acessadas linhas únicas aleatoriamente na tabela, a ordem real dos dados na tabela não é importante. Entretanto, se alguns dados são mais acessados do que outros, e há um índice que os agrupa, então há benefício em usar o comando CLUSTER. Se estiver sendo solicitado um intervalo de valores indexados de uma tabela, ou um único valor indexado com várias linhas correspondentes, o comando CLUSTER ajudará, porque uma vez que o índice identifica a página da tabela para a primeira linha correspondente, todas as outras linhas correspondentes provavelmente já estarão na mesma página da tabela, portanto, se economiza acesso a disco, acelerando a consulta.

O comando CLUSTER pode reordenar a tabela usando uma varredura de índice no índice especificado, ou (se o índice for uma Árvore-B) uma varredura sequencial seguida de classificação. O comando tenta escolher o método que será mais rápido, com base nos parâmetros de custo do planejador, e nas informações estatísticas disponíveis.

Enquanto o comando CLUSTER está executando, o search_path é temporariamente mudado para pg_catalog, pg_temp.

Quando é usada a varredura de índice, é criada uma cópia temporária da tabela que contém os dados da tabela na ordem do índice. Também são criadas cópias temporárias de cada índice na tabela. Portanto, é necessário espaço livre em disco pelo menos igual à soma do tamanho da tabela com os tamanhos dos índices.

Quando são usadas varredura e classificação sequenciais, também é criado um arquivo de classificação temporário, de modo que o requisito de espaço temporário máximo seja o dobro do tamanho da tabela, mais os tamanhos dos índices. Este método é geralmente mais rápido que o método de varredura de índice, mas se o requisito de espaço em disco for inaceitável, pode-se desativar esta opção definindo enable_sort temporariamente como off .

É aconselhável definir maintenance_work_mem para um valor razoavelmente grande (mas não acima da quantidade de RAM que se pode dedicar à operação CLUSTER) antes agrupamento.

Como o planejador registra estatísticas sobre a ordem das tabelas, é recomendável executar o comando ANALYZE na tabela recém-agrupada. Caso contrário, o planejador pode fazer escolhas ruins de planos de consulta.

Como o comando CLUSTER se lembra de quais índices estão agrupados, pode-se agrupar as tabelas que se deseja agrupar manualmente na primeira vez e, depois, configurar um script de manutenção periódica executando o comando CLUSTER sem nenhum parâmetro, para que as tabelas desejadas sejam reagrupadas periodicamente.

Cada processo servidor executando o comando CLUSTER relata seu progresso na visão pg_stat_progress_cluster. Veja Relatório de progresso do CLUSTER para obter detalhes.

O agrupamento de uma tabela particionada agrupa cada uma de suas partições usando a partição do índice particionado especificado. Ao agrupar uma tabela particionada, o índice não pode ser omitido. O comando CLUSTER em uma tabela particionada não pode ser executado dentro de um bloco de transação.

Exemplos

Agrupar a tabela employees com base em seu índice employees_ind:

CLUSTER employees USING employees_ind;

Agrupar a tabela employees usando o mesmo índice usado anteriormente:

CLUSTER employees;

Agrupar todas as tabelas no banco de dados que foram agrupadas anteriormente:

CLUSTER;

Conformidade

Não existe o comando CLUSTER no padrão SQL. ^[114]

A seguinte sintaxe era usada antes do PostgreSQL 17 e ainda tem suporte:

CLUSTER [ VERBOSE ] [ nome_da_tabela [ USING nome_do_índice ] ]

A seguinte sintaxe era usada antes do PostgreSQL 8.3 e ainda tem suporte:

CLUSTER nome_do_índice ON nome_da_tabela

Veja também