Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

clickhouse-local

View as MarkdownEdit this pageReport an issueSet up docs MCP

Cuándo usar clickhouse-local vs. ClickHouse

clickhouse-local es una versión de ClickHouse fácil de usar, ideal para desarrolladores que necesitan procesar rápidamente archivos locales y remotos con SQL sin tener que instalar un servidor de base de datos completo. Con clickhouse-local, los desarrolladores pueden usar comandos SQL (con el dialecto SQL de ClickHouse) directamente desde la línea de comandos, lo que ofrece una forma sencilla y eficiente de acceder a las capacidades de ClickHouse sin necesidad de una instalación completa. Uno de los principales beneficios de clickhouse-local es que ya se incluye al instalar clickhouse-client. Esto significa que los desarrolladores pueden empezar a usar clickhouse-local rápidamente, sin necesidad de un proceso de instalación complejo.

Aunque clickhouse-local es una excelente herramienta para desarrollo, pruebas y procesamiento de archivos, no es adecuado para dar servicio a usuarios finales ni a aplicaciones. En estos casos, se recomienda usar la versión open-source de ClickHouse. ClickHouse es una potente base de datos OLAP diseñada para gestionar cargas de trabajo analíticas a gran escala. Proporciona un procesamiento rápido y eficiente de consultas complejas sobre grandes conjuntos de datos, lo que la hace ideal para entornos de producción en los que el alto rendimiento es fundamental. Además, ClickHouse ofrece una amplia gama de capacidades, como replicación, sharding y alta disponibilidad, que son esenciales para escalar, manejar grandes conjuntos de datos y dar servicio a aplicaciones. Si necesita manejar conjuntos de datos más grandes o dar servicio a usuarios finales o aplicaciones, le recomendamos usar la versión open-source de ClickHouse en lugar de clickhouse-local.

Consulte la documentación a continuación, donde se muestran casos de uso de clickhouse-local, como consultar un archivo local o leer un archivo Parquet en S3.

Descargar clickhouse-local

clickhouse-local se ejecuta con el mismo binario clickhouse que utiliza el servidor ClickHouse y clickhouse-client. La forma más sencilla de descargar la versión más reciente es con el siguiente comando:

curl https://clickhouse.com/ | sh

Consultar datos de un archivo con SQL

Un uso habitual de clickhouse-local es ejecutar consultas ad hoc sobre archivos, sin tener que insertar los datos en una tabla. clickhouse-local puede leer los datos de un archivo en una tabla temporal y ejecutar tu SQL.

Si el archivo está en la misma máquina que clickhouse-local, puedes simplemente especificar el archivo que quieres cargar. El siguiente archivo reviews.tsv contiene una muestra de reseñas de productos de Amazon:

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

Este comando es una abreviatura de:

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

ClickHouse reconoce por la extensión del nombre del archivo que usa un formato separado por tabulaciones. Si necesitas especificar el formato explícitamente, simplemente agrega uno de los muchos formatos de entrada de ClickHouse:

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

La función de tabla file crea una tabla y puedes usar DESCRIBE para ver el esquema inferido:

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

Los datos no tienen que ser locales: se puede usar una URL en lugar de un nombre de archivo, y el esquema de URL selecciona el motor de tabla correspondiente (http:// y https:// se leen como la función url, s3:// como la función s3, file:// como la función file):

./clickhouse local -q "SELECT * FROM 'https://datasets-documentation.s3.eu-west-3.amazonaws.com/aapl_stock.csv' LIMIT 3"
./clickhouse local -q "SELECT count() FROM 's3://clickhouse-public-datasets/hits_compatible/athena_partitioned/hits_1.parquet'"
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)

Busquemos un producto con la valoración más alta:

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

Consultar datos en un archivo Parquet en AWS S3

Si tienes un archivo en S3, usa clickhouse-local y la función de tabla s3 para consultar el archivo directamente (sin insertar los datos en una tabla de ClickHouse). Tenemos un archivo llamado house_0.parquet en un bucket público que contiene los precios de las viviendas vendidas en el Reino Unido. Veamos cuántas filas tiene:

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

El archivo tiene 2,7 millones de filas:

2772030

Siempre es útil ver cuál es el esquema que ClickHouse infiere a partir del archivo:

