clickhouse-local - ClickHouse Documentation

Quando usar clickhouse-local vs. ClickHouse

clickhouse-local é uma versão do ClickHouse fácil de usar, ideal para desenvolvedores que precisam processar rapidamente arquivos locais e remotos usando SQL, sem precisar instalar um servidor de banco de dados completo. Com o clickhouse-local, os desenvolvedores podem usar comandos SQL (com o dialeto ClickHouse SQL) diretamente na linha de comando, o que oferece uma maneira simples e eficiente de acessar os recursos do ClickHouse sem a necessidade de uma instalação completa. Um dos principais benefícios do clickhouse-local é que ele já vem incluído na instalação do clickhouse-client. Isso significa que os desenvolvedores podem começar a usar o clickhouse-local rapidamente, sem passar por um processo de instalação complexo. Embora o clickhouse-local seja uma ótima ferramenta para desenvolvimento, testes e processamento de arquivos, ele não é adequado para atender usuários finais nem aplicações. Nesses cenários, recomenda-se usar o ClickHouse de código aberto. O ClickHouse é um poderoso banco de dados OLAP projetado para lidar com cargas de trabalho analíticas em grande escala. Ele oferece processamento rápido e eficiente de consultas complexas em grandes conjuntos de dados, o que o torna ideal para ambientes de produção em que alto desempenho é essencial. Além disso, o ClickHouse oferece uma ampla variedade de recursos, como replicação, sharding e alta disponibilidade, que são essenciais para escalar e lidar com grandes conjuntos de dados, além de atender aplicações. Se você precisa lidar com conjuntos de dados maiores ou atender usuários finais ou aplicações, recomendamos usar o ClickHouse de código aberto em vez do clickhouse-local. Leia a documentação abaixo, que mostra exemplos de casos de uso do clickhouse-local, como consultar um arquivo local ou ler um arquivo Parquet no S3.

Baixe o clickhouse-local

O clickhouse-local é executado usando o mesmo binário clickhouse que executa o servidor ClickHouse e o clickhouse-client. A forma mais fácil de baixar a versão mais recente é com o seguinte comando:

curl https://clickhouse.com/ | sh

O binário que você acabou de baixar pode executar todos os tipos de ferramentas e utilitários do ClickHouse. Se você quiser executar o ClickHouse como um servidor de banco de dados, confira o Quick Start.

Consultar dados em um arquivo usando SQL

Um uso comum do clickhouse-local é executar consultas ad hoc em arquivos, sem precisar inserir os dados em uma tabela. O clickhouse-local pode ler os dados de um arquivo em uma tabela temporária e executar seu SQL. Se o arquivo estiver na mesma máquina que o clickhouse-local, você pode simplesmente especificar o arquivo a ser carregado. O arquivo reviews.tsv a seguir contém uma amostra de avaliações de produtos da Amazon:

./clickhouse local -q "SELECT * FROM 'reviews.tsv'"

Este comando é um atalho para:

./clickhouse local -q "SELECT * FROM file('reviews.tsv')"

O ClickHouse reconhece, pela extensão do nome do arquivo, que ele usa um formato separado por tabulação. Se precisar especificar explicitamente o formato, basta adicionar um dos muitos formatos de entrada do ClickHouse:

./clickhouse local -q "SELECT * FROM file('reviews.tsv', 'TabSeparated')"

A função de tabela file cria uma tabela, e você pode usar DESCRIBE para ver o schema inferido:

./clickhouse local -q "DESCRIBE file('reviews.tsv')"

Você pode usar globs em nomes de arquivo (consulte substituições de glob).Exemplos:

./clickhouse local -q "SELECT * FROM 'reviews*.jsonl'"
./clickhouse local -q "SELECT * FROM 'review_?.csv'"
./clickhouse local -q "SELECT * FROM 'review_{1..3}.csv'"

marketplace    Nullable(String)
customer_id    Nullable(Int64)
review_id    Nullable(String)
product_id    Nullable(String)
product_parent    Nullable(Int64)
product_title    Nullable(String)
product_category    Nullable(String)
star_rating    Nullable(Int64)
helpful_votes    Nullable(Int64)
total_votes    Nullable(Int64)
vine    Nullable(String)
verified_purchase    Nullable(String)
review_headline    Nullable(String)
review_body    Nullable(String)
review_date    Nullable(Date)

Vamos encontrar o produto com a melhor avaliação:

./clickhouse local -q "SELECT
    argMax(product_title,star_rating),
    max(star_rating)
FROM file('reviews.tsv')"

