---
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`.