./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)

Veamos cuáles son los barrios más 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    ██████████████▋

Conversión entre formatos

Puede usar clickhouse-local para convertir datos entre distintos formatos. Ejemplo:

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

Los formatos se detectan automáticamente a partir de las extensiones de archivo:

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

Como método abreviado, puede escribirlo con el argumento --copy:

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

Uso

De forma predeterminada, clickhouse-local tiene acceso a los datos de un servidor ClickHouse en el mismo host y no depende de la configuración del servidor. También permite cargar la configuración del servidor mediante el argumento --config-file. Para los datos temporales, se crea por defecto un directorio temporal de datos único.

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"

Argumentos:

  • -S, --structure — estructura de la tabla para los datos de entrada.
  • --input-format — formato de entrada; TSV de forma predeterminada.
  • -F, --file — ruta de los datos; stdin de forma predeterminada.
  • -q, --query — consultas que se ejecutarán usando ; como delimitador. --query puede especificarse varias veces; p. ej., --query "SELECT 1" --query "SELECT 2". No puede usarse simultáneamente con --queries-file.
  • --queries-file - ruta del archivo con las consultas que se ejecutarán. --queries-file puede especificarse varias veces; p. ej., --query queries1.sql --query queries2.sql. No puede usarse simultáneamente con --query.
  • --multiquery, -n – Si se especifica, se pueden indicar varias consultas separadas por punto y coma después de la opción --query. Para mayor comodidad, también es posible omitir --query y pasar las consultas directamente después de --multiquery.
  • -N, --table — nombre de la tabla en la que se colocarán los datos de salida; table de forma predeterminada.
  • -f, --format, --output-format — formato de salida; TSV de forma predeterminada.
  • -d, --database — base de datos predeterminada; _local de forma predeterminada.
  • --stacktrace — indica si se debe volcar la salida de depuración en caso de excepción.
  • --echo [ <bool> ] — imprime cada consulta antes de ejecutarla. Acepta un valor booleano opcional. Está habilitado de forma predeterminada en modo interactivo y deshabilitado en modo por lotes. Nota: dado que --echo ahora acepta un valor opcional, una consulta posicional colocada inmediatamente después de un --echo sin valor se interpreta como su valor; use --echo --query "...", --echo -q "...", --echo=false o redirija stdin en su lugar.
  • --echo-formatted [ <bool> ] — da formato a las consultas mostradas por echo. Acepta un valor booleano opcional. Está habilitado de forma predeterminada en modo interactivo y deshabilitado en modo por lotes.
  • --echo-query-id [ <bool> ] — imprime el query_id antes de la ejecución. Acepta un valor booleano opcional. Está habilitado de forma predeterminada en modo interactivo y deshabilitado en modo por lotes.
  • --echo-query-separator <string> — imprime este separador antes de la consulta mostrada por echo ya formateada (requiere --echo-formatted), lo que facilita distinguir la consulta escrita de su eco reformateado. Vacío de forma predeterminada (deshabilitado).
  • --highlight, --hilite <bool> — alterna el resaltado de sintaxis del prompt de comandos y de las consultas mostradas por echo. Está habilitado de forma predeterminada. El resaltado se aplica solo cuando se escribe en un terminal.
  • --hints <bool> — muestra sugerencias de autocompletado mientras escribe (texto "fantasma" en línea) para la sugerencia coincidente más adecuada cuando el cursor está al final de la entrada. Navegue por las sugerencias con Arriba/Abajo (o Ctrl-Arriba/Ctrl-Abajo); acepte la sugerencia en línea con Tab o Flecha derecha; Enter acepta una sugerencia solo después de que se haya seleccionado explícitamente una y, en caso contrario, ejecuta la consulta; Tab también abre la lista clásica de autocompletado. Requiere --highlight (las sugerencias necesitan color). Las sugerencias también necesitan el mecanismo de sugerencias, por lo que --disable_suggestion las desactiva; los comandos / del client son una lista estática y siguen mostrándose como sugerencias mientras --hints y --highlight estén activados. Tab completa los comandos / incluso cuando las sugerencias están desactivadas. Está habilitado de forma predeterminada.
  • --verbose — muestra más detalles sobre la ejecución de la consulta.
  • --logger.console — registrar en la consola.
  • --logger.log — nombre del archivo de registro.
  • --logger.level — nivel de registro.
  • --ignore-error — no detener el procesamiento si falla una consulta.
  • -c, --config-file — ruta al archivo de configuración en el mismo formato que el del servidor ClickHouse; de forma predeterminada, la configuración está vacía.
  • --no-system-tables — no adjuntar las tablas del sistema.
  • --help — referencia de argumentos para clickhouse-local.
  • -V, --version — imprime la información de la versión y sale.

