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