Pular para o conteúdo principal
Os dados processados no ClickHouse geralmente são armazenados no sistema de arquivos local da máquina em que o servidor ClickHouse está em execução. Isso exige discos de grande capacidade, que podem ser caros. Para evitar armazenar dados localmente, há suporte às seguintes opções de armazenamento:
  1. armazenamento de objetos Amazon S3.
  2. Azure Blob Storage.
  3. Sem suporte: Hadoop Distributed File System (HDFS)

O ClickHouse também oferece suporte a motores de tabela externos, que são diferentes da opção de armazenamento externo descrita nesta página, pois permitem ler dados armazenados em formatos de arquivo genéricos (como Parquet). Nesta página, estamos descrevendo a configuração de armazenamento para tabelas da família MergeTree ou da família Log do ClickHouse.
  1. para trabalhar com dados armazenados em discos Amazon S3, use o motor de tabela S3.
  2. para trabalhar com dados armazenados no Azure Blob Storage, use o motor de tabela AzureBlobStorage.
  3. para trabalhar com dados no Hadoop Distributed File System (sem suporte), use o motor de tabela HDFS.

​
Configurar armazenamento externo

Os motores de tabela das famílias MergeTree e Log podem armazenar dados em S3, AzureBlobStorage e HDFS (não compatível) usando um disco dos tipos s3, azure_blob_storage e hdfs (não compatível), respectivamente. A configuração do disco exige:
  1. Uma seção type, igual a um destes valores: s3, azure_blob_storage, hdfs (não compatível), local_blob_storage, web.
  2. A configuração de um tipo específico de armazenamento externo.
A partir da versão 24.1 do ClickHouse, é possível usar uma nova opção de configuração. Ela exige especificar:
  1. Um type igual a object_storage
  2. object_storage_type, igual a um destes valores: s3, azure_blob_storage (ou apenas azure a partir da 24.3), hdfs (não compatível), local_blob_storage (ou apenas local a partir da 24.3), web.

Opcionalmente, metadata_type pode ser especificado (o padrão é local), mas também pode ser definido como plain, web e, a partir da 24.4, plain_rewritable. O uso do tipo de metadados plain é descrito na seção de plain storage; o tipo de metadados web só pode ser usado com o tipo de armazenamento de objetos web; o tipo de metadados local armazena os arquivos de metadados localmente (cada arquivo de metadados contém o mapeamento para arquivos no armazenamento de objetos e algumas metainformações adicionais sobre eles). Por exemplo:
corresponde à seguinte configuração (a partir da versão 24.1):
A configuração a seguir:
é igual a:
Um exemplo de configuração completa de armazenamento será o seguinte:
A partir da versão 24.1, também pode ser assim:
Para definir um tipo específico de armazenamento como opção padrão para todas as tabelas MergeTree, adicione a seguinte seção ao arquivo de configuração:
Se você quiser configurar uma política de armazenamento específica para uma tabela específica, poderá defini-la nas configurações ao criar a tabela:
Você também pode usar disk em vez de storage_policy. Nesse caso, não é necessário ter a seção storage_policy no arquivo de configuração; basta uma seção disk.

​
refresh_parts_interval and table_disk

Esta configuração se destina a tabelas MergeTree não replicadas, nas quais as partes podem ser gravadas externamente e a descoberta de metadados precisa ser atualizada a partir do armazenamento. A configuração do MergeTree refresh_parts_interval permite atualizar periodicamente a lista de partes de dados a partir do armazenamento subjacente (por exemplo, para reconhecer partes gravadas externamente). A distinção importante é entre metadados compartilhados entre réplicas e metadados locais à réplica (por exemplo, S3 com metadados locais por réplica): somente quando os metadados são compartilhados as novas partes ficam visíveis para todas as réplicas. Usar apenas armazenamento de objetos não implica metadados compartilhados.
  • Armazenamento de objetos (por exemplo, disk = 's3') não implica metadados compartilhados. Quando os metadados são armazenados localmente por réplica (o padrão), cada réplica gerencia de forma independente seus ponteiros para blobs no armazenamento de objetos. Alterações feitas em uma réplica não ficam visíveis para as outras. Nesse caso, refresh_parts_interval não torna novas partes visíveis entre réplicas, porque os metadados que cada réplica lê são locais à própria réplica.
  • A atualização automática de partes exige que os metadados do sistema de arquivos sejam compartilhados (ou que a tabela use metadados somente leitura pertencentes à própria tabela, para que a atualização se aplique). Definir table_disk = true junto com um disco local da tabela (por exemplo, SETTINGS disk = disk(type=object_storage, ...), table_disk = true) é uma forma de obter a semântica correta: a tabela controla o ciclo de vida dos metadados e o armazenamento é tratado como somente leitura, de modo que refresh_parts_interval é executado e partes adicionadas externamente podem ser descobertas.
  • Com um disco definido globalmente (por exemplo, disk = 's3' em storage_configuration) e metadados locais padrão, cada réplica tem seu próprio estado de metadados. Embora os blobs possam estar no S3, o armazenamento não é considerado compartilhado para fins de refresh_parts_interval, e novas partes criadas fora do ClickHouse ou em outra réplica não serão detectadas.
