Conecta dlt con ClickHouse - ClickHouse Documentation

dlt es una biblioteca de código abierto que puedes añadir a tus scripts de Python para cargar datos desde diversas fuentes de datos, a menudo desordenadas, en conjuntos de datos bien estructurados y actualizados en tiempo real.

Instalar dlt con ClickHouse

Para instalar la biblioteca `dlt` con las dependencias de ClickHouse:

pip install "dlt[clickhouse]"

Guía de configuración

Inicializa el proyecto dlt

Empieza inicializando un nuevo proyecto dlt de la siguiente manera:

dlt init chess clickhouse

Este comando inicializará tu pipeline con chess como origen y ClickHouse como destino.

El comando anterior genera varios archivos y directorios, incluidos .dlt/secrets.toml y un archivo de requisitos para ClickHouse. Puedes instalar las dependencias necesarias especificadas en el archivo de requisitos ejecutando lo siguiente:

pip install -r requirements.txt

o con pip install dlt[clickhouse], que instala la biblioteca dlt y las dependencias necesarias para trabajar con ClickHouse como destino.

Configura la base de datos de ClickHouse

Para cargar datos en ClickHouse, necesitas crear una base de datos en ClickHouse. Aquí tienes un resumen general de lo que debes hacer:

Puedes usar una base de datos de ClickHouse existente o crear una nueva.
Para crear una base de datos nueva, conéctate a tu servidor ClickHouse con la herramienta de línea de comandos clickhouse-client o con el cliente SQL que prefieras.
Ejecuta los siguientes comandos SQL para crear una nueva base de datos, un usuario y conceder los permisos necesarios:

CREATE DATABASE IF NOT EXISTS dlt;
CREATE USER dlt IDENTIFIED WITH sha256_password BY 'Dlt*12345789234567';
GRANT CREATE, ALTER, SELECT, DELETE, DROP, TRUNCATE, OPTIMIZE, SHOW, INSERT, dictGet ON dlt.* TO dlt;
GRANT SELECT ON INFORMATION_SCHEMA.COLUMNS TO dlt;
GRANT CREATE TEMPORARY TABLE, S3 ON *.* TO dlt;

Agrega las credenciales

A continuación, configura las credenciales de ClickHouse en el archivo .dlt/secrets.toml como se muestra a continuación:

[destination.clickhouse.credentials]
database = "dlt"                         # Nombre de la base de datos que creaste
username = "dlt"                         # Nombre de usuario de ClickHouse; el predeterminado suele ser "default"
password = "Dlt*12345789234567"          # Contraseña de ClickHouse, si corresponde
host = "localhost"                       # Host del servidor ClickHouse
port = 9000                              # Puerto de ClickHouse; el valor predeterminado es 9000
http_port = 8443                         # Puerto HTTP para conectarte a la interfaz HTTP del servidor ClickHouse. El valor predeterminado es 8443.
secure = 1                               # Establécelo en 1 si usas HTTPS; de lo contrario, 0.

[destination.clickhouse]
dataset_table_separator = "___"          # Separador para los nombres de tabla del conjunto de datos.

HTTP_PORTEl parámetro http_port especifica el número de puerto que se debe usar al conectarse a la interfaz HTTP del servidor ClickHouse. Esto es diferente del puerto predeterminado 9000, que se usa para el protocolo TCP nativo.Debes establecer http_port si no estás usando staging externo (es decir, no configuras el parámetro staging en tu pipeline). Esto se debe a que el staging integrado del almacenamiento local de ClickHouse usa la biblioteca clickhouse-connect, que se comunica con ClickHouse a través de HTTP.Asegúrate de que tu servidor ClickHouse esté configurado para aceptar conexiones HTTP en el puerto especificado por http_port. Por ejemplo, si estableces http_port = 8443, entonces ClickHouse debería estar escuchando solicitudes HTTP en el puerto 8443. Si estás usando staging externo, puedes omitir el parámetro http_port, ya que clickhouse-connect no se usará en este caso.

Puedes pasar una cadena de conexión a la base de datos similar a la que usa la biblioteca clickhouse-driver. Las credenciales anteriores se verán así:

