fn_registry/python/functions/infra/clickhouse_insert_rows.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, tested, tests, test_file_path, file_path, params, output

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	tested	tests	test_file_path	file_path	params	output
clickhouse_insert_rows	function	py	infra	1.0.0	impure	def clickhouse_insert_rows(base_url: str, table: str, rows: list[dict], *, user: str = 'default', password: str = '', database: str = 'analytics', timeout: float = 30.0) -> int	Inserta una lista de dicts en ClickHouse via HTTP (puerto 8123) usando el formato JSONEachRow. Retorna el numero de filas enviadas.	clickhouse analytics http insert ingest etl				false	error_go_core	json urllib.request urllib.parse urllib.error	false			python/functions/infra/clickhouse_insert_rows.py	name desc base_url URL base del servidor ClickHouse sin trailing slash. Ej: 'http://127.0.0.1:18123'. Para tunel SSH, apunta al puerto local reenviado. name desc table Nombre de la tabla destino, con o sin prefijo de base de datos. Ej: 'analytics.gnula_movies' o 'gnula_movies'. name desc rows Lista de dicts a insertar. Cada dict se serializa como una linea JSON. Las claves deben coincidir con columnas existentes; columnas ausentes usan DEFAULT. name desc user Usuario ClickHouse para autenticacion via header X-ClickHouse-User (default: 'default'). name desc password Contrasena ClickHouse para autenticacion via header X-ClickHouse-Key (default: cadena vacia). name desc database Base de datos ClickHouse enviada como parametro de query (default: 'analytics'). name desc timeout Timeout de socket en segundos (default: 30.0).	Entero con el numero de filas insertadas (len(rows)). Retorna 0 si rows esta vacio sin contactar el servidor.

Ejemplo

from infra import clickhouse_insert_rows

n = clickhouse_insert_rows(
    "http://127.0.0.1:18123",
    "analytics.gnula_movies",
    [
        {
            "snapshot_ts": "2026-05-30 14:00:00",
            "href": "/pelicula/avatar-el-camino-del-agua",
            "title": "Avatar: El camino del agua",
            "year": 2022,
            "flags": "es.png",
            "lang_es": 1,
            "status": "pending",
            "in_library": 0,
            "detected_at": "2026-05-30T14:00:00",
            "downloaded_at": "",
        }
    ],
    user="analytics",
    password="secret",
    database="analytics",
)
print(f"Inserted {n} rows")

Cuando usarla

Cuando un ETL empuja snapshots o eventos a ClickHouse via HTTP (puerto 8123), incluyendo a traves de un tunel SSH a un ClickHouse interno no expuesto publicamente. Alternativa ligera (solo stdlib) a clickhouse-driver o clickhouse-connect cuando no se quieren dependencias externas.

Gotchas

• base_url sin trailing slash: "http://127.0.0.1:18123", no "http://127.0.0.1:18123/".
• Fechas y datetimes deben pasarse como strings en formato que ClickHouse acepte ("YYYY-MM-DD HH:MM:SS") o como enteros epoch. El caller formatea; esta funcion no convierte tipos.
• Arrays van como listas JSON nativas Python: {"tags": ["drama", "sci-fi"]}.
• Columnas ausentes en un dict usan el valor DEFAULT de la tabla (JSONEachRow ignora claves faltantes). No falla.
• Para tunel SSH: ssh -L 18123:localhost:8123 user@host y usar base_url="http://127.0.0.1:18123".
• En caso de error HTTP, ValueError incluye el codigo y los primeros 500 caracteres del cuerpo — util para depurar errores de schema o SQL malformado.
• Lotes grandes: no hay batching interno. Si rows tiene miles de elementos, el body puede ser grande. Partir en chunks desde el caller si es necesario.