> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > Documentação das instruções SYSTEM # SYSTEM export const CloudNotSupportedBadge = () => { return
Sem suporte no ClickHouse Cloud ; }; ## SYSTEM RELOAD EMBEDDED DICTIONARIES Recarrega todos os [dicionários internos](/pt-BR/reference/statements/create/dictionary). Por padrão, os dicionários internos ficam desabilitados. Sempre retorna `Ok.`, independentemente do resultado da atualização dos dicionários internos. ## SYSTEM RELOAD DICTIONARIES A consulta `SYSTEM RELOAD DICTIONARIES` recarrega dicionários com status `LOADED` (consulte a coluna `status` de [`system.dictionaries`](/pt-BR/reference/system-tables/dictionaries)), ou seja, dicionários que já foram carregados com sucesso anteriormente. Por padrão, os dicionários são carregados sob demanda (consulte [dictionaries\_lazy\_load](/pt-BR/reference/settings/server-settings/settings/dictionaries#dictionaries_lazy_load)), portanto, em vez de serem carregados automaticamente na inicialização, eles são inicializados no primeiro acesso, por meio da função [`dictGet`](/pt-BR/reference/functions/regular-functions/ext-dict-functions#dictGet) ou de `SELECT` em tabelas com `ENGINE = Dictionary`. **Sintaxe** ```sql theme={null} SYSTEM RELOAD DICTIONARIES [ON CLUSTER cluster_name] ``` ## SYSTEM RELOAD DICTIONARY Recarrega por completo o dicionário `dictionary_name`, independentemente do estado do dicionário (LOADED / NOT\_LOADED / FAILED). Sempre retorna `Ok.`, independentemente do resultado da atualização do dicionário. ```sql theme={null} SYSTEM RELOAD DICTIONARY [ON CLUSTER cluster_name] dictionary_name ``` O status do dicionário pode ser verificado consultando a tabela `system.dictionaries`. ```sql theme={null} SELECT name, status FROM system.dictionaries; ``` ## SYSTEM UNLOAD DICTIONARY Descarrega um Dicionário `dictionary_name` para liberar a memória dele, se o status do dicionário for `LOADED`. O dicionário é recarregado sob demanda quando necessário novamente. ```sql theme={null} SYSTEM UNLOAD DICTIONARY dictionary_name ``` O status do dicionário pode ser verificado consultando a tabela `system.dictionaries`. ```sql theme={null} SELECT name, status FROM system.dictionaries; ``` ## SYSTEM UNLOAD DICTIONARIES A consulta `SYSTEM UNLOAD DICTIONARIES` descarrega todos os dicionários com status `LOADED` (consulte a coluna `status` de [`system.dictionaries`](/pt-BR/reference/system-tables/dictionaries)), ou seja, os dicionários que já foram carregados com sucesso. ```sql theme={null} SYSTEM UNLOAD DICTIONARIES ``` ## SYSTEM RELOAD FUNCTIONS Recarrega todas as [funções executáveis definidas pelo usuário](/pt-BR/reference/functions/regular-functions/udf#executable-user-defined-functions) registradas, ou uma delas, de um arquivo de configuração. **Sintaxe** ```sql theme={null} SYSTEM RELOAD FUNCTIONS [ON CLUSTER cluster_name] SYSTEM RELOAD FUNCTION [ON CLUSTER cluster_name] function_name ``` ## SYSTEM RELOAD ASYNCHRONOUS METRICS Recalcula todas as [métricas assíncronas](/pt-BR/reference/system-tables/asynchronous_metrics). Como as métricas assíncronas são atualizadas periodicamente com base na configuração [asynchronous\_metrics\_update\_period\_s](/pt-BR/reference/settings/server-settings/settings/asynchronous-metrics#asynchronous_metrics_update_period_s), em geral não é necessário atualizá-las manualmente com esta instrução. ```sql theme={null} SYSTEM RELOAD ASYNCHRONOUS METRICS [ON CLUSTER cluster_name] ``` ## SYSTEM CLEAR|DROP DNS CACHE Limpa o cache DNS interno do ClickHouse. Às vezes (em versões mais antigas do ClickHouse), é necessário usar este comando ao alterar a infraestrutura (mudando o endereço IP de outro servidor ClickHouse ou do servidor usado pelos dicionários). Para um gerenciamento de cache mais prático (automático), consulte os parâmetros `disable_internal_dns_cache`, `dns_cache_max_entries`, `dns_cache_update_period`. ## SYSTEM CLEAR|DROP MARK CACHE Limpa o cache de marks. ## SYSTEM CLEAR|DROP PRIMARY INDEX CACHE Limpa o cache de índice primário, que mantém em memória as chaves primárias das tabelas [`MergeTree`](/pt-BR/reference/engines/table-engines/mergetree-family/mergetree). Seu tamanho é configurado pela configuração no nível do servidor [`primary_index_cache_size`](/pt-BR/reference/settings/server-settings/settings/primary-index#primary_index_cache_size). ## SYSTEM CLEAR|DROP ICEBERG METADATA CACHE Limpa o cache de metadados do Iceberg. ## SYSTEM CLEAR|DROP AVRO SCHEMA CACHE Limpa os caches por URL do Confluent Schema Registry usados pelo formato `AvroConfluent`. Isso remove tanto o cache de obtenção de schema (id → schema) quanto o cache de registro de schema (subject + schema → id), fazendo com que leituras e gravações subsequentes voltem a recorrer ao servidor do registry. É útil quando um schema foi excluído ou reescrito no registry, ou para verificar a idempotência do registry em testes. ## SYSTEM DROP PARQUET METADATA CACHE Limpa o cache de metadados do Parquet. ## SYSTEM CLEAR|DROP PAIMON METADATA CACHE Limpa o cache em memória dos arquivos de metadados do Paimon processados (listas de manifestos e manifestos). ## SYSTEM CLEAR|DROP POINT IN POLYGON CACHE Limpa o cache de polígonos constantes pré-processados usado pela função [`pointInPolygon`](/pt-BR/reference/functions/regular-functions/geo/coordinates#pointinpolygon). O limite de tamanho configurado (a configuração no nível do servidor `point_in_polygon_cache_size`) permanece inalterado, portanto o cache continua aceitando novas entradas depois disso. Para desativar o cache, defina `point_in_polygon_cache_size` como `0`. ## SYSTEM CLEAR|DROP TEXT INDEX CACHES Limpa os caches de tokens, de cabeçalho e de postings do índice de texto. Se quiser limpar um desses caches individualmente, você pode executar * `SYSTEM CLEAR TEXT INDEX TOKENS CACHE`, * `SYSTEM CLEAR TEXT INDEX HEADER CACHE`, ou * `SYSTEM CLEAR TEXT INDEX POSTINGS CACHE` ## SYSTEM CLEAR|DROP INDEX MARK CACHE Limpa o cache de marcas dos índices secundários (de salto de dados). ## SYSTEM CLEAR|DROP INDEX UNCOMPRESSED CACHE Limpa o cache de blocos não comprimidos dos índices secundários (de salto de dados). ## SYSTEM CLEAR|DROP MMAP CACHE Limpa o cache de arquivos mapeados em memória. ## SYSTEM CLEAR|DROP PAGE CACHE Limpa o cache de páginas em espaço do usuário, o cache em memória do próprio ClickHouse para dados lidos do armazenamento subjacente. ## SYSTEM CLEAR|DROP VECTOR SIMILARITY INDEX CACHE Limpa o cache do índice de similaridade vetorial. ## SYSTEM CLEAR|DROP CONNECTIONS CACHE Limpa o cache dos pools de conexões HTTP usados nas conexões de saída. ## SYSTEM CLEAR|DROP S3 CLIENT CACHE Limpa o cache dos clientes S3. ## SYSTEM PREWARM MARK CACHE Carrega as marcas de uma tabela para o [cache de marcas](#drop-mark-cache). As marcas dos índices secundários também são carregadas para o [cache de marcas de índice](#drop-index-mark-cache). ```sql theme={null} SYSTEM PREWARM MARK CACHE [ON CLUSTER cluster_name] [db.]table ``` ## SYSTEM PREWARM PRIMARY INDEX CACHE Carrega os índices primários de uma tabela `MergeTree` para o [cache de índice primário](#drop-primary-index-cache). ```sql theme={null} SYSTEM PREWARM PRIMARY INDEX CACHE [ON CLUSTER cluster_name] [db.]table ``` ## SYSTEM CLEAR|DROP DISK METADATA CACHE Limpa o cache de metadados do disco especificado. ```sql theme={null} SYSTEM DROP DISK METADATA CACHE ``` ## SYSTEM SYNC FILESYSTEM CACHE Reconcilia o estado em memória do cache do sistema de arquivos do ClickHouse com os arquivos de cache efetivamente presentes em disco e retorna o `cache_name`, o `path` e o `size` baixado de cada segmento de arquivo em cache. Um nome de cache opcional limita a operação a um único cache. ```sql theme={null} SYSTEM SYNC FILESYSTEM CACHE [''] ``` ## SYSTEM CLEAR|DROP DISTRIBUTED CACHE `SYSTEM CLEAR|DROP DISTRIBUTED CACHE` está disponível apenas no ClickHouse Cloud. Remove o Distributed Cache. Use `CONNECTIONS` para remover apenas as conexões em cache com os servidores do Distributed Cache ou informe o identificador de um servidor específico. ```sql theme={null} SYSTEM DROP DISTRIBUTED CACHE [CONNECTIONS | 'server_id'] ``` ## SYSTEM DROP REPLICA Réplicas inativas de tabelas `ReplicatedMergeTree` podem ser removidas usando a sintaxe a seguir: ```sql theme={null} SYSTEM DROP REPLICA 'replica_name' FROM TABLE database.table; SYSTEM DROP REPLICA 'replica_name' FROM DATABASE database; SYSTEM DROP REPLICA 'replica_name'; SYSTEM DROP REPLICA 'replica_name' FROM ZKPATH '/path/to/table/in/zk'; ``` As consultas removerão o caminho da réplica `ReplicatedMergeTree` no ZooKeeper. Isso é útil quando a réplica está inativa e seus metadados não podem ser removidos do ZooKeeper com `DROP TABLE`, porque essa tabela não existe mais. Ela removerá apenas a réplica inativa/desatualizada e não pode remover a réplica local; para isso, use `DROP TABLE`. `DROP REPLICA` não remove nenhuma tabela nem remove dados ou metadados do disco. A primeira remove os metadados da réplica `'replica_name'` da tabela `database.table`. A segunda faz o mesmo para todas as tabelas replicadas no banco de dados. A terceira faz o mesmo para todas as tabelas replicadas no servidor local. A quarta é útil para remover os metadados de uma réplica inativa quando todas as outras réplicas de uma tabela tiverem sido removidas. Ela exige que o caminho da tabela seja especificado explicitamente. Deve ser o mesmo caminho que foi passado como primeiro argumento do motor `ReplicatedMergeTree` na criação da tabela. ## SYSTEM DROP DATABASE REPLICA Réplicas inativas de bancos de dados `Replicated` podem ser removidas com a seguinte sintaxe: ```sql theme={null} SYSTEM DROP DATABASE REPLICA 'replica_name' [FROM SHARD 'shard_name'] FROM DATABASE database; SYSTEM DROP DATABASE REPLICA 'replica_name' [FROM SHARD 'shard_name']; SYSTEM DROP DATABASE REPLICA 'replica_name' [FROM SHARD 'shard_name'] FROM ZKPATH '/path/to/table/in/zk'; ``` Semelhante a `SYSTEM DROP REPLICA`, mas remove do ZooKeeper o caminho da réplica do banco de dados `Replicated` quando não existe um banco de dados sobre o qual executar `DROP DATABASE`. Observe que isso não remove réplicas `ReplicatedMergeTree` (portanto, talvez você também precise de `SYSTEM DROP REPLICA`). Os nomes do shard e da réplica são os que foram especificados nos argumentos do mecanismo `Replicated` ao criar o banco de dados. Além disso, esses nomes podem ser obtidos nas colunas `database_shard_name` e `database_replica_name` em `system.clusters`. Se a cláusula `FROM SHARD` estiver ausente, `replica_name` deverá ser um nome completo de réplica no formato `shard_name|replica_name`. ## SYSTEM CLEAR|DROP UNCOMPRESSED CACHE Limpa o cache de dados não comprimidos. O cache de dados não comprimidos é ativado/desativado pela configuração [`use_uncompressed_cache`](/pt-BR/reference/settings/session-settings/use#use_uncompressed_cache) no nível de consulta/usuário/perfil. Seu tamanho pode ser configurado usando a configuração no nível do servidor [`uncompressed_cache_size`](/pt-BR/reference/settings/server-settings/settings/uncompressed-cache#uncompressed_cache_size). ## SYSTEM CLEAR|DROP COMPILED EXPRESSION CACHE Limpa o cache de expressões compiladas. O cache de expressões compiladas é ativado/desativado pela configuração [`compile_expressions`](/pt-BR/reference/settings/session-settings/compile#compile_expressions) no nível de consulta/usuário/perfil. ## SYSTEM CLEAR|DROP QUERY CONDITION CACHE Limpa o cache de condições de consulta. ## SYSTEM CLEAR|DROP ENCRYPTION HEADERS CACHE Limpa o cache de cabeçalhos de criptografia. Esse cache armazena os cabeçalhos de criptografia lidos no início de arquivos criptografados e é usado pelo caminho de leitura experimental `use_reader_executor` para evitar relê-los; seu tamanho é configurado pela configuração do servidor `encryption_header_cache_size`. ## SYSTEM CLEAR|DROP QUERY CACHE ```sql theme={null} SYSTEM CLEAR QUERY CACHE; SYSTEM CLEAR QUERY CACHE TAG '' ``` Limpa o [cache de consultas](/pt-BR/concepts/features/performance/caches/query-cache). Se uma tag for especificada, somente as entradas do cache de consultas com a tag especificada serão excluídas. ## SYSTEM CLEAR|DROP FORMAT SCHEMA CACHE Limpa o cache dos esquemas carregados a partir de [`format_schema_path`](/pt-BR/reference/settings/server-settings/settings/format#format_schema_path). Alvos compatíveis: * Protobuf: Remove da memória as definições de mensagens Protobuf importadas. * Files: Exclui os arquivos de esquema em cache armazenados localmente no [`format_schema_path`](/pt-BR/reference/settings/server-settings/settings/format#format_schema_path), gerados quando `format_schema_source` é definido como `query`. Observação: Se nenhum alvo for especificado, ambos os caches serão limpos. ```sql theme={null} SYSTEM CLEAR|DROP FORMAT SCHEMA CACHE [FOR Protobuf/Files] ``` ## SYSTEM FLUSH LOGS Descarrega mensagens de log em buffer nas tabelas de sistema, por exemplo, system.query\_log. É útil principalmente para depuração, já que a maioria das tabelas de sistema tem um intervalo padrão de flush de 7,5 segundos. Isso também criará tabelas de sistema mesmo que a fila de mensagens esteja vazia. ```sql theme={null} SYSTEM FLUSH LOGS [ON CLUSTER cluster_name] [log_name|[database.table]] [, ...] ``` Se você não quiser fazer flush de tudo, poderá fazer flush de um ou mais logs individuais informando o nome deles ou o da respectiva tabela de destino: ```sql theme={null} SYSTEM FLUSH LOGS query_log, system.query_views_log; ``` ## SYSTEM RELOAD CONFIG Recarrega a configuração do ClickHouse. É usado quando a configuração está armazenada no ZooKeeper. Observe que `SYSTEM RELOAD CONFIG` não recarrega a configuração de `USER` armazenada no ZooKeeper; ele recarrega apenas a configuração de `USER` armazenada em `users.xml`. Para recarregar toda a configuração de `USER`, use `SYSTEM RELOAD USERS` ```sql theme={null} SYSTEM RELOAD CONFIG [ON CLUSTER cluster_name] ``` ## SYSTEM RELOAD USERS Recarrega todos os armazenamentos de acesso, incluindo: users.xml, o armazenamento de acesso em disco local e o armazenamento de acesso replicado (no ZooKeeper). ```sql theme={null} SYSTEM RELOAD USERS [ON CLUSTER cluster_name] ``` ## SYSTEM SHUTDOWN Normalmente encerra o ClickHouse (como `service clickhouse-server stop` / `kill {$pid_clickhouse-server}`) ## SYSTEM KILL Encerra o processo do ClickHouse (como `kill -9 {$ pid_clickhouse-server}`) ## SYSTEM INSTRUMENT Gerencia pontos de instrumentação usando o recurso XRay do LLVM, que está disponível quando o ClickHouse é compilado com `ENABLE_XRAY=1`. Isso permite depurar e gerar perfis em produção sem modificar o código-fonte e com sobrecarga mínima. Quando nenhum ponto de instrumentação é adicionado, o impacto no desempenho é desprezível, pois isso apenas adiciona um salto extra para um endereço próximo no prólogo e no epílogo das funções com mais de 200 instruções. ### SYSTEM INSTRUMENT ADD Adiciona um novo ponto de instrumentação. As funções instrumentadas podem ser inspecionadas na tabela de sistema [`system.instrumentation`](/pt-BR/reference/system-tables/instrumentation). Mais de um handler pode ser adicionado à mesma função, e eles serão executados na mesma ordem em que a instrumentação foi adicionada. As funções a serem instrumentadas podem ser obtidas na tabela de sistema [`system.symbols`](/pt-BR/reference/system-tables/symbols). Há três tipos diferentes de handlers que podem ser adicionados às funções: **Sintaxe** ```sql theme={null} SYSTEM INSTRUMENT ADD FUNCTION HANDLER [ARGUMENTS] ``` em que `FUNCTION` é qualquer função ou substring de uma função, como `QueryMetricLog::startQuery`, e o handler é um dos seguintes #### LOG Imprime o texto fornecido como argumento e o stack trace na `ENTRY` ou na `EXIT` da função. ```sql theme={null} SYSTEM INSTRUMENT ADD 'QueryMetricLog::startQuery' LOG ENTRY 'this is a log printed at entry' SYSTEM INSTRUMENT ADD 'QueryMetricLog::startQuery' LOG EXIT 'this is a log printed at exit' ``` #### SLEEP Suspende a execução por um número fixo de segundos em `ENTRY` ou `EXIT`: ```sql theme={null} SYSTEM INSTRUMENT ADD 'QueryMetricLog::startQuery' SLEEP ENTRY 0.5 ``` ou para um número aleatório de segundos com distribuição uniforme, informando o mínimo e o máximo separados por um espaço em branco: ```sql theme={null} SYSTEM INSTRUMENT ADD 'QueryMetricLog::startQuery' SLEEP ENTRY 0 1 ``` #### PROFILE Mede o tempo gasto entre `ENTRY` e `EXIT` de uma função. O resultado do profiling é armazenado em [`system.trace_log`](/pt-BR/reference/system-tables/trace_log) e pode ser convertido no [Chrome Event Trace Format](/pt-BR/reference/system-tables/trace_log#chrome-event-trace-format). ```sql theme={null} SYSTEM INSTRUMENT ADD 'QueryMetricLog::startQuery' PROFILE ``` ### SYSTEM INSTRUMENT REMOVE Remove um único ponto de instrumentação com: ```sql theme={null} SYSTEM INSTRUMENT REMOVE ID ``` todos usando a palavra-chave `ALL`: ```sql theme={null} SYSTEM INSTRUMENT REMOVE ALL ``` um conjunto de IDs de uma subconsulta: ```sql theme={null} SYSTEM INSTRUMENT REMOVE (SELECT id FROM system.instrumentation WHERE handler = 'log') ``` ou todos os pontos de instrumentação que tenham um determinado function\_name: ```sql theme={null} SYSTEM INSTRUMENT REMOVE 'QueryMetricLog::startQuery' ``` As informações sobre o ponto de instrumentação podem ser obtidas na tabela de sistema [`system.instrumentation`](/pt-BR/reference/system-tables/instrumentation). ## Gerenciando tabelas distribuídas O ClickHouse pode gerenciar tabelas [distribuídas](/pt-BR/reference/engines/table-engines/special/distributed). Quando um usuário insere dados nessas tabelas, o ClickHouse primeiro cria uma fila com os dados que devem ser enviados aos nós do cluster e depois os envia de forma assíncrona. Você pode gerenciar o processamento da fila com as consultas [`STOP DISTRIBUTED SENDS`](#stop-distributed-sends), [FLUSH DISTRIBUTED](#flush-distributed) e [`START DISTRIBUTED SENDS`](#start-distributed-sends). Você também pode inserir dados distribuídos de forma síncrona com a configuração [`distributed_foreground_insert`](/pt-BR/reference/settings/session-settings/distributed#distributed_foreground_insert). ### SYSTEM STOP DISTRIBUTED SENDS Desativa a distribuição de dados em segundo plano ao inserir dados em tabelas distribuídas. ```sql theme={null} SYSTEM STOP DISTRIBUTED SENDS [db.] [ON CLUSTER cluster_name] ``` Se [`prefer_localhost_replica`](/pt-BR/reference/settings/session-settings/prefer#prefer_localhost_replica) estiver habilitado (padrão), os dados ainda serão inseridos no shard local. ### SYSTEM FLUSH DISTRIBUTED Força o ClickHouse a enviar dados aos nós do cluster de forma síncrona. Se algum nó estiver indisponível, o ClickHouse gera uma exceção e interrompe a execução da consulta. Você pode tentar a consulta novamente até que ela seja concluída com sucesso, o que acontecerá quando todos os nós voltarem a ficar online. Você também pode sobrescrever algumas configurações usando a cláusula `SETTINGS`; isso pode ser útil para contornar limitações temporárias, como `max_concurrent_queries_for_all_users` ou `max_memory_usage`. ```sql theme={null} SYSTEM FLUSH DISTRIBUTED [db.] [ON CLUSTER cluster_name] [SETTINGS ...] ``` Cada bloco pendente é armazenado em disco com as configurações da consulta INSERT inicial; por isso, às vezes pode ser necessário substituir essas configurações. ### SYSTEM START DISTRIBUTED SENDS Ativa a distribuição de dados em segundo plano ao inserir dados em tabelas distribuídas. ```sql theme={null} SYSTEM START DISTRIBUTED SENDS [db.] [ON CLUSTER cluster_name] ``` ### SYSTEM STOP LISTEN Fecha o socket e encerra de forma controlada as conexões existentes com o servidor na porta e no protocolo especificados. No entanto, se as configurações de protocolo correspondentes não tiverem sido especificadas na configuração do clickhouse-server, este comando não terá efeito. ```sql theme={null} SYSTEM STOP LISTEN [ON CLUSTER cluster_name] [QUERIES ALL | QUERIES DEFAULT | QUERIES CUSTOM | TCP | TCP WITH PROXY | TCP SECURE | HTTP | HTTPS | MYSQL | GRPC | POSTGRESQL | PROMETHEUS | CUSTOM 'protocol'] ``` * Se o modificador `CUSTOM 'protocol'` for especificado, o protocolo personalizado com o nome indicado, definido na seção de protocolos da configuração do servidor, será interrompido. * Se o modificador `QUERIES ALL [EXCEPT .. [,..]]` for especificado, todos os protocolos serão interrompidos, exceto os especificados na cláusula `EXCEPT`. * Se o modificador `QUERIES DEFAULT [EXCEPT .. [,..]]` for especificado, todos os protocolos padrão serão interrompidos, exceto os especificados na cláusula `EXCEPT`. * Se o modificador `QUERIES CUSTOM [EXCEPT .. [,..]]` for especificado, todos os protocolos personalizados serão interrompidos, exceto os especificados na cláusula `EXCEPT`. ### SYSTEM START LISTEN Permite estabelecer novas conexões nos protocolos especificados. No entanto, se o servidor na porta e no protocolo especificados não tiver sido interrompido com o comando SYSTEM STOP LISTEN, este comando não terá efeito. ```sql theme={null} SYSTEM START LISTEN [ON CLUSTER cluster_name] [QUERIES ALL | QUERIES DEFAULT | QUERIES CUSTOM | TCP | TCP WITH PROXY | TCP SECURE | HTTP | HTTPS | MYSQL | GRPC | POSTGRESQL | PROMETHEUS | CUSTOM 'protocol'] ``` ## Gerenciamento de tabelas MergeTree O ClickHouse pode gerenciar processos em segundo plano em tabelas [MergeTree](/pt-BR/reference/engines/table-engines/mergetree-family/mergetree). ### SYSTEM STOP MERGES Permite interromper os merges em segundo plano de tabelas da família MergeTree: ```sql theme={null} SYSTEM STOP MERGES [ON CLUSTER cluster_name] [ON VOLUME | [db.]merge_tree_family_table_name] ``` O `DETACH / ATTACH` de uma tabela iniciará merges em segundo plano para a tabela, mesmo que os merges tenham sido interrompidos anteriormente para todas as tabelas MergeTree. ### SYSTEM START MERGES Permite iniciar merges em segundo plano para tabelas da família MergeTree: ```sql theme={null} SYSTEM START MERGES [ON CLUSTER cluster_name] [ON VOLUME | [db.]merge_tree_family_table_name] ``` ### SYSTEM STOP TTL MERGES Permite interromper a exclusão em segundo plano de dados antigos de acordo com a [expressão TTL](/pt-BR/reference/engines/table-engines/mergetree-family/mergetree#table_engine-mergetree-ttl) para tabelas da família MergeTree: Retorna `Ok.` mesmo que a tabela não exista ou não use o motor MergeTree. Retorna erro quando o banco de dados não existe: ```sql theme={null} SYSTEM STOP TTL MERGES [ON CLUSTER cluster_name] [[db.]merge_tree_family_table_name] ``` ### SYSTEM START TTL MERGES Permite iniciar a exclusão em segundo plano de dados antigos de acordo com a [expressão TTL](/pt-BR/reference/engines/table-engines/mergetree-family/mergetree#table_engine-mergetree-ttl) para tabelas da família MergeTree: Retorna `Ok.` mesmo que a tabela não exista. Retorna erro quando o banco de dados não existe: ```sql theme={null} SYSTEM START TTL MERGES [ON CLUSTER cluster_name] [[db.]merge_tree_family_table_name] ``` ### SYSTEM STOP MOVES Permite interromper a movimentação de dados em segundo plano de acordo com a [expressão TTL da tabela com a cláusula TO VOLUME ou TO DISK](/pt-BR/reference/engines/table-engines/mergetree-family/mergetree#mergetree-table-ttl) para tabelas da família MergeTree: Retorna `Ok.` mesmo que a tabela não exista. Retorna erro quando o banco de dados não existe: ```sql theme={null} SYSTEM STOP MOVES [ON CLUSTER cluster_name] [[db.]merge_tree_family_table_name] ``` ### SYSTEM START MOVES Permite iniciar a movimentação de dados em segundo plano de acordo com a [expressão TTL da tabela com as cláusulas TO VOLUME e TO DISK](/pt-BR/reference/engines/table-engines/mergetree-family/mergetree#mergetree-table-ttl) para tabelas da família MergeTree: Retorna `Ok.` mesmo que a tabela não exista. Retorna erro quando o banco de dados não existe: ```sql theme={null} SYSTEM START MOVES [ON CLUSTER cluster_name] [[db.]merge_tree_family_table_name] ``` ### SYSTEM UNFREEZE Remove um backup congelado com o nome especificado de todos os disks. Veja mais sobre como descongelar partes individuais em [ALTER TABLE table\_name UNFREEZE WITH NAME ](/pt-BR/reference/statements/alter/partition#unfreeze-partition) ```sql theme={null} SYSTEM UNFREEZE WITH NAME ``` ### SYSTEM WAIT LOADING PARTS Aguarde até que todas as partes de dados de uma tabela carregadas de forma assíncrona (partes de dados desatualizadas) sejam carregadas. ```sql theme={null} SYSTEM WAIT LOADING PARTS [ON CLUSTER cluster_name] [db.]merge_tree_family_table_name ``` ## Gerenciando tabelas ReplicatedMergeTree O ClickHouse pode gerenciar, em segundo plano, os processos relacionados à replicação em tabelas [ReplicatedMergeTree](/pt-BR/reference/engines/table-engines/mergetree-family/replication). ### SYSTEM STOP FETCHES Permite interromper os fetches em segundo plano de partes inseridas em tabelas da família `ReplicatedMergeTree`: Sempre retorna `Ok.`, independentemente do motor da tabela, mesmo que a tabela ou o banco de dados não existam. ```sql theme={null} SYSTEM STOP FETCHES [ON CLUSTER cluster_name] [[db.]replicated_merge_tree_family_table_name] ``` ### SYSTEM START FETCHES Oferece a possibilidade de iniciar fetches em segundo plano para partes inseridas em tabelas da família `ReplicatedMergeTree`: Sempre retorna `Ok.` independentemente do motor da tabela, mesmo que a tabela ou o banco de dados não existam. ```sql theme={null} SYSTEM START FETCHES [ON CLUSTER cluster_name] [[db.]replicated_merge_tree_family_table_name] ``` ### SYSTEM STOP REPLICATED SENDS Permite interromper, em segundo plano, o envio de novas partes inseridas para outras réplicas no cluster em tabelas da família `ReplicatedMergeTree`: ```sql theme={null} SYSTEM STOP REPLICATED SENDS [ON CLUSTER cluster_name] [[db.]replicated_merge_tree_family_table_name] ``` ### SYSTEM START REPLICATED SENDS Permite iniciar, em segundo plano, o envio de novas partes inseridas para outras réplicas no cluster em tabelas da família `ReplicatedMergeTree`: ```sql theme={null} SYSTEM START REPLICATED SENDS [ON CLUSTER cluster_name] [[db.]replicated_merge_tree_family_table_name] ``` ### SYSTEM STOP REPLICATION QUEUES Permite interromper tarefas de fetch em segundo plano das filas de replicação armazenadas no ZooKeeper para tabelas da família `ReplicatedMergeTree`. Os possíveis tipos de tarefas em segundo plano são: merges, fetches, mutation e instruções DDL com a cláusula ON CLUSTER: ```sql theme={null} SYSTEM STOP REPLICATION QUEUES [ON CLUSTER cluster_name] [[db.]replicated_merge_tree_family_table_name] ``` ### SYSTEM START REPLICATION QUEUES Permite iniciar tarefas de fetch em segundo plano a partir das filas de replicação armazenadas no Zookeeper para tabelas da família `ReplicatedMergeTree`. Os tipos possíveis de tarefas em segundo plano são - merges, fetches, mutation, instruções DDL com a cláusula ON CLUSTER: ```sql theme={null} SYSTEM START REPLICATION QUEUES [ON CLUSTER cluster_name] [[db.]replicated_merge_tree_family_table_name] ``` ### SYSTEM STOP PULLING REPLICATION LOG Interrompe a leitura de novas entradas do log de replicação para a fila de replicação em uma tabela `ReplicatedMergeTree`. ```sql theme={null} SYSTEM STOP PULLING REPLICATION LOG [ON CLUSTER cluster_name] [[db.]replicated_merge_tree_family_table_name] ``` ### SYSTEM START PULLING REPLICATION LOG Cancela `SYSTEM STOP PULLING REPLICATION LOG`. ```sql theme={null} SYSTEM START PULLING REPLICATION LOG [ON CLUSTER cluster_name] [[db.]replicated_merge_tree_family_table_name] ``` ### SYSTEM SYNC REPLICA Aguarde até que uma tabela `ReplicatedMergeTree` esteja sincronizada com outras réplicas em um cluster, mas por no máximo `receive_timeout` segundos. ```sql theme={null} SYSTEM SYNC REPLICA [ON CLUSTER cluster_name] [db.]replicated_merge_tree_family_table_name [IF EXISTS] [STRICT | LIGHTWEIGHT [FROM 'srcReplica1'[, 'srcReplica2'[, ...]]] | PULL] ``` Após executar esta instrução, `[db.]replicated_merge_tree_family_table_name` busca comandos do log replicado comum para sua própria fila de replicação, e então a consulta aguarda até que a réplica processe todos os comandos buscados. Há suporte para os seguintes modificadores: * Com `IF EXISTS` (disponível desde a versão 25.6), a consulta não gerará erro se a tabela não existir. Isso é útil ao adicionar uma nova réplica a um cluster, quando ela já faz parte da configuração do cluster, mas ainda está em processo de criação e sincronização da tabela. * Se um modificador `STRICT` for especificado, a consulta aguardará até que a fila de replicação fique vazia. A versão `STRICT` pode nunca ser concluída com sucesso se novas entradas continuarem aparecendo na fila de replicação. * Se um modificador `LIGHTWEIGHT` for especificado, a consulta aguardará apenas o processamento das entradas `GET_PART`, `ATTACH_PART`, `DROP_RANGE`, `REPLACE_RANGE` e `DROP_PART`. Além disso, o modificador LIGHTWEIGHT oferece suporte a uma cláusula opcional FROM 'srcReplicas', em que 'srcReplicas' é uma lista, separada por vírgulas, com nomes de réplicas de origem. Essa extensão permite uma sincronização mais direcionada, ao focar apenas nas tarefas de replicação originadas das réplicas de origem especificadas. * Se um modificador `PULL` for especificado, a consulta extrai novas entradas da fila de replicação do ZooKeeper, mas não aguarda o processamento de nada. ### SYNC DATABASE REPLICA Aguarda até que o [banco de dados replicado](/pt-BR/reference/engines/database-engines/replicated) especificado aplique todas as alterações de esquema presentes na fila DDL desse banco de dados. **Sintaxe** ```sql theme={null} SYSTEM SYNC DATABASE REPLICA replicated_database_name; ``` ### SYSTEM RESTART REPLICA Permite reinicializar o estado da sessão do ZooKeeper para a tabela `ReplicatedMergeTree`, comparar o estado atual com o ZooKeeper como fonte da verdade e adicionar tarefas à fila do ZooKeeper, se necessário. A inicialização da fila de replicação com base nos dados do ZooKeeper acontece da mesma forma que na instrução `ATTACH TABLE`. Por um curto período, a tabela ficará indisponível para qualquer operação. ```sql theme={null} SYSTEM RESTART REPLICA [ON CLUSTER cluster_name] [db.]replicated_merge_tree_family_table_name ``` ### SYSTEM RESTORE REPLICA Restaura uma réplica se os dados \[possivelmente] ainda estiverem presentes, mas os metadados do ZooKeeper tiverem sido perdidos. Funciona apenas em tabelas `ReplicatedMergeTree` somente leitura. É possível executar a consulta após: * Perda da raiz `/` do ZooKeeper. * Perda do caminho de réplicas `/replicas`. * Perda do caminho de uma réplica específica `/replicas/replica_name/`. A réplica anexa as partes encontradas localmente e envia informações sobre elas ao ZooKeeper. As partes presentes em uma réplica antes da perda dos metadados não são buscadas novamente de outras réplicas se não estiverem desatualizadas (ou seja, restaurar a réplica não significa baixar novamente todos os dados pela rede). As partes em qualquer estado são movidas para a pasta `detached/`. As partes que estavam ativas antes da perda dos dados (confirmadas) são anexadas. ### SYSTEM RESTORE DATABASE REPLICA Restaura uma réplica caso os dados \[possivelmente] ainda estejam presentes, mas os metadados do Zookeeper tenham sido perdidos. **Sintaxe** ```sql theme={null} SYSTEM RESTORE DATABASE REPLICA repl_db [ON CLUSTER cluster] ``` **Exemplo** ```sql theme={null} CREATE DATABASE repl_db ENGINE=Replicated("/clickhouse/repl_db", shard1, replica1); CREATE TABLE repl_db.test_table (n UInt32) ENGINE = ReplicatedMergeTree ORDER BY n PARTITION BY n % 10; -- zookeeper_delete_path("/clickhouse/repl_db", recursive=True) <- perda do nó raiz. SYSTEM RESTORE DATABASE REPLICA repl_db; ``` **Sintaxe** ```sql theme={null} SYSTEM RESTORE REPLICA [db.]replicated_merge_tree_family_table_name [ON CLUSTER cluster_name] ``` Sintaxe alternativa: ```sql theme={null} SYSTEM RESTORE REPLICA [ON CLUSTER cluster_name] [db.]replicated_merge_tree_family_table_name ``` **Exemplo** Criar uma tabela em vários servidores. Depois que os metadados da réplica no ZooKeeper são perdidos, a tabela será anexada em modo somente leitura, já que os metadados estão ausentes. A última consulta precisa ser executada em cada réplica. ```sql theme={null} CREATE TABLE test(n UInt32) ENGINE = ReplicatedMergeTree('/clickhouse/tables/test/', '{replica}') ORDER BY n PARTITION BY n % 10; INSERT INTO test SELECT * FROM numbers(1000); -- zookeeper_delete_path("/clickhouse/tables/test", recursive=True) <- perda da raiz. SYSTEM RESTART REPLICA test; SYSTEM RESTORE REPLICA test; ``` Outra forma: ```sql theme={null} SYSTEM RESTORE REPLICA test ON CLUSTER cluster; ``` ### SYSTEM RESTART REPLICAS Permite reinicializar o estado das sessões do Zookeeper para todas as tabelas `ReplicatedMergeTree`, comparando o estado atual com o Zookeeper como fonte da verdade e adicionando tarefas à fila do Zookeeper, se necessário ### SYSTEM CLEAR|DROP FILESYSTEM CACHE Permite limpar o cache do sistema de arquivos. ```sql theme={null} SYSTEM CLEAR FILESYSTEM CACHE [ON CLUSTER cluster_name] ``` ### SYSTEM SYNC FILE CACHE É muito pesado e pode ser usado indevidamente. Executa a syscall `sync`. ```sql theme={null} SYSTEM SYNC FILE CACHE [ON CLUSTER cluster_name] ``` ### SYSTEM LOAD PRIMARY KEY Carrega as chaves primárias para a tabela especificada ou para todas as tabelas. ```sql theme={null} SYSTEM LOAD PRIMARY KEY [db.]name ``` ```sql theme={null} SYSTEM LOAD PRIMARY KEY ``` ### SYSTEM UNLOAD PRIMARY KEY Descarrega as chaves primárias da tabela especificada ou de todas as tabelas. ```sql theme={null} SYSTEM UNLOAD PRIMARY KEY [db.]name ``` ```sql theme={null} SYSTEM UNLOAD PRIMARY KEY ``` ## Gerenciando views materializadas atualizáveis Comandos para controlar tarefas em segundo plano executadas por [views materializadas atualizáveis](/pt-BR/reference/statements/create/view#refreshable-materialized-view) Fique de olho em [`system.view_refreshes`](/pt-BR/reference/system-tables/view_refreshes) ao usá-las. ### SYSTEM STOP \[REPLICATED] VIEW, STOP VIEWS Desativa a atualização periódica da view especificada ou de todas as views atualizáveis. Se houver uma atualização em andamento, ela também será cancelada. Se a view estiver em um banco de dados Replicated ou Shared, `STOP VIEW` afeta apenas a réplica atual, enquanto `STOP REPLICATED VIEW` afeta todas as réplicas. O estado de parada não persiste após reinicializações do servidor. Após uma reinicialização, as views voltarão a seguir os agendamentos de atualização configurados. Em bancos de dados Replicated ou Shared, `SYSTEM STOP VIEW` afeta apenas a réplica atual. Use `SYSTEM STOP REPLICATED VIEW` para interromper as atualizações em todas as réplicas. ```sql theme={null} SYSTEM STOP VIEW [db.]name ``` ```sql theme={null} SYSTEM STOP VIEWS ``` ### SYSTEM START \[REPLICATED] VIEW, START VIEWS Ativa a atualização periódica da view especificada ou de todas as views atualizáveis. Nenhuma atualização imediata é disparada. Se a view estiver em um banco de dados Replicated ou Shared, `START VIEW` desfaz o efeito de `STOP VIEW`, e `START REPLICATED VIEW` desfaz o efeito de `STOP REPLICATED VIEW`. `START VIEW` também desfaz o efeito de `PAUSE VIEW`. ```sql theme={null} SYSTEM START VIEW [db.]name ``` ```sql theme={null} SYSTEM START VIEWS ``` ### SYSTEM PAUSE VIEW, PAUSE VIEWS Desativa a atualização periódica da view especificada ou de todas as views atualizáveis. Ao contrário de `SYSTEM STOP VIEW`, `SYSTEM PAUSE VIEW` não interrompe uma atualização que já esteja em andamento: a atualização em execução pode terminar, e apenas as atualizações subsequentes são impedidas. Reative com `SYSTEM START VIEW` ou `SYSTEM START VIEWS`. O estado de pausa não persiste após reinicializações do servidor. Depois de uma reinicialização, as views retomarão seus intervalos de atualização configurados. Em bancos de dados Replicated ou Shared, `SYSTEM PAUSE VIEW` afeta apenas a réplica atual. ```sql theme={null} SYSTEM PAUSE VIEW [db.]name ``` ```sql theme={null} SYSTEM PAUSE VIEWS ``` ### SYSTEM REFRESH VIEW Executa uma atualização imediata, fora do agendamento, de uma determinada view. ```sql theme={null} SYSTEM REFRESH VIEW [db.]name ``` ### SYSTEM WAIT VIEW Espera a atualização em execução ser concluída. Se nenhuma atualização estiver em execução, retorna imediatamente. Se a tentativa de atualização mais recente tiver falhado, retorna um erro. Pode ser usado logo após criar uma nova view materializada atualizável (sem a palavra-chave EMPTY) para aguardar a conclusão da atualização inicial. Se a view estiver em um banco de dados Replicated ou Shared, e a atualização estiver em execução em outra réplica, aguarda a conclusão dessa atualização. ```sql theme={null} SYSTEM WAIT VIEW [db.]name ``` ### SYSTEM CANCEL VIEW Se houver uma atualização em andamento para a view especificada na réplica atual, interrompa-o e cancele-o. Caso contrário, não faça nada. ```sql theme={null} SYSTEM CANCEL VIEW [db.]name ``` ## Gerenciamento de atividades em segundo plano Comandos independentes de mecanismo para controlar a atividade em segundo plano de uma única tabela ou de todas essas tabelas no servidor de uma só vez. Eles abrangem: * [Views materializadas atualizáveis](/pt-BR/reference/statements/create/view#refreshable-materialized-view) (a atualização periódica); e * os motores de tabela de streaming que consomem continuamente de uma fonte externa: [Kafka](/pt-BR/reference/engines/table-engines/integrations/kafka), [RabbitMQ](/pt-BR/reference/engines/table-engines/integrations/rabbitmq), [NATS](/pt-BR/reference/engines/table-engines/integrations/nats), [S3Queue](/pt-BR/reference/engines/table-engines/integrations/s3queue) e [AzureQueue](/pt-BR/reference/engines/table-engines/integrations/azure-queue). Para uma view materializada atualizável, cada verbo é um alias do comando `SYSTEM ... VIEW` correspondente em [Gerenciamento de views materializadas atualizáveis](#managing-refreshable-materialized-views). Portanto, `SYSTEM STOP [db.]name` se comporta exatamente como `SYSTEM STOP VIEW [db.]name`, e assim por diante. As formas por tabela e com curinga diferem na forma como tratam tabelas sem atividade em segundo plano. A forma por tabela (`SYSTEM STOP [db.]table`) gera um erro se a tabela especificada não for nem um mecanismo de streaming nem uma view materializada atualizável. A forma com curinga ignora essas tabelas silenciosamente, portanto, é sempre seguro executá-la. `STOP` e `CANCEL` interrompem o consumo assim que possível. Para [Kafka](/pt-BR/reference/engines/table-engines/integrations/kafka), [RabbitMQ](/pt-BR/reference/engines/table-engines/integrations/rabbitmq) e [NATS](/pt-BR/reference/engines/table-engines/integrations/nats), eles interrompem a leitura da fonte, mas não interrompem um insert que já tenha sido iniciado: um bloco que já está sendo gravado nas views materializadas ainda é concluído e confirmado. [S3Queue](/pt-BR/reference/engines/table-engines/integrations/s3queue) e [AzureQueue](/pt-BR/reference/engines/table-engines/integrations/azure-queue) leem e inserem dados em um único pipeline. Com a desduplicação ativada (padrão), o insert também é cancelado, e os arquivos são reprocessados posteriormente. Com a desduplicação desativada, o Batch em andamento é concluído e confirmado (como nos motores acima) para evitar a duplicação de linhas. Os dados que foram lidos, mas ainda não confirmados, são consumidos novamente mais tarde; portanto, nada é perdido, exceto no NATS básico (sem JetStream), que não pode reenviá-los e os descarta. `PAUSE` não interrompe um insert em execução e, portanto, normalmente não causa perda de dados. O NATS básico é a exceção: pausar interrompe o consumo e descarta as mensagens que já havia recebido, mas ainda não inserido, e o NATS básico não pode reenviá-las. Nenhum desses estados persiste após a reinicialização do servidor. Após uma reinicialização, as views atualizáveis retomam os agendamentos configurados, e os motores de streaming retomam o consumo. ### SYSTEM STOP Interrompe a atividade em segundo plano e a mantém interrompida: interrompe o que está em execução e impede novas execuções até `SYSTEM START`. Equivale a `PAUSE` + `CANCEL`. ```sql theme={null} SYSTEM STOP [db.]table SYSTEM STOP ALL BACKGROUND ``` ### SYSTEM START Retoma a atividade, revertendo um `SYSTEM STOP` ou `SYSTEM PAUSE` anterior. Nenhuma atividade é interrompida. ```sql theme={null} SYSTEM START [db.]table SYSTEM START ALL BACKGROUND ``` ### SYSTEM PAUSE Impede novas atividades em segundo plano, mas permite que o que estiver em execução no momento seja concluído primeiro. ```sql theme={null} SYSTEM PAUSE [db.]table SYSTEM PAUSE ALL BACKGROUND ``` ### SYSTEM CANCEL Interrompe apenas a atividade em execução, sem bloquear atividades futuras — a tabela continua sendo atualizada ou consumindo dados conforme o agendamento. Não faz nada se não houver atividade em andamento. ```sql theme={null} SYSTEM CANCEL [db.]table SYSTEM CANCEL ALL BACKGROUND ``` ### SYSTEM REFRESH Execute um ciclo extra fora do agendamento. Em uma tabela de streaming, ele é executado imediatamente, uma única vez, mesmo que a tabela esteja interrompida ou pausada. Em uma view materializada atualizável, ele se comporta como `SYSTEM REFRESH VIEW`: se a view estiver interrompida, a atualização é registrada e executada uma vez quando `SYSTEM START` a liberar. ```sql theme={null} SYSTEM REFRESH [db.]table SYSTEM REFRESH ALL BACKGROUND ``` ### Privilégios Cada comando exige o privilégio do mecanismo correspondente: `SYSTEM VIEWS` para uma view materializada atualizável e `SYSTEM STREAMING ENGINES` para uma tabela de streaming. Ambos são subordinados a `SYSTEM BACKGROUND`; portanto, conceder `SYSTEM BACKGROUND` permite controlar a atividade em segundo plano de todas essas tabelas. As formas `ALL BACKGROUND` se aplicam apenas às tabelas que o usuário tem permissão para controlar e ignoram silenciosamente as demais. ## SYSTEM FLUSH OBJECT STORAGE QUEUE Bloqueia até que o arquivo especificado seja processado ou falhe permanentemente pela tabela [S3Queue](/pt-BR/reference/engines/table-engines/integrations/s3queue) ou [AzureQueue](/pt-BR/reference/engines/table-engines/integrations/azure-queue) informada. Retorna imediatamente se o arquivo já tiver sido processado. Gera um erro se o arquivo tiver falhado permanentemente (todas as tentativas esgotadas). ```sql theme={null} SYSTEM FLUSH OBJECT STORAGE QUEUE [db.]table_name PATH 'path' ``` ## SYSTEM ENABLE|DISABLE FAILPOINT Fail points são pontos nomeados no código do servidor onde uma falha pode ser injetada sob demanda — um erro, um atraso ou uma pausa da thread em execução — para fins de teste. Eles são listados na tabela [`system.fail_points`](/pt-BR/reference/system-tables/fail_points) junto com seu estado atual. ```sql theme={null} SYSTEM ENABLE FAILPOINT name SYSTEM DISABLE FAILPOINT name SYSTEM DISABLE ALL FAILPOINTS SYSTEM WAIT FAILPOINT name [PAUSE|RESUME] SYSTEM NOTIFY FAILPOINT name ``` `SYSTEM ENABLE FAILPOINT` arma um único fail point; `SYSTEM DISABLE FAILPOINT` o desarma e retoma qualquer thread bloqueada nele, sendo um no-op caso ele não estivesse habilitado. `SYSTEM DISABLE ALL FAILPOINTS` desabilita todos os fail points de uma só vez e retoma todas as threads bloqueadas em um fail point pausável. Não recebe nome e é idempotente, de modo que um conjunto de testes pode usá-lo para devolver o servidor a um estado que não injeta nada, sem precisar saber quais fail points o teste anterior habilitou. Em uma compilação sem suporte a fail points, a instrução é executada com sucesso e não faz nada. `SYSTEM WAIT FAILPOINT ... PAUSE` bloqueia até que uma thread pause no fail point pausável informado (ou até que o fail point seja desabilitado), `... RESUME` bloqueia até que a thread pausada seja retomada, e `SYSTEM NOTIFY FAILPOINT` retoma as threads pausadas sem desabilitar o fail point. Fail points são estado local do node, portanto nenhuma dessas instruções aceita `ON CLUSTER`. Todas elas exigem o privilégio `SYSTEM FAILPOINT`.