Para a atualização automática de partes, garanta que os metadados sejam compartilhados ou use um disco no nível da tabela com table_disk = true, como acima. Confiar apenas em refresh_parts_interval com metadados locais à réplica não atualizará as partes como esperado.
refresh_parts_interval não é usado para tabelas ReplicatedMergeTree. As tabelas replicadas já sincronizam partes por meio do mecanismo de replicação. Esta configuração se aplica apenas a tabelas MergeTree não replicadas nas quais as partes são gravadas externamente e a atualização de metadados é necessária.

​
Configuração dinâmica

Também é possível especificar a configuração de armazenamento sem um disco predefinido no arquivo de configuração; em vez disso, ela pode ser definida nas configurações da consulta CREATE/ATTACH. A consulta de exemplo a seguir se baseia na configuração dinâmica de disco acima e mostra como usar um disco local para armazenar em cache dados de uma tabela armazenada em uma URL.
O exemplo abaixo adiciona um cache ao armazenamento externo.
Nas configurações destacadas abaixo, observe que o disco de type=web está aninhado no disco de type=cache.
O exemplo usa type=web, mas qualquer tipo de disco pode ser configurado como dinâmico, incluindo disco local. Discos locais exigem que o argumento path esteja dentro do parâmetro de configuração do servidor custom_local_disks_base_directory, que não tem valor padrão; portanto, defina-o também ao usar disco local.
Também é possível combinar a configuração baseada em arquivo de configuração com a configuração definida em SQL:
em que web vem do arquivo de configuração do servidor:

​
Usando o armazenamento S3

​
Parâmetros obrigatórios

​
Parâmetros opcionais

O Google Cloud Storage (GCS) também é compatível com o tipo s3. Consulte GCS backed MergeTree.

​
Usando Plain Storage

Na versão 22.10, foi introduzido um novo tipo de disco, s3_plain, que oferece armazenamento de gravação única. Os parâmetros de configuração dele são os mesmos do tipo de disco s3. Diferentemente do tipo de disco s3, ele armazena os dados como estão. Em outras palavras, em vez de usar nomes de blob gerados aleatoriamente, ele usa nomes de arquivo normais (da mesma forma que o ClickHouse armazena arquivos no disco local) e não armazena metadados localmente. Por exemplo, ele é derivado dos dados em s3. Esse tipo de disco permite manter uma versão estática da tabela, pois não permite executar mesclagens nos dados existentes nem inserir novos dados. Um caso de uso desse tipo de disco é criar backups nele, o que pode ser feito via BACKUP TABLE data TO Disk('plain_disk_name', 'backup_name'). Depois, você pode executar RESTORE TABLE data AS data_restored FROM Disk('plain_disk_name', 'backup_name') ou usar ATTACH TABLE data (...) ENGINE = MergeTree() SETTINGS disk = 'plain_disk_name'. Configuração:
A partir da versão 24.1, é possível configurar qualquer disco de armazenamento de objetos (s3, azure, hdfs (não compatível), local) usando o tipo de metadados plain. Configuração:

​
Usando o armazenamento S3 Plain Rewritable

