---
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, pendiente-usar]
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`.