feat: add BigQuery Python functions and BQClient type

Funciones CRUD completas para BigQuery: auth, datasets, tables, queries, jobs, routines, load/export. Tipo BQClient como wrapper del SDK oficial.
2026-04-07 18:45:02 +02:00
parent c9f28aa603
commit 9f5e6791db
33 changed files with 2720 additions and 0 deletions
@@ -0,0 +1,69 @@
+---
+name: bq_query
+kind: function
+lang: py
+domain: infra
+version: "1.0.0"
+purity: impure
+signature: "def bq_query(client: BQClient, sql: str, params: list[dict] | None = None, dry_run: bool = False) -> dict"
+description: "Ejecuta una query SQL en BigQuery con soporte para parametros tipados y modo dry-run para estimacion de costos."
+tags: [bigquery, gcp, query, sql, google-cloud, python]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: [google-cloud-bigquery]
+params:
+  - name: client
+    desc: "cliente BQClient autenticado contra el proyecto GCP"
+  - name: sql
+    desc: "query SQL a ejecutar; usar @nombre para referencias a parametros tipados"
+  - name: params
+    desc: "lista de parametros tipados, cada uno con {name, type, value}; tipos: STRING, INT64, FLOAT64, BOOL, DATE, TIMESTAMP"
+  - name: dry_run
+    desc: "si True, estima bytes procesados/facturados sin ejecutar la query"
+output: "si dry_run=True: {total_bytes_processed, total_bytes_billed}; si False: {columns, rows, total_rows, bytes_processed, cache_hit}"
+tested: false
+tests: []
+test_file_path: ""
+file_path: "python/functions/bigquery/queries.py"
+---
+
+## Ejemplo
+
+```python
+from bigquery.client import bq_auth
+from bigquery.queries import bq_query
+
+client = bq_auth("my-project")
+
+# Query simple
+result = bq_query(client, "SELECT COUNT(*) as n FROM `my_project.dataset.table`")
+print(result["columns"])  # ["n"]
+print(result["rows"])     # [[12345]]
+
+# Con parametros
+result = bq_query(
+    client,
+    "SELECT * FROM `dataset.users` WHERE status = @s AND age > @a",
+    params=[
+        {"name": "s", "type": "STRING", "value": "active"},
+        {"name": "a", "type": "INT64",  "value": 18},
+    ],
+)
+
+# Dry-run para estimar costo
+est = bq_query(client, "SELECT * FROM `dataset.big_table`", dry_run=True)
+print(f"Procesaria {est['total_bytes_processed'] / 1e9:.2f} GB")
+```
+
+## Notas
+
+Usa `bigquery.ScalarQueryParameter` para parametros — solo soporta escalares. Para arrays
+usar `bigquery.ArrayQueryParameter` directamente si se necesita.
+
+En dry_run=True el job se crea pero no se ejecuta; `job.result()` no se llama. BigQuery
+retorna la estimacion de bytes sin cargo.
+
+`cache_hit=True` indica que el resultado provino de la cache de BigQuery (sin costo).