Um novo tipo de disco s3_plain_rewritable foi introduzido na versão 24.4. Assim como o tipo de disco s3_plain, ele não requer armazenamento adicional para arquivos de metadados. Em vez disso, os metadados são armazenados no S3. Ao contrário do tipo de disco s3_plain, o s3_plain_rewritable permite executar mesclagens e oferece suporte a operações INSERT. Mutações e a replicação de tabelas não são suportadas. Um caso de uso desse tipo de disco é em tabelas MergeTree não replicadas. Embora o tipo de disco s3 seja adequado para tabelas MergeTree não replicadas, você pode optar pelo tipo de disco s3_plain_rewritable se não precisar de metadados locais para a tabela e estiver disposto a aceitar um conjunto limitado de operações. Isso pode ser útil, por exemplo, para tabelas de sistema. Configuração:
é igual a
A partir da versão 24.5, é possível configurar qualquer disco de armazenamento de objetos (s3, azure, local) com o tipo de metadados plain_rewritable.

​
Usando o Azure Blob Storage

Os motores de tabela da família MergeTree podem armazenar dados no Azure Blob Storage usando um disco do tipo azure_blob_storage. Trecho de configuração:

​
Parâmetros de conexão

Parâmetros de autenticação (o disco tentará todos os métodos disponíveis e Managed Identity Credential):

​
Parâmetros de limite

​
Outros parâmetros

Exemplos de configurações funcionais podem ser encontrados no diretório de testes de integração (veja, por exemplo, test_merge_tree_azure_blob_storage ou test_azure_blob_storage_zero_copy_replication).
A replicação zero-copy não está pronta para produçãoA replicação zero-copy é desabilitada por padrão no ClickHouse versão 22.8 e posteriores. Este recurso não é recomendado para uso em produção.

​
Usando armazenamento HDFS (sem suporte)

Nesta configuração de exemplo:
  • o disco é do tipo hdfs (sem suporte)
  • os dados estão hospedados em hdfs://hdfs1:9000/clickhouse/
Vale lembrar que o HDFS não tem suporte e, portanto, podem ocorrer problemas ao usá-lo. Fique à vontade para enviar um pull request com a correção caso surja algum problema.
Tenha em mente que o HDFS pode não funcionar em casos de borda.

​
Usando criptografia de dados

Você pode criptografar os dados armazenados em discos externos S3 ou HDFS (sem suporte), ou em um disco local. Para ativar o modo de criptografia, no arquivo de configuração, você deve definir um disco do tipo encrypted e escolher o disco em que os dados serão salvos. Um disco encrypted criptografa todos os arquivos gravados em tempo real e, quando você lê arquivos de um disco encrypted, ele os descriptografa automaticamente. Assim, você pode trabalhar com um disco encrypted como se fosse um disco normal. Exemplo de configuração de disco:
Por exemplo, quando o ClickHouse grava dados de uma tabela no arquivo store/all_1_1_0/data.bin em disk1, na prática, esse arquivo será gravado no disco físico no caminho /path1/store/all_1_1_0/data.bin. Ao gravar o mesmo arquivo em disk2, ele será, na prática, gravado no disco físico no caminho /path1/path2/store/all_1_1_0/data.bin, em modo criptografado.

​
Parâmetros obrigatórios

​
Parâmetros opcionais

Exemplo de configuração de disco:

​
Usando cache local

É possível configurar cache local em discos na configuração de armazenamento a partir da versão 22.3. Nas versões 22.3 - 22.7, o cache é suportado apenas para o tipo de disco s3. Nas versões >= 22.8, o cache é suportado para qualquer tipo de disco: S3, Azure, Local, Encrypted etc. Nas versões >= 23.5, o cache é suportado apenas para tipos de disco remotos: S3, Azure, HDFS (não suportado). O cache usa a política de cache LRU. Exemplo de configuração para versões iguais ou posteriores à 22.8:
Exemplo de configuração para versões anteriores à 22.8:
Configurações de disco do File Cache: Essas configurações devem ser definidas na seção de configuração de disco.
Observação: Valores de tamanho aceitam unidades como ki, Mi, Gi etc. (por exemplo, 10Gi).

​
Configurações de consulta/perfil do cache do sistema de arquivos

As configurações do cache e as configurações de consulta do cache correspondem à versão mais recente do ClickHouse; em versões anteriores, alguns recursos podem não ter suporte.

​
Tabelas de sistema do cache

​
Comandos do cache

