Saltar al contenido principal
clickhouse-local es una CLI con una versión integrada de ClickHouse. Permite a los usuarios aprovechar la potencia de ClickHouse sin tener que instalar un servidor. En esta guía, aprenderemos a usar una base de datos clickhouse-local desde chDB.

Configuración

Primero, creemos un entorno virtual:
python -m venv .venv
source .venv/bin/activate
Y ahora instalaremos chDB. Asegúrate de tener la versión 2.0.2 o posterior:
pip install "chdb>=2.0.2"
Ahora vamos a instalar ipython:
pip install ipython
Vamos a usar ipython para ejecutar los comandos del resto de la guía, que puedes iniciar con:
ipython

Instalar clickhouse-local

Descargar e instalar clickhouse-local es igual que descargar e instalar ClickHouse. Podemos hacerlo ejecutando el siguiente comando:
curl https://clickhouse.com/ | sh
Para iniciar clickhouse-local con los datos guardados en un directorio, debemos indicar --path:
./clickhouse -m --path demo.chdb

Ingesta de datos en clickhouse-local

La base de datos predeterminada solo almacena datos en memoria, así que tendremos que crear una base de datos con un nombre específico para asegurarnos de que cualquier dato que ingestemos persista en disco.
CREATE DATABASE foo;
Vamos a crear una tabla e insertar unos números aleatorios:
CREATE TABLE foo.randomNumbers
ORDER BY number AS
SELECT rand() AS number
FROM numbers(10_000_000);
Escribamos una consulta para ver qué datos tenemos:
SELECT quantilesExact(0, 0.5, 0.75, 0.99)(number) AS quants
FROM foo.randomNumbers
┌─quants────────────────────────────────┐
│ [69,2147776478,3221525118,4252096960] │
└───────────────────────────────────────┘
Una vez hecho esto, asegúrate de salir de la CLI con exit;, ya que solo un proceso puede mantener un bloqueo sobre este directorio. Si no lo hacemos, obtendremos el siguiente error cuando intentemos conectarnos a la base de datos desde chDB:
ChdbError: Code: 76. DB::Exception: Cannot lock file demo.chdb/status. Another server instance in same directory is already running. (CANNOT_OPEN_FILE)

Conectarse a una base de datos clickhouse-local

Vuelve a la consola de ipython e importa el módulo session de chDB:
from chdb import session as chs
Inicializa una sesión que apunte a demo.chdb:
sess = chs.Session("demo.chdb")
Luego, podemos ejecutar la misma consulta que devuelve los cuantiles de números:
sess.query("""
SELECT quantilesExact(0, 0.5, 0.75, 0.99)(number) AS quants
FROM foo.randomNumbers
""", "Vertical")

Row 1:
──────
quants: [0,9976599,2147776478,4209286886]
También podemos insertar datos en esta base de datos desde chDB:
sess.query("""
INSERT INTO foo.randomNumbers
SELECT rand() AS number FROM numbers(10_000_000)
""")

Row 1:
──────
quants: [0,9976599,2147776478,4209286886]
A continuación, podemos volver a ejecutar la consulta de cuantiles desde chDB o clickhouse-local.
Última modificación el 19 de junio de 2026