# mantenlo en la parte superior de tu archivo toml, antes de que comience cualquier sección.
destination.clickhouse.credentials="clickhouse://dlt:Dlt*12345789234567@localhost:9000/dlt?secure=1"

Disposición de escritura

Se admiten todas las disposiciones de escritura . Las disposiciones de escritura en la biblioteca dlt definen cómo deben escribirse los datos en el destino. Hay tres tipos de disposiciones de escritura: Replace: Esta disposición reemplaza los datos en el destino con los datos del recurso. Elimina todas las clases y objetos, y vuelve a crear el esquema antes de cargar los datos. Puede obtener más información aquí. Merge: Esta disposición combina los datos del recurso con los datos del destino. Para la disposición merge, deberá especificar una primary_key para el recurso. Puede obtener más información aquí. Append: Esta es la disposición predeterminada. Añade los datos a los datos existentes en el destino, ignorando el campo primary_key.

Carga de datos

Los datos se cargan en ClickHouse con el método más eficiente según su origen:

Para los archivos locales, se utiliza la biblioteca clickhouse-connect para cargarlos directamente en tablas de ClickHouse mediante el comando INSERT.
Para los archivos en almacenamiento remoto como S3, Google Cloud Storage o Azure Blob Storage, se utilizan funciones de tabla de ClickHouse, como s3, gcs y azureBlobStorage, para leer los archivos e insertar los datos en las tablas.

Conjuntos de datos

ClickHouse no admite varios conjuntos de datos en una misma base de datos, mientras que dlt depende de ellos por varios motivos. Para que ClickHouse funcione con dlt, los nombres de las tablas generadas por dlt en tu base de datos ClickHouse llevarán el prefijo del nombre del conjunto de datos, separado por el dataset_table_separator configurable. Además, se creará una tabla centinela especial que no contendrá ningún dato, lo que permitirá a dlt reconocer qué conjuntos de datos virtuales ya existen en un destino de ClickHouse.

Formatos de archivo compatibles

jsonl es el formato preferido tanto para la carga directa como para el staging.
parquet es compatible tanto con la carga directa como con el staging.

El destino clickhouse presenta algunas diferencias específicas con respecto a los destinos SQL predeterminados:

ClickHouse tiene un tipo de dato object experimental, pero hemos comprobado que puede ser algo impredecible, por lo que el destino ClickHouse de dlt cargará el tipo de dato complejo en una columna de texto. Si necesita esta funcionalidad, póngase en contacto con nuestra comunidad de Slack y estudiaremos incorporarla.
ClickHouse no admite el tipo de dato time. time se cargará en una columna text.
ClickHouse no admite el tipo de dato binary. En su lugar, los datos binarios se cargarán en una columna text. Al cargar desde jsonl, los datos binarios serán una cadena en base64, y al cargar desde parquet, el objeto binary se convertirá en text.
ClickHouse permite agregar columnas no nulas a una tabla con datos.
ClickHouse puede producir errores de redondeo en determinadas condiciones al usar el tipo de dato float o double. Si no puede permitirse errores de redondeo, asegúrese de usar el tipo de dato decimal. Por ejemplo, al cargar el valor 12.7001 en una columna double con el formato de archivo del cargador establecido en jsonl, se producirá de forma predecible un error de redondeo.

Indicadores de columna compatibles

ClickHouse admite los siguientes indicadores de columna:

primary_key - marca la columna como parte de la clave primaria. Varias columnas pueden tener este indicador para crear una clave primaria compuesta.

Motor de tabla

De forma predeterminada, las tablas se crean con el motor de tabla ReplicatedMergeTree en ClickHouse. Puede especificar un motor de tabla alternativo mediante table_engine_type con el adaptador ClickHouse:

from dlt.destinations.adapters import clickhouse_adapter

@dlt.resource()
def my_resource():
  ...

clickhouse_adapter(my_resource, table_engine_type="merge_tree")

Los valores compatibles son:

merge_tree - crea tablas con el motor MergeTree
replicated_merge_tree (predeterminado) - crea tablas con el motor ReplicatedMergeTree

Compatibilidad con staging

