Pular para o conteúdo principal
O cache de consultas permite processar consultas SELECT apenas uma vez e atender às execuções subsequentes da mesma consulta diretamente do cache. Dependendo do tipo de consulta, isso pode reduzir drasticamente a latência e o consumo de recursos do servidor ClickHouse.

​
Contexto, design e limitações

Os caches de consultas geralmente podem ser classificados como transacionalmente consistentes ou inconsistentes.
  • Em caches transacionalmente consistentes, o banco de dados invalida (descarta) os resultados de consultas em cache se o resultado da consulta SELECT mudar ou puder mudar. No ClickHouse, as operações que alteram os dados incluem inserções/atualizações/exclusões em/de tabelas ou merges de colapsamento. O cache transacionalmente consistente é especialmente adequado para bancos de dados OLTP, como MySQL (que removeu o cache de consultas após a v8.0) e Oracle.
  • Em caches transacionalmente inconsistentes, pequenas imprecisões nos resultados das consultas são aceitas, partindo do pressuposto de que todas as entradas de cache recebem um período de validade após o qual expiram (por exemplo, 1 minuto) e de que os dados subjacentes mudam pouco durante esse período. Essa abordagem é, em geral, mais adequada para bancos de dados OLAP. Como exemplo de caso em que o cache transacionalmente inconsistente é suficiente, considere um relatório de vendas por hora em uma ferramenta de relatórios acessado simultaneamente por vários usuários. Em geral, os dados de vendas mudam devagar o suficiente para que o banco de dados precise computar o relatório apenas uma vez (representado pela primeira consulta SELECT). As consultas seguintes podem ser atendidas diretamente pelo cache de consultas. Neste exemplo, um período de validade razoável poderia ser de 30 min.
O cache transacionalmente inconsistente é tradicionalmente fornecido por ferramentas cliente ou pacotes de proxy (por exemplo, chproxy) que interagem com o banco de dados. Como resultado, a mesma lógica de cache e configuração costuma ser duplicada. Com o cache de consultas do ClickHouse, a lógica de cache passa para o lado do servidor. Isso reduz o esforço de manutenção e evita redundância.

​
Configurações e uso

