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 c311623a76
commit 690e68a542
33 changed files with 2720 additions and 0 deletions
@@ -0,0 +1,77 @@
+---
+name: bq_load_from_gcs
+kind: function
+lang: py
+domain: infra
+version: "1.0.0"
+purity: impure
+signature: "def bq_load_from_gcs(client: BQClient, uri: str | list[str], dataset_id: str, table_id: str, source_format: str = 'CSV', write_disposition: str = 'WRITE_APPEND', autodetect: bool = True, skip_leading_rows: int = 0) -> dict"
+description: "Carga datos desde uno o varios URIs de Google Cloud Storage a una tabla BigQuery configurando un LoadJob. Espera la finalizacion del job."
+tags: [bigquery, gcp, load, gcs, google-cloud, python, etl]
+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: uri
+    desc: "URI de GCS de origen (gs://bucket/file.csv) o lista de URIs; soporta wildcards como gs://bucket/prefix_*.csv"
+  - name: dataset_id
+    desc: "ID del dataset de destino en BigQuery"
+  - name: table_id
+    desc: "ID de la tabla de destino en BigQuery"
+  - name: source_format
+    desc: "formato del archivo fuente: CSV, NEWLINE_DELIMITED_JSON, AVRO, PARQUET, ORC"
+  - name: write_disposition
+    desc: "comportamiento si la tabla ya existe: WRITE_APPEND agrega, WRITE_TRUNCATE reemplaza, WRITE_EMPTY falla si hay datos"
+  - name: autodetect
+    desc: "si True, BigQuery infiere el schema automaticamente desde los datos"
+  - name: skip_leading_rows
+    desc: "numero de filas a ignorar al inicio del archivo (tipicamente 1 para saltar cabeceras CSV)"
+output: "dict con {job_id: ID del LoadJob, rows_loaded: filas cargadas, status: DONE o FAILED}"
+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_load_from_gcs
+
+client = bq_auth("my-project")
+
+# Cargar un archivo CSV con cabecera
+result = bq_load_from_gcs(
+    client,
+    "gs://my-bucket/data/users_2024.csv",
+    "my_dataset", "users",
+    skip_leading_rows=1,
+)
+print(f"Cargadas {result['rows_loaded']} filas — job: {result['job_id']}")
+
+# Cargar multiples archivos Parquet reemplazando la tabla
+result = bq_load_from_gcs(
+    client,
+    ["gs://my-bucket/export/part_001.parquet", "gs://my-bucket/export/part_002.parquet"],
+    "my_dataset", "events",
+    source_format="PARQUET",
+    write_disposition="WRITE_TRUNCATE",
+)
+```
+
+## Notas
+
+El job se ejecuta de forma asincrona en BigQuery; `job.result()` bloquea hasta completar.
+
+Los wildcards en el URI (`gs://bucket/prefix_*.csv`) son resueltos por GCS — BigQuery
+acepta la lista de archivos resultante como una sola carga atomica.
+
+`autodetect=True` es conveniente pero puede inferir tipos incorrectamente para columnas
+con valores nulos o mixtos. Para produccion, definir el schema explicitamente via
+`job_config.schema`.