ClickHouse admite Amazon S3, Google Cloud Storage y Azure Blob Storage como destinos de staging para archivos. dlt subirá archivos Parquet o jsonl a la ubicación de staging y usará las funciones de tabla de ClickHouse para cargar los datos directamente desde los archivos en staging. Consulta la documentación del sistema de archivos para obtener información sobre cómo configurar las credenciales de los destinos de staging:

Para ejecutar un pipeline con staging habilitado:

pipeline = dlt.pipeline(
  pipeline_name='chess_pipeline',
  destination='clickhouse',
  staging='filesystem',  # añade esto para activar el staging
  dataset_name='chess_data'
)

Uso de Google Cloud Storage como área de staging

dlt admite el uso de Google Cloud Storage (GCS) como área de staging al cargar datos en ClickHouse. Esto se gestiona automáticamente mediante la función de tabla GCS de ClickHouse, que dlt utiliza internamente. La función de tabla GCS de ClickHouse solo admite la autenticación mediante claves Hash-based Message Authentication Code (HMAC). Para habilitar esto, GCS ofrece un modo de compatibilidad con S3 que emula la API de Amazon S3. ClickHouse aprovecha esto para permitir el acceso a buckets de GCS a través de su integración con S3. Para configurar el staging de GCS con autenticación HMAC en dlt:

Cree claves HMAC para su cuenta de servicio de GCS siguiendo la guía de Google Cloud.
Configure las claves HMAC, así como client_email, project_id y private_key de su cuenta de servicio en la configuración del destino ClickHouse de su proyecto de dlt en config.toml:

[destination.filesystem]
bucket_url = "gs://dlt-ci"

[destination.filesystem.credentials]
project_id = "a-cool-project"
client_email = "my-service-account@a-cool-project.iam.gserviceaccount.com"
private_key = "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkaslkdjflasjnkdcopauihj...wEiEx7y+mx\nNffxQBqVVej2n/D93xY99pM=\n-----END PRIVATE KEY-----\n"

[destination.clickhouse.credentials]
database = "dlt"
username = "dlt"
password = "Dlt*12345789234567"
host = "localhost"
port = 9440
secure = 1
gcp_access_key_id = "JFJ$$*f2058024835jFffsadf"
gcp_secret_access_key = "DFJdwslf2hf57)%$02jaflsedjfasoi"

Nota: Además de las claves HMAC bashgcp_access_key_id y gcp_secret_access_key), ahora también debes proporcionar client_email, project_id y private_key de tu cuenta de servicio en [destination.filesystem.credentials]. Esto se debe a que el soporte de staging de GCS está implementado actualmente como una solución temporal y aún no está optimizado. dlt pasará estas credenciales a ClickHouse, que se encargará de la autenticación y del acceso a GCS. Se está trabajando activamente para simplificar y mejorar en el futuro la configuración del staging de GCS para el destino ClickHouse de dlt. El soporte adecuado para el staging de GCS se está siguiendo en estos issues de GitHub:

Hacer que el destino filesystem funcione con gcs en modo de compatibilidad con s3
Soporte para el área de staging de Google Cloud Storage

Soporte para dbt

La integración con dbt suele estar disponible a través de dbt-clickhouse.

Sincronización del estado de `dlt`

Este destino es totalmente compatible con la sincronización del estado de dlt.

​Instalar dlt con ClickHouse

​Para instalar la biblioteca dlt con las dependencias de ClickHouse:

​Guía de configuración

​Disposición de escritura

​Carga de datos

​Conjuntos de datos

​Formatos de archivo compatibles

​Indicadores de columna compatibles

​Motor de tabla

​Compatibilidad con staging

​Uso de Google Cloud Storage como área de staging

​Soporte para dbt

​Sincronización del estado de dlt

Instalar dlt con ClickHouse

Para instalar la biblioteca `dlt` con las dependencias de ClickHouse:

Guía de configuración

Disposición de escritura

Carga de datos

Conjuntos de datos

Formatos de archivo compatibles

Indicadores de columna compatibles

Motor de tabla

Compatibilidad con staging

Uso de Google Cloud Storage como área de staging

Soporte para dbt

Sincronización del estado de `dlt`