chore: auto-commit (26 archivos)

- python/functions/bigquery/bq_auth.md
- python/functions/bigquery/bq_load_from_file.md
- python/functions/bigquery/bq_load_from_gcs.md
- python/functions/bigquery/client.py
- python/functions/bigquery/queries.py
- python/functions/datascience/__init__.py
- python/functions/datascience/decode_qr_image.py
- python/functions/datascience/load_bq_table_to_duckdb.md
- python/functions/datascience/load_bq_table_to_duckdb.py
- python/functions/pipelines/profile_bq_table.md
- ...

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

python/functions/pipelines/profile_bq_table.md

@@ -4,8 +4,8 @@ kind: pipeline
 lang: py
 domain: pipelines
 purity: impure
-version: "1.1.0"
-signature: "def profile_bq_table(table_fqn: str, sample_frac: float = None, max_rows: int = 0, pseudonymize_cols: list = None, run_models: bool = True, run_series: bool = False, run_llm: bool = False, project_id: str = \"\", report_dir: str = \"reports\", duckdb_path: str = \"\", keep_duckdb: bool = False) -> dict"
+version: "1.2.0"
+signature: "def profile_bq_table(table_fqn: str, sample_frac: float = None, max_rows: int = 0, pseudonymize_cols: list = None, run_models: bool = True, run_series: bool = False, run_llm: bool = False, project_id: str = \"\", report_dir: str = \"reports\", duckdb_path: str = \"\", keep_duckdb: bool = False, where_sql: str = \"\", select_sql: str = \"\") -> dict"
 description: "EDA one-shot de una tabla o vista de BigQuery: materializa el origen COMPLETO por defecto (todas las filas; muestreo opt-in con sample_frac; seudonimizacion PII opcional, LOPDGDD/RGPD) a un DuckDB local con load_bq_table_to_duckdb y lo perfila end-to-end con profile_table del grupo de capacidad eda, emitiendo el informe AutomaticEDA (PDF A5 movil + PPTX 16:9), Markdown y JSON sidecar. Es el adaptador BigQuery que faltaba en el grupo eda, resuelto por composicion (BigQuery -> DuckDB local -> profile_table) sin duplicar la logica de perfilado ni de render. Es el hazme un EDA de esta tabla BigQuery en una sola llamada, sobre el total de filas por defecto."
 tags: [eda, bigquery, launcher]
 uses_functions:
@@ -43,7 +43,11 @@ params:
     desc: "Ruta DuckDB a usar. Vacio = temporal autogestionado."
   - name: keep_duckdb
     desc: "Si True conserva el DuckDB materializado (para el notebook Jupyter). Default False."
-output: "dict dict-no-throw. En exito {status:'ok', table_fqn, load:{n_rows_source,n_rows_fetched,sampled,sample_frac,pseudonymized,table}, duckdb_path, report_md_path, report_json_path, aeda_pdf_path, aeda_pptx_path, aeda_manifest_path, profile}. En error {status:'error', error, stage}."
+  - name: where_sql
+    desc: "Clausula WHERE SQL (sin la palabra WHERE) aplicada al origen y a su COUNT. Pass-through a load_bq_table_to_duckdb; se combina con sample_frac via AND. Ej: `fecha <= CURRENT_DATE() AND venta_n IS NOT NULL`. Se interpola tal cual: no usar con input no confiable."
+  - name: select_sql
+    desc: "Expresiones del SELECT (sin la palabra SELECT); vacio (DEFAULT) = `*`. Pass-through a load_bq_table_to_duckdb. Util para castear tipos problematicos (p. ej. BIGNUMERIC->FLOAT64) antes de perfilar. Se interpola tal cual: no usar con input no confiable."
+output: "dict dict-no-throw. En exito {status:'ok', table_fqn, load:{n_rows_source,n_rows_fetched,sampled,sample_frac,pseudonymized,table,streamed, where_sql?, select_sql?}, duckdb_path, report_md_path, report_json_path, aeda_pdf_path, aeda_pptx_path, aeda_manifest_path, profile}. En error {status:'error', error, stage}. where_sql/select_sql aparecen en load solo si vienen informados."
 ---
 
 ## Ejemplo
@@ -66,6 +70,16 @@ r = profile_bq_table(
     sample_frac=0.05,
     pseudonymize_cols=["document_number", "full_name", "email", "phone", "postal_code", "salesforce_customer_id"],
 )