Además, hay argumentos para cada variable de configuración de ClickHouse que suelen usarse en lugar de --config-file.

Comandos

Comando LS

Muestra todos los archivos del directorio de trabajo actual a los que puede acceder clickhouse-local.

Puede ejecutarlo en modo interactivo así:

Querysql
ClickHouse local version 26.3.1.1.

:) ls

SELECT _file AS file
FROM file('*', 'One')
ORDER BY file ASC
Responsetext
┌─file────────┐
│ file1.csv   │
│ file2.json  │
│ file3.xml   │
└─────────────┘

También puede ejecutarse como una consulta con el argumento -q:

./clickhouse-local -q ls
Responsetext
file1.csv
file2.json
file3.xml

Comando CLEAR

Limpia la pantalla del terminal (similar al comando clear en Linux o a Ctrl+L en muchos terminales). Es una acción del cliente: no se envía al motor SQL.

En clickhouse-local, el metacomando se reconoce en modo interactivo y con entrada mediante -q y --queries-file (por la misma vía del cliente que -q, en la misma línea que ls), por lo que un clear sin más no produce un error UNKNOWN_IDENTIFIER. En clickhouse-client --queries-file remoto no hay cambios: el contenido del archivo se ejecuta únicamente como SQL (sin metacomandos a nivel de texto).

En clickhouse-client, solo se reconoce en modo interactivo. Con -q o archivos de consultas, clear sigue interpretándose como SQL, de modo que la automatización conserva el comportamiento de error anterior en lugar de convertir errores tipográficos en un no-op silencioso.

Formas admitidas: clear, CLEAR, /clear (se ignora un ; final opcional). Si la salida estándar no es un terminal (por ejemplo, al redirigir la salida por una tubería), el metacomando se acepta cuando se reconoce, pero no emite secuencias de control.

Con clickhouse-local y -q:

./clickhouse-local -q clear

Ejemplos

Querybash
$ 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

El ejemplo anterior es el mismo que:

Querybash
$ 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

No es necesario usar stdin ni el argumento --file, y puedes abrir cualquier cantidad de archivos con la función de tabla file:

Querybash
$ 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

Ahora mostremos qué usuario de memoria corresponde a cada usuario de Unix:

Querybash
$ 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"
Responsetext
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 │
├──────────┼──────────┤
...

Inicio de listeners TCP y HTTP

clickhouse-local puede convertirse en un servidor ligero que acepta conexiones TCP (protocolo nativo) y HTTP. Esto resulta útil si desea permitir que otras herramientas o aplicaciones de ClickHouse accedan a las bases de datos y tablas de una instancia de clickhouse-local en ejecución. Tenga en cuenta que cada conexión entrante obtiene su propia sesión: las tablas temporales y la configuración a nivel de sesión de clickhouse-local en modo interactivo no son visibles para las conexiones externas.

Use SYSTEM START LISTEN para abrir un listener y SYSTEM STOP LISTEN para cerrarlo:

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;
    "

Las opciones --listen_host, --tcp_port y --http_port configuran la dirección de enlace y los puertos. Los puertos predeterminados son 9000 para TCP y 8123 para HTTP.

El listener HTTP responde a las solicitudes de comprobación previa de CORS con las mismas cabeceras permisivas que la configuración predeterminada de clickhouse-server, por lo que una aplicación web puede consultarlo directamente desde el navegador, incluida la interfaz web abierta desde una URL file://, cuyo origen es null. Para restringir esto, defina su propia sección http_options_response en un archivo de configuración pasado con --config-file; esta reemplaza por completo los valores predeterminados.

Contenido relacionado

Navigation