fn_registry/python/functions/infra/pg_insert_rows.md

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

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	params	output	tested	tests	test_file_path	file_path
pg_insert_rows	function	py	infra	1.0.0	impure	def pg_insert_rows(dsn: str, table: str, rows: list[dict], add_snapshot_date: bool = True) -> int	Inserta filas (lista de dicts) en una tabla PostgreSQL de forma append-only via psycopg2.extras.execute_values. Deriva columnas de las claves del dict (union si difieren, rellena con None). Opcionalmente inyecta snapshot_date = date.today(). Insercion parametrizada (sin format de strings, evita inyeccion SQL). Commit y cierre de conexion. Retorna el numero de filas insertadas.	postgres market-intel infra				false	error_go_core	psycopg2	name desc dsn Cadena de conexion PostgreSQL en formato postgresql://user:pass@host:port/dbname. name desc table Nombre de la tabla destino (debe existir previamente). name desc rows Lista de dicts; cada dict es una fila, sus claves son nombres de columna. Si los esquemas difieren se usa la union de claves y se rellena con None. name desc add_snapshot_date Si True y una fila no trae snapshot_date, inyecta snapshot_date = date.today() antes de insertar. Default True.	Numero entero de filas insertadas (0 si rows esta vacio).	false			python/functions/infra/pg_insert_rows.py

Ejemplo

import sys, os
sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", "python", "functions"))
from infra.pg_insert_rows import pg_insert_rows

dsn = "postgresql://scraper:secret@localhost:5432/captacion"
rows = [
    {"name": "Cliente A", "city": "Madrid", "score": 87},
    {"name": "Cliente B", "city": "Sevilla"},  # sin score -> NULL
]
# snapshot_date = hoy se inyecta en cada fila automaticamente
n = pg_insert_rows(dsn, "leads_raw", rows)
print(f"insertadas {n} filas")  # insertadas 2 filas

Cuando usarla

Cuando escribes datos scrapeados a Postgres en lote append-only y quieres la columna snapshot_date poblada sin codigo extra. Usala antes de cualquier dashboard/consulta de market-intel sobre el dato bruto. Cada llamada acumula una nueva foto historica.

Gotchas

• La tabla debe existir antes de llamar — esta funcion NO crea schema (usa pg_apply_sql para eso).
• Es append-only: NO hace upsert ni deduplica. Llamadas repetidas duplican filas (por diseno, para historico).
• El esquema efectivo es la UNION de las claves de todas las filas; columnas ausentes en una fila se insertan como NULL. Si una clave no existe como columna en la tabla, Postgres lanza error y la transaccion entera hace rollback.
• add_snapshot_date=True solo rellena filas que NO traen ya snapshot_date; si tu dict ya la incluye, se respeta.
• Requiere psycopg2 instalado en el venv (import perezoso: el modulo se importa sin la dependencia, pero la llamada falla con RuntimeError claro si falta).
• Conexion nueva por llamada (sin pool). Para muchas inserciones pequenas en bucle, agrupa las filas en una sola llamada.