+
+# Filtrar el origen + castear una columna BIGNUMERIC antes de perfilar. where_sql y
+# select_sql se pasan al loader (que ingiere por batches Arrow, RAM acotada).
+r = profile_bq_table(
+    "autingo-159109.data.ventas_39M",
+    where_sql="fecha <= CURRENT_DATE() AND venta_n IS NOT NULL",
+    select_sql="fecha, idCentro, CAST(importe_bignumeric AS FLOAT64) AS importe",
+    run_models=True,
+)
+print(r["load"]["n_rows_fetched"], "filas, streamed=", r["load"].get("streamed"))
 ```
 
 ## Cuando usarla
@@ -83,12 +97,19 @@ en RAM, pasa `sample_frac` (muestreo opt-in).
 
 - Impura: requiere ADC de BigQuery configurado (Application Default Credentials)
   para que `load_bq_table_to_duckdb` autentique contra el proyecto.
-- FULL por defecto: `sample_frac=None` perfila TODAS las filas del origen. Una
-  vista de millones de filas se trae entera a RAM (varios GB posibles) antes de
-  materializar en DuckDB; el fetch usa el BigQuery Storage Read API (Arrow) cuando
-  esta disponible, mucho mas rapido que REST. Para acotar coste/memoria, pasa
-  `sample_frac` in (0,1) (muestreo opt-in) o `max_rows` (tope duro). Si por limite
-  de recursos no cabe el total, dilo explicito con el maximo que si se cargo.
+- FULL por defecto: `sample_frac=None` perfila TODAS las filas del origen. El
+  loader `load_bq_table_to_duckdb` (v1.2.0) ingiere por batches Arrow ->
+  DuckDB cuando `pyarrow` esta disponible, con la RAM acotada al tamano de un
+  batch (una tabla de decenas de millones de filas cabe sin cargarse entera); si
+  no, cae al camino DataFrame completo (todo en RAM, varios GB posibles). Para
+  acotar coste/memoria pasa `sample_frac` in (0,1), `max_rows` (tope duro) o
+  `where_sql` (filtra el origen). Si por limite de recursos no cabe el total,
+  dilo explicito con el maximo que si se cargo.
+- `where_sql` / `select_sql` (pass-through al loader) se interpolan TAL CUAL en la
+  query BigQuery: NO los construyas a partir de input no confiable (inyeccion SQL).
+  `select_sql` es la via para castear columnas BIGNUMERIC (Arrow decimal256, que
+  DuckDB no ingiere) a FLOAT64 antes de perfilar; si no las casteas, el loader
+  devuelve `{status:'error', stage:'stream_schema'|'stream_insert'}`.
 - Seudonimiza PII con `pseudonymize_cols` para cumplir LOPDGDD/RGPD ANTES de
   escribir a disco: nombres, DNI/NIE, email, telefono, direccion, IDs de cliente,
   etc. Se hashean preservando nulos y cardinalidad. Sin seudonimizar, la muestra
@@ -103,4 +124,5 @@ en RAM, pasa `sample_frac` (muestreo opt-in).
 
 ## Capability growth log
 
+- v1.2.0 (2026-07-02) — Añade `where_sql` y `select_sql` como pass-through al loader `load_bq_table_to_duckdb`: filtran/proyectan el origen antes de perfilar (`where_sql` tambien acota el COUNT del origen; `select_sql` permite castear BIGNUMERIC->FLOAT64). Ambos se reflejan en el bloque `load` del retorno (solo si vienen informados), junto con la nueva clave `streamed`. Hereda del loader v1.2.0 la ingesta streaming Arrow -> DuckDB por batches (RAM acotada) para tablas que no caben en RAM, con fallback DataFrame completo.
 - v1.1.0 (2026-07-01) — FULL pasa a ser el DEFAULT del pipeline: se sustituye `max_rows=300000, sample=True` por `sample_frac=None` (None = perfila todas las filas) + `max_rows=0` (tope duro opcional). El muestreo es opt-in explicito (`sample_frac`). Alinea con la preferencia estandar del usuario: los EDA se corren sobre el total salvo que se pida lo contrario. Hereda el fetch acelerado (Arrow/bqstorage) de `load_bq_table_to_duckdb` v1.1.0.