fn_registry/python/functions/bigquery/bq_query.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, params, output, tested, tests, test_file_path, file_path

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	params	output	tested	tests	test_file_path	file_path
bq_query	function	py	infra	1.0.0	impure	def bq_query(client: BQClient, sql: str, params: list[dict] | None = None, dry_run: bool = False) -> dict	Ejecuta una query SQL en BigQuery con soporte para parametros tipados y modo dry-run para estimacion de costos.	bigquery gcp query sql google-cloud python				false	error_go_core	google-cloud-bigquery	name desc client cliente BQClient autenticado contra el proyecto GCP name desc sql query SQL a ejecutar; usar @nombre para referencias a parametros tipados name desc params lista de parametros tipados, cada uno con {name, type, value}; tipos: STRING, INT64, FLOAT64, BOOL, DATE, TIMESTAMP name desc dry_run si True, estima bytes procesados/facturados sin ejecutar la query	si dry_run=True: {total_bytes_processed, total_bytes_billed}; si False: {columns, rows, total_rows, bytes_processed, cache_hit}	false			python/functions/bigquery/queries.py

Ejemplo

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