Como usar um banco de dados clickhouse-local

clickhouse-local é uma CLI com uma versão embutida do ClickHouse. Ela permite usar o poder do ClickHouse sem precisar instalar um servidor. Neste guia, aprenderemos a usar um banco de dados clickhouse-local com o chDB.

Primeiro, vamos criar um ambiente virtual:

python -m venv .venv
source .venv/bin/activate

Agora vamos instalar o chDB. Certifique-se de que você tenha a versão 2.0.2 ou superior:

pip install "chdb>=2.0.2"

Agora, vamos instalar ipython:

pip install ipython

Vamos usar o ipython para executar os comandos do restante do guia, que você pode iniciar com:

ipython

Fazer o download e instalar o clickhouse-local é igual a fazer o download e instalar o ClickHouse. Podemos fazer isso executando o seguinte comando:

curl https://clickhouse.com/ | sh

Para iniciar o clickhouse-local com os dados persistidos em um diretório, precisamos informar um --path:

./clickhouse -m --path demo.chdb

O banco de dados padrão armazena dados apenas na memória, então precisamos criar um banco de dados com nome para garantir que os dados ingeridos sejam persistidos em disco.

CREATE DATABASE foo;

Vamos criar uma tabela e inserir alguns números aleatórios:

CREATE TABLE foo.randomNumbers
ORDER BY number AS
SELECT rand() AS number
FROM numbers(10_000_000);

Vamos escrever uma consulta para ver quais dados temos:

SELECT quantilesExact(0, 0.5, 0.75, 0.99)(number) AS quants
FROM foo.randomNumbers

┌─quants────────────────────────────────┐
│ [69,2147776478,3221525118,4252096960] │
└───────────────────────────────────────┘

Depois de fazer isso, certifique-se de executar exit; na CLI, pois apenas um processo pode manter um bloqueio neste diretório. Se não fizermos isso, receberemos o seguinte erro ao tentar nos conectar ao banco de dados pelo chDB:

ChdbError: Code: 76. DB::Exception: Cannot lock file demo.chdb/status. Another server instance in same directory is already running. (CANNOT_OPEN_FILE)

Volte ao shell ipython e importe o módulo session do chDB:

from chdb import session as chs

Inicialize uma sessão apontando para demo.chdb:

sess = chs.Session("demo.chdb")

Podemos então executar a mesma consulta que retorna os quantis dos números:

sess.query("""
SELECT quantilesExact(0, 0.5, 0.75, 0.99)(number) AS quants
FROM foo.randomNumbers
""", "Vertical")

Linha 1:
──────
quants: [0,9976599,2147776478,4209286886]

Também podemos inserir dados nesse banco de dados usando o chDB:

sess.query("""
INSERT INTO foo.randomNumbers
SELECT rand() AS number FROM numbers(10_000_000)
""")

Linha 1:
──────
quants: [0,9976599,2147776478,4209286886]

Podemos então executar novamente a consulta de quantis no chDB ou no clickhouse-local.