No ClickHouse Cloud, você deve usar configurações em nível de consulta para editar as configurações do cache de consultas. No momento, não há suporte para editar configurações em nível de configuração.
O clickhouse-local executa uma única consulta por vez. Como o cache de resultados de consultas não faz sentido, o cache de resultados de consultas fica desativado no clickhouse-local.
A configuração use_query_cache pode ser usada para controlar se uma consulta específica ou todas as consultas da sessão atual devem usar o cache de consultas. Por exemplo, a primeira execução da consulta 
SELECT some_expensive_calculation(column_1, column_2)
FROM table
SETTINGS use_query_cache = true;
armazenará o resultado da consulta no cache de consultas. Execuções subsequentes da mesma consulta (também com o parâmetro use_query_cache = true) irão ler do cache o resultado já calculado e retorná-lo imediatamente.
Definir use_query_cache e todas as outras configurações relacionadas ao cache de consultas só tem efeito em instruções SELECT independentes. Em particular, os resultados de SELECTs em views criadas por CREATE VIEW AS SELECT [...] SETTINGS use_query_cache = true não são armazenados em cache, a menos que a instrução SELECT seja executada com SETTINGS use_query_cache = true.
A forma como o cache é utilizado pode ser configurada em mais detalhes usando as configurações enable_writes_to_query_cache e enable_reads_from_query_cache (ambas true por padrão). A primeira configuração controla se os resultados das consultas são armazenados no cache, enquanto a segunda determina se o banco de dados deve tentar recuperar do cache os resultados das consultas. Por exemplo, a consulta a seguir usará o cache apenas de forma passiva, ou seja, tentará ler dele, mas não armazenará nele o seu resultado: 
SELECT some_expensive_calculation(column_1, column_2)
FROM table
SETTINGS use_query_cache = true, enable_writes_to_query_cache = false;
Para ter o máximo de controle, em geral recomenda-se fornecer as configurações use_query_cache, enable_writes_to_query_cache e enable_reads_from_query_cache apenas em consultas específicas. Também é possível habilitar o cache no nível do usuário ou do perfil (por exemplo, via SET use_query_cache = true), mas é preciso ter em mente que todas as consultas SELECT podem, nesse caso, retornar resultados em cache. O cache de consultas pode ser limpo usando a instrução SYSTEM CLEAR QUERY CACHE. O conteúdo do cache de consultas é exibido na tabela de sistema system.query_cache. O número de acertos e falhas do cache de consultas desde a inicialização do banco de dados é mostrado como eventos “QueryCacheHits” e “QueryCacheMisses” na tabela de sistema system.events. Ambos os contadores são atualizados apenas para consultas SELECT executadas com a configuração use_query_cache = true; outras consultas não afetam “QueryCacheMisses”. O campo query_cache_usage na tabela de sistema system.query_log mostra, para cada consulta executada, se o resultado da consulta foi gravado no cache de consultas ou lido dele. As métricas QueryCacheEntries e QueryCacheBytes na tabela de sistema system.metrics mostram quantas entradas / bytes o cache de consultas contém no momento. O cache de consultas existe uma vez por processo do servidor ClickHouse. No entanto, por padrão, os resultados em cache não são compartilhados entre usuários. Isso pode ser alterado (veja abaixo), mas não é recomendado por motivos de segurança. Os resultados das consultas são referenciados no cache de consultas pela Abstract Syntax Tree (AST) de cada consulta. Isso significa que o cache não diferencia maiúsculas de minúsculas; por exemplo, SELECT 1 e select 1 são tratados como a mesma consulta. Para tornar a correspondência mais natural, todas as configurações no nível da consulta relacionadas ao cache de consultas e à formatação de saída) são removidas da AST. Se a consulta foi interrompida devido a uma exceção ou a um cancelamento pelo usuário, nenhuma entrada é gravada no cache de consultas. O tamanho do cache de consultas em bytes, o número máximo de entradas de cache e o tamanho máximo de entradas individuais de cache (em bytes e em registros) podem ser configurados usando diferentes opções de configuração do servidor. 
<query_cache>
    <max_size_in_bytes>1073741824</max_size_in_bytes>
    <max_entries>1024</max_entries>
    <max_entry_size_in_bytes>1048576</max_entry_size_in_bytes>
    <max_entry_size_in_rows>30000000</max_entry_size_in_rows>
</query_cache>
Também é possível limitar o uso do cache por usuários individuais usando perfis de configurações e restrições de configurações. Mais especificamente, você pode restringir a quantidade máxima de memória (em bytes) que um usuário pode alocar no cache de consultas e o número máximo de resultados de consulta armazenados. Para isso, primeiro defina as configurações query_cache_max_size_in_bytes e query_cache_max_entries em um perfil de usuário no users.xml e, em seguida, torne ambas as configurações somente leitura: 
<profiles>
    <default>
        <!-- O tamanho máximo do cache em bytes para o usuário/perfil 'default' -->
        <query_cache_max_size_in_bytes>10000</query_cache_max_size_in_bytes>
        <!-- O número máximo de resultados de consultas SELECT armazenados no cache para o usuário/perfil 'default' -->
        <query_cache_max_entries>100</query_cache_max_entries>
        <!-- Define ambas as configurações como somente leitura para que o usuário não possa alterá-las -->
        <constraints>
            <query_cache_max_size_in_bytes>
                <readonly/>
            </query_cache_max_size_in_bytes>
            <query_cache_max_entries>
                <readonly/>
            <query_cache_max_entries>
        </constraints>
    </default>
