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,60 @@
+---
+name: bq_insert_rows
+kind: function
+lang: py
+domain: infra
+version: "1.0.0"
+purity: impure
+signature: "def bq_insert_rows(client: BQClient, dataset_id: str, table_id: str, rows: list[dict]) -> dict"
+description: "Inserta filas en una tabla BigQuery usando streaming insert (insert_rows_json). Retorna el conteo de filas insertadas y errores por fila."
+tags: [bigquery, gcp, insert, streaming, 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: dataset_id
+    desc: "ID del dataset de destino en BigQuery"
+  - name: table_id
+    desc: "ID de la tabla de destino en BigQuery"
+  - name: rows
+    desc: "lista de dicts con los datos a insertar; las claves deben coincidir con las columnas de la tabla"
+output: "dict con {inserted: N filas insertadas sin error, errors: lista de errores por fila retornada por la API}"
+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_insert_rows
+
+client = bq_auth("my-project")
+
+result = bq_insert_rows(client, "my_dataset", "events", [
+    {"event_id": "abc1", "user_id": 42, "ts": "2024-01-01T12:00:00Z", "action": "click"},
+    {"event_id": "abc2", "user_id": 99, "ts": "2024-01-01T12:01:00Z", "action": "view"},
+])
+
+print(f"Insertadas: {result['inserted']}")
+if result["errors"]:
+    print("Errores:", result["errors"])
+```
+
+## Notas
+
+El streaming insert tiene disponibilidad casi inmediata pero no es transaccional.
+Las filas pueden aparecer duplicadas si el job se reintenta — BigQuery no garantiza
+exactamente-una-vez con insert_rows_json.
+
+`errors` es la lista retornada directamente por la API. Cada elemento es un dict con
+`index` (posicion de la fila fallida) y `errors` (lista de mensajes de error).
+
+Para cargas masivas o garantias ACID, preferir `bq_load_from_gcs` o `bq_load_from_file`.