Monopoly Junior Board Game    5

Consultar dados em um arquivo Parquet no S3 da AWS

Se você tiver um arquivo no S3, use clickhouse-local e a função de tabela s3 para consultar o arquivo diretamente no S3 (sem inserir os dados em uma tabela do ClickHouse). Temos um arquivo chamado house_0.parquet em um bucket público que contém preços de imóveis vendidos no Reino Unido. Vamos ver quantas linhas ele tem:

./clickhouse local -q "
SELECT count()
FROM s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/house_parquet/house_0.parquet')"

O arquivo tem 2,7 milhões de linhas:

É sempre útil ver qual schema o ClickHouse infere a partir do arquivo:

./clickhouse local -q "DESCRIBE s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/house_parquet/house_0.parquet')"

price    Nullable(Int64)
date    Nullable(UInt16)
postcode1    Nullable(String)
postcode2    Nullable(String)
type    Nullable(String)
is_new    Nullable(UInt8)
duration    Nullable(String)
addr1    Nullable(String)
addr2    Nullable(String)
street    Nullable(String)
locality    Nullable(String)
town    Nullable(String)
district    Nullable(String)
county    Nullable(String)

Vamos ver quais são os bairros mais caros:

./clickhouse local -q "
SELECT
    town,
    district,
    count() AS c,
    round(avg(price)) AS price,
    bar(price, 0, 5000000, 100)
FROM s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/house_parquet/house_0.parquet')
GROUP BY
    town,
    district
HAVING c >= 100
ORDER BY price DESC
LIMIT 10"

LONDON    CITY OF LONDON    886    2271305    █████████████████████████████████████████████▍
LEATHERHEAD    ELMBRIDGE    206    1176680    ███████████████████████▌
LONDON    CITY OF WESTMINSTER    12577    1108221    ██████████████████████▏
LONDON    KENSINGTON AND CHELSEA    8728    1094496    █████████████████████▉
HYTHE    FOLKESTONE AND HYTHE    130    1023980    ████████████████████▍
CHALFONT ST GILES    CHILTERN    113    835754    ████████████████▋
AMERSHAM    BUCKINGHAMSHIRE    113    799596    ███████████████▉
VIRGINIA WATER    RUNNYMEDE    356    789301    ███████████████▊
BARNET    ENFIELD    282    740514    ██████████████▊
NORTHWOOD    THREE RIVERS    184    731609    ██████████████▋

Quando estiver pronto para inserir seus arquivos no ClickHouse, inicie o servidor ClickHouse e insira os resultados das funções de tabela file e s3 em uma tabela MergeTree. Consulte o Quick Start para mais detalhes.

Conversões entre formatos

Você pode usar clickhouse-local para converter dados entre diferentes formatos. Exemplo:

$ clickhouse-local --input-format JSONLines --output-format CSV --query "SELECT * FROM table" < data.json > data.csv

Os formatos são detectados automaticamente pelas extensões de arquivo:

$ clickhouse-local --query "SELECT * FROM table" < data.json > data.csv

Como atalho, você pode escrevê-lo com o argumento --copy:

$ clickhouse-local --copy < data.json > data.csv

Uso

Por padrão, o clickhouse-local tem acesso aos dados de um servidor ClickHouse no mesmo host e não depende da configuração do servidor. Ele também permite carregar a configuração do servidor usando o argumento --config-file. Para dados temporários, um diretório temporário exclusivo é criado por padrão. Uso básico (Linux):

$ clickhouse-local --structure "table_structure" --input-format "format_of_incoming_data" --query "query"

Uso básico (Mac):

$ ./clickhouse local --structure "table_structure" --input-format "format_of_incoming_data" --query "query"

clickhouse-local também é compatível com o Windows via WSL2.

Argumentos:

-S, --structure — estrutura da tabela para os dados de entrada.
--input-format — formato de entrada, TSV por padrão.
-F, --file — caminho para os dados, stdin por padrão.
-q, --query — consultas a executar, com ; como delimitador. --query pode ser especificado várias vezes, por exemplo, --query "SELECT 1" --query "SELECT 2". Não pode ser usado simultaneamente com --queries-file.
--queries-file - caminho do arquivo com as consultas a executar. --queries-file pode ser especificado várias vezes, por exemplo, --query queries1.sql --query queries2.sql. Não pode ser usado simultaneamente com --query.
--multiquery, -n – Se especificado, várias consultas separadas por ponto e vírgula podem ser listadas após a opção --query. Para maior conveniência, também é possível omitir --query e passar as consultas diretamente após --multiquery.
-N, --table — nome da tabela onde os dados de saída serão colocados, table por padrão.
-f, --format, --output-format — formato de saída, TSV por padrão.
-d, --database — banco de dados padrão, _local por padrão.
--stacktrace — se deve gerar saída de depuração em caso de exceção.
--echo [ <bool> ] — imprime cada consulta antes da execução. Aceita um valor booleano opcional. Habilitado por padrão no modo interativo e desabilitado no modo batch. Nota: como --echo agora aceita um valor opcional, uma consulta posicional colocada imediatamente após um --echo sem valor é interpretada como seu valor; use --echo --query "...", --echo -q "...", --echo=false ou stdin via pipe.
--echo-formatted [ <bool> ] — formata as consultas exibidas por echo. Aceita um valor booleano opcional. Habilitado por padrão no modo interativo e desabilitado no modo batch.
--echo-query-id [ <bool> ] — imprime o query_id antes da execução. Aceita um valor booleano opcional. Habilitado por padrão no modo interativo e desabilitado no modo batch.
--echo-query-separator <string> — imprime este separador antes da consulta formatada exibida por echo (requer --echo-formatted), facilitando distinguir a consulta digitada da sua versão reformatada exibida por echo. Vazio por padrão (desabilitado).
--highlight, --hilite <bool> — alterna o realce de sintaxe do prompt de comando e das consultas exibidas por echo. Habilitado por padrão. O realce é aplicado somente ao escrever em um terminal.
--hints <bool> — mostra dicas de autocompletar conforme você digita (texto “fantasma” em linha) para a melhor sugestão correspondente quando o cursor está no fim da entrada. Navegue pelas dicas com Up/Down (ou Ctrl-Up/Ctrl-Down); aceite a dica em linha com Tab ou Right; Enter aceita uma dica somente depois que uma tiver sido selecionada explicitamente e, caso contrário, executa a consulta; Tab também abre a lista clássica de preenchimento automático. Requer --highlight (as dicas precisam de cor) e o mecanismo de sugestão (portanto, --disable_suggestion também as desativa). Habilitado por padrão.
--verbose — mais detalhes sobre a execução da consulta.
--logger.console — Registrar no console.
--logger.log — Nome do arquivo de log.
--logger.level — Nível de log.
--ignore-error — não interrompe o processamento se uma consulta falhar.
-c, --config-file — caminho para o arquivo de configuração no mesmo formato do servidor ClickHouse; por padrão, a configuração é vazia.
--no-system-tables — não anexar as tabelas do sistema.
--help — referência dos argumentos de clickhouse-local.
-V, --version — imprime informações da versão e sai.

Além disso, há argumentos para cada variável de configuração do ClickHouse que são mais usados do que --config-file.

Comandos

Comando LS

Lista todos os arquivos no diretório de trabalho atual aos quais o clickhouse-local tem acesso. Você pode executá-lo no modo interativo assim:

Query

ClickHouse local version 26.3.1.1.

:) ls

SELECT _file AS file
FROM file('*', 'One')
ORDER BY file ASC

Response

┌─file────────┐
│ file1.csv   │
│ file2.json  │
│ file3.xml   │
└─────────────┘

Você também pode executá-lo como uma consulta usando o argumento -q:

./clickhouse-local -q ls

Response

file1.csv
file2.json
file3.xml

Comando CLEAR

Limpa a tela do terminal (semelhante ao comando clear no Linux ou a Ctrl+L em muitos terminais). Esta é uma ação do lado do cliente: não é enviada ao mecanismo SQL. No clickhouse-local, o metacomando é reconhecido no modo interativo e para entrada com -q e --queries-file (mesmo caminho no cliente que -q, mesma ideia que ls), de modo que um clear isolado não gera um erro UNKNOWN_IDENTIFIER. O clickhouse-client --queries-file remoto permanece inalterado: o conteúdo do arquivo é executado apenas como SQL (sem metacomandos em nível de texto). No clickhouse-client, ele é reconhecido apenas no modo interativo. Com -q ou arquivos de consulta, clear continua sendo interpretado como SQL, então a automação mantém o comportamento de erro anterior, em vez de transformar erros de digitação em um no-op silencioso. Formas compatíveis: clear, CLEAR, /clear (um ; opcional no final é ignorado). Se a saída padrão não for um terminal (por exemplo, ao redirecionar a saída por pipe), o metacomando é aceito quando reconhecido, mas não emite sequências de controle. Com clickhouse-local e -q:

./clickhouse-local -q clear

Exemplos

Query

$ echo -e "1,2\n3,4" | clickhouse-local --structure "a Int64, b Int64" \
    --input-format "CSV" --query "SELECT * FROM table"
Read 2 rows, 32.00 B in 0.000 sec., 5182 rows/sec., 80.97 KiB/sec.
1   2
3   4

O exemplo anterior é igual a:

Query

$ echo -e "1,2\n3,4" | clickhouse-local -n --query "
    CREATE TABLE table (a Int64, b Int64) ENGINE = File(CSV, stdin);
    SELECT a, b FROM table;
    DROP TABLE table;"
Read 2 rows, 32.00 B in 0.000 sec., 4987 rows/sec., 77.93 KiB/sec.
1   2
3   4

Você não precisa usar o argumento stdin nem --file e pode abrir qualquer número de arquivos usando a função de tabela file:

Query

$ echo 1 | tee 1.tsv
1

$ echo 2 | tee 2.tsv
2

$ clickhouse-local --query "
    select * from file('1.tsv', TSV, 'a int') t1
    cross join file('2.tsv', TSV, 'b int') t2"
1    2

Agora, vamos exibir o memory user de cada usuário Unix:

Query

$ ps aux | tail -n +2 | awk '{ printf("%s\t%s\n", $1, $4) }' \
    | clickhouse-local --structure "user String, mem Float64" \
        --query "SELECT user, round(sum(mem), 2) as memTotal
            FROM table GROUP BY user ORDER BY memTotal DESC FORMAT Pretty"

Response

Read 186 rows, 4.15 KiB in 0.035 sec., 5302 rows/sec., 118.34 KiB/sec.
┏━━━━━━━━━━┳━━━━━━━━━━┓
┃ user     ┃ memTotal ┃
┡━━━━━━━━━━╇━━━━━━━━━━┩
│ bayonet  │    113.5 │
├──────────┼──────────┤
│ root     │      8.8 │
├──────────┼──────────┤
...

Iniciando listeners TCP e HTTP

O clickhouse-local pode ser transformado em um servidor leve que aceita conexões TCP (protocolo nativo) e HTTP. Isso é útil quando você quer permitir que outras ferramentas ou aplicações do ClickHouse acessem os bancos de dados e as tabelas de uma instância do clickhouse-local em execução. Observe que cada conexão de entrada recebe sua própria sessão: as tabelas temporárias e as configurações de sessão da sessão interativa do clickhouse-local não ficam visíveis para conexões externas. Use SYSTEM START LISTEN para abrir um listener e SYSTEM STOP LISTEN para fechá-lo:

clickhouse-local \
    --listen_host 127.0.0.1 \
    --tcp_port 9000 \
    --http_port 8123 \
    --query "
        SYSTEM START LISTEN TCP;
        SYSTEM START LISTEN HTTP;
        SELECT * FROM url('http://127.0.0.1:8123/?query=SELECT+42', LineAsString);
        SYSTEM STOP LISTEN TCP;
        SYSTEM STOP LISTEN HTTP;
    "

As opções --listen_host, --tcp_port e --http_port configuram o endereço de escuta e as portas. As portas padrão são 9000 para TCP e 8123 para HTTP.

SegurançaPor padrão, o clickhouse-local é executado com a configuração temporária de usuários, portanto qualquer porta de escuta que ele abra não terá autenticação. Vincule-o a um endereço de loopback (127.0.0.1 ou ::1), a menos que você tenha configurado explicitamente os usuários e o controle de acesso apontando a configuração users_config para um users.xml personalizado (por exemplo, via --config-file). Escutar em um endereço que não seja de loopback sem autenticação expõe os dados da instância local a qualquer pessoa que consiga acessar a porta escolhida.

​Quando usar clickhouse-local vs. ClickHouse

​Baixe o clickhouse-local

​Consultar dados em um arquivo usando SQL

​Consultar dados em um arquivo Parquet no S3 da AWS

​Conversões entre formatos

​Uso

​Comandos

​Comando LS

​Comando CLEAR

​Exemplos

​Iniciando listeners TCP e HTTP

​Conteúdo relacionado

Quando usar clickhouse-local vs. ClickHouse

Baixe o clickhouse-local

Consultar dados em um arquivo usando SQL

Consultar dados em um arquivo Parquet no S3 da AWS

Conversões entre formatos

Uso

Comandos

Comando LS

Comando CLEAR

Exemplos

Iniciando listeners TCP e HTTP

Conteúdo relacionado