clickhouse-local - ClickHouse Documentation

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

El binario que acabas de descargar puede ejecutar todo tipo de herramientas y utilidades de ClickHouse. Si quieres ejecutar ClickHouse como servidor de bases de datos, consulta la Inicio rápido.

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')"

Puede usar globs en el nombre del archivo (consulte sustituciones de globs).Ejemplos:

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

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:

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    ██████████████▋

Cuando esté listo para insertar sus archivos en ClickHouse, inicie un servidor de ClickHouse e inserte los resultados de las funciones de tabla file y s3 en una tabla MergeTree. Consulte Inicio rápido para obtener más información.

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

clickhouse-local también es compatible con Windows a través de WSL2.

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 — imprime la consulta antes de ejecutarla.
--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í:

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   │
└─────────────┘

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

./clickhouse-local -q ls

Response

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

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

El ejemplo anterior es el mismo que:

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

No es necesario usar stdin ni el argumento --file, y puedes abrir cualquier cantidad de archivos con la función de tabla 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

Ahora mostremos qué usuario de memoria corresponde a cada usuario de 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 │
├──────────┼──────────┤
...

​Cuándo usar clickhouse-local vs. ClickHouse

​Descargar clickhouse-local

​Consultar datos de un archivo con SQL

​Consultar datos en un archivo Parquet en AWS S3

​Conversión entre formatos

​Uso

​Comandos

​Comando LS

​Comando CLEAR

​Ejemplos

​Contenido relacionado

Cuándo usar clickhouse-local vs. ClickHouse

Descargar clickhouse-local

Consultar datos de un archivo con SQL

Consultar datos en un archivo Parquet en AWS S3

Conversión entre formatos

Uso

Comandos

Comando LS

Comando CLEAR

Ejemplos

Contenido relacionado