</profiles>
Para definir por quanto tempo, no mínimo, uma consulta deve ser executada para que seu resultado possa ser armazenado em cache, você pode usar a configuração query_cache_min_query_duration. Por exemplo, o resultado da consulta 
SELECT some_expensive_calculation(column_1, column_2)
FROM table
SETTINGS use_query_cache = true, query_cache_min_query_duration = 5000;
é armazenado em cache apenas se a consulta levar mais de 5 segundos para ser executada. Também é possível especificar quantas vezes uma consulta precisa ser executada até que seu resultado seja armazenado em cache — para isso, use a configuração query_cache_min_query_runs. As entradas no cache de consultas ficam desatualizadas após um determinado período (time-to-live). Por padrão, esse período é de 60 segundos, mas um valor diferente pode ser especificado no nível da sessão, do perfil ou da consulta usando a configuração query_cache_ttl. O cache de consultas remove entradas de forma “preguiçosa”, ou seja, quando uma entrada fica desatualizada, ela não é removida imediatamente do cache. Em vez disso, quando uma nova entrada precisa ser inserida no cache de consultas, o banco de dados verifica se o cache tem espaço livre suficiente para a nova entrada. Se esse não for o caso, o banco de dados tenta remover todas as entradas desatualizadas. Se o cache ainda não tiver espaço livre suficiente, a nova entrada não será inserida. Se a consulta for executada via HTTP, o ClickHouse definirá os cabeçalhos Age e Expires com a idade (em segundos) e o timestamp de expiração da entrada em cache. As entradas no cache de consultas são comprimidas por padrão. Isso reduz o consumo geral de memória, ao custo de gravações mais lentas no cache e leituras mais lentas a partir do cache de consultas. Para desabilitar a compressão, use a configuração query_cache_compress_entries. Às vezes, é útil manter em cache vários resultados da mesma consulta. Isso pode ser obtido usando a configuração query_cache_tag, que atua como um rótulo (ou espaço de nomes) para entradas do cache de consultas. O cache de consultas considera como diferentes os resultados da mesma consulta com tags diferentes. Exemplo de como criar três entradas diferentes no cache de consultas para a mesma consulta: 
SELECT 1 SETTINGS use_query_cache = true; -- query_cache_tag é implicitamente '' (string vazia)
SELECT 1 SETTINGS use_query_cache = true, query_cache_tag = 'tag 1';
SELECT 1 SETTINGS use_query_cache = true, query_cache_tag = 'tag 2';
Para remover apenas as entradas com a tag tag do cache de consultas, você pode usar a instrução SYSTEM CLEAR QUERY CACHE TAG 'tag'. O ClickHouse lê os dados da tabela em blocos de max_block_size linhas. Devido à filtragem, agregação, etc., os blocos de resultado normalmente são muito menores que ‘max_block_size’, mas também há casos em que são bem maiores. A configuração query_cache_squash_partial_results (habilitada por padrão) controla se os blocos de resultado são combinados (se forem muito pequenos) ou divididos (se forem grandes) em blocos do tamanho de ‘max_block_size’ antes de serem inseridos no cache de resultados da consulta. Isso reduz o desempenho das gravações no cache de consultas, mas melhora a taxa de compressão das entradas de cache e proporciona uma granularidade de bloco mais natural quando os resultados da consulta são posteriormente servidos a partir do cache de consultas. Como resultado, o cache de consultas armazena, para cada consulta, vários blocos de resultado (parciais). Embora esse comportamento seja um bom padrão, ele pode ser suprimido usando a configuração query_cache_squash_partial_results. Além disso, os resultados de consultas com funções não determinísticas não são armazenados em cache por padrão. Essas funções incluem Para forçar o armazenamento em cache dos resultados de consultas com funções não determinísticas mesmo assim, use a configuração query_cache_nondeterministic_function_handling. Os resultados de consultas que envolvem tabelas de sistema (por exemplo, system.processes` ou information_schema.tables) não são armazenados em cache por padrão. Para forçar o armazenamento em cache dos resultados de consultas com tabelas de sistema mesmo assim, use a configuração query_cache_system_table_handling. Por fim, as entradas no cache de consultas não são compartilhadas entre usuários por motivos de segurança. Por exemplo, o usuário A não deve conseguir contornar uma ROW POLICY em uma tabela executando a mesma consulta que outro usuário B para quem essa política não existe. No entanto, se necessário, as entradas de cache podem ser marcadas como acessíveis a outros usuários (isto é, compartilhadas) informando a configuração query_cache_share_between_users.

​
Conteúdo relacionado

Última modificação em 10 de junho de 2026