SYSTEM CLEAR|DROP FILESYSTEM CACHE (<cache_name>) (ON CLUSTER) — ON CLUSTER
Este comando só é compatível quando nenhum <cache_name> é fornecido
SHOW FILESYSTEM CACHES
Exibe uma lista dos caches do sistema de arquivos configurados no servidor. (Em versões menores ou iguais à 22.8, o comando se chama SHOW CACHES)
Query
Response
DESCRIBE FILESYSTEM CACHE '<cache_name>'
Mostra a configuração do cache e algumas estatísticas gerais de um cache específico. O nome do cache pode ser obtido com o comando SHOW FILESYSTEM CACHES. (Para versões anteriores ou iguais à 22.8, o comando se chama DESCRIBE CACHE)
Query
Response

​
Usando armazenamento web estático (somente leitura)

Este é um disco somente leitura. Seus dados apenas são lidos e nunca modificados. Uma nova tabela é carregada nesse disco com a consulta ATTACH TABLE (veja o exemplo abaixo). O disco local não é efetivamente usado; cada consulta SELECT resultará em uma requisição http para buscar os dados necessários. Qualquer modificação nos dados da tabela resultará em uma exceção, ou seja, os seguintes tipos de consultas não são permitidos: CREATE TABLE, ALTER TABLE, RENAME TABLE, DETACH TABLE e TRUNCATE TABLE. O armazenamento web pode ser usado para fins de somente leitura. Um exemplo de uso é hospedar dados de exemplo ou migrar dados. Há uma ferramenta, clickhouse-static-files-uploader, que prepara um diretório de dados para uma determinada tabela (SELECT data_paths FROM system.tables WHERE name = 'table_name'). Para cada tabela necessária, você obtém um diretório de arquivos. Esses arquivos podem ser enviados para, por exemplo, um servidor web de arquivos estáticos. Após essa preparação, você pode carregar essa tabela em qualquer servidor ClickHouse por meio de DiskWeb. Nesta configuração de exemplo:
  • o disco é do tipo web
  • os dados são hospedados em http://nginx:80/test1/
  • um cache no armazenamento local é usado
O armazenamento também pode ser configurado temporariamente em uma consulta, caso não se espere usar um dataset da web com frequência; consulte a configuração dinâmica e evite editar o arquivo de configuração.Um dataset de demonstração está hospedado no GitHub. Para preparar suas próprias tabelas para armazenamento web, consulte a ferramenta clickhouse-static-files-uploader
Nesta consulta ATTACH TABLE, o UUID fornecido corresponde ao nome do diretório dos dados, e o endpoint é a URL do conteúdo bruto no GitHub.
Um caso de teste pronto para uso. Você precisa adicionar esta configuração a config:
Em seguida, execute esta consulta:

​
Parâmetros obrigatórios

​
Parâmetros opcionais

Se uma consulta falhar com a exceção DB:Exception Unreachable URL, você pode tentar ajustar as configurações: http_connection_timeout, http_receive_timeout, keep_alive_timeout. Para gerar os arquivos para upload, execute: clickhouse static-files-disk-uploader --metadata-path <path> --output-dir <dir> (--metadata-path pode ser encontrado na consulta SELECT data_paths FROM system.tables WHERE name = 'table_name'). Ao carregar arquivos por endpoint, eles devem ser carregados no caminho <endpoint>/store/, mas a configuração deve conter apenas endpoint. Se a URL não estiver acessível durante o carregamento do disco, quando o servidor estiver inicializando as tabelas, todos os erros serão capturados. Se, nesse caso, ocorrerem erros, as tabelas poderão ser recarregadas (e ficar visíveis) por meio de DETACH TABLE table_name -> ATTACH TABLE table_name. Se os metadados tiverem sido carregados com sucesso na inicialização do servidor, as tabelas ficarão disponíveis imediatamente. Use a configuração http_max_single_read_retries para limitar o número máximo de tentativas durante uma única leitura HTTP.

​
Replicação zero-copy (não pronta para produção)

A replicação zero-copy é possível, mas não é recomendada, com discos S3 e HDFS (não compatível). Replicação zero-copy significa que, se os dados estiverem armazenados remotamente em várias máquinas e precisarem ser sincronizados, apenas os metadados serão replicados (caminhos para as partes de dados), e não os dados em si.
A replicação zero-copy não está pronta para produçãoA replicação zero-copy vem desabilitada por padrão no ClickHouse versão 22.8 e posteriores. Este recurso não é recomendado para uso em produção.
Última modificação em 29 de junho de 2026