# Capability: bigquery

_(Descripcion del grupo — editar a mano)_

## Funciones

| ID | Firma | Que hace |
|---|---|---|
| `bq_auth_py_infra` | `def bq_auth(project_id: str = '', credentials_path: str = '') -> BQClient` | Autentica contra Google BigQuery con ADC o service account JSON. Retorna un BQClient listo para usar con todas las funciones CRUD. |
| `bq_cancel_job_py_infra` | `def bq_cancel_job(client: BQClient, job_id: str) -> dict` | Cancela un job en ejecucion. Retorna el estado tras la cancelacion. |
| `bq_copy_table_py_infra` | `def bq_copy_table(client: BQClient, source_dataset: str, source_table: str, dest_dataset: str, dest_table: str, write_disposition: str = 'WRITE_EMPTY') -> dict` | Copia una tabla BigQuery a otro dataset o tabla dentro del mismo proyecto usando copy_table del SDK. Espera la finalizacion del CopyJob. |
| `bq_create_dataset_py_infra` | `def bq_create_dataset(client: BQClient, dataset_id: str, location: str = 'US', description: str = '', labels: dict[str, str] \| None = None, default_table_expiration_ms: int = 0) -> dict` | Crea un dataset en Google BigQuery con ubicacion, descripcion y labels. Usa client._client.create_dataset() del SDK oficial. |
| `bq_create_routine_py_infra` | `def bq_create_routine(client: BQClient, dataset_id: str, routine_id: str, body: str, routine_type: str = 'SCALAR_FUNCTION', language: str = 'SQL', arguments: list[dict] \| None = None, return_type: str = '', description: str = '') -> dict` | Crea una routine (UDF scalar, tabla o stored procedure) en BigQuery. Soporta SQL, JavaScript y Python. |
| `bq_create_table_py_infra` | `def bq_create_table(client: BQClient, dataset_id: str, table_id: str, schema: list[dict], partitioning: dict \| None = None, clustering: list[str] \| None = None, description: str = '', labels: dict \| None = None) -> dict` | Crea una tabla en BigQuery con schema, particionamiento opcional y clustering. Usa client._client.create_table() del SDK oficial. |
| `bq_delete_dataset_py_infra` | `def bq_delete_dataset(client: BQClient, dataset_id: str, delete_contents: bool = False) -> None` | Elimina un dataset de Google BigQuery. IRREVERSIBLE. Usa client._client.delete_dataset() del SDK oficial. |
| `bq_delete_routine_py_infra` | `def bq_delete_routine(client: BQClient, dataset_id: str, routine_id: str) -> None` | Elimina una routine de un dataset. |
| `bq_delete_table_py_infra` | `def bq_delete_table(client: BQClient, dataset_id: str, table_id: str) -> None` | Elimina permanentemente una tabla de BigQuery. IRREVERSIBLE. Usa client._client.delete_table() del SDK oficial. |
| `bq_export_to_gcs_py_infra` | `def bq_export_to_gcs(client: BQClient, dataset_id: str, table_id: str, destination_uri: str, destination_format: str = 'CSV', compression: str = 'NONE') -> dict` | Exporta una tabla BigQuery a Google Cloud Storage usando extract_table del SDK. Soporta CSV, JSON, Avro y Parquet con compresion opcional. |
| `bq_get_dataset_py_infra` | `def bq_get_dataset(client: BQClient, dataset_id: str) -> dict` | Obtiene los detalles completos de un dataset de Google BigQuery. Usa client._client.get_dataset() del SDK oficial. |
| `bq_get_job_py_infra` | `def bq_get_job(client: BQClient, job_id: str) -> dict` | Obtiene detalles completos de un job por su ID incluyendo estado, bytes procesados y errores. Incluye campos adicionales respecto a bq_list_jobs: destination_table, query y lista de errores. |
| `bq_get_table_py_infra` | `def bq_get_table(client: BQClient, dataset_id: str, table_id: str) -> dict` | Obtiene los metadatos completos de una tabla BigQuery incluyendo schema, estadisticas y configuracion. Usa client._client.get_table() del SDK oficial. |
| `bq_insert_rows_py_infra` | `def bq_insert_rows(client: BQClient, dataset_id: str, table_id: str, rows: list[dict]) -> dict` | Inserta filas en una tabla BigQuery usando streaming insert (insert_rows_json). Retorna el conteo de filas insertadas y errores por fila. |
| `bq_list_datasets_py_infra` | `def bq_list_datasets(client: BQClient) -> list[dict]` | Lista todos los datasets del proyecto de Google BigQuery. Usa client._client.list_datasets() del SDK oficial. |
| `bq_list_jobs_py_infra` | `def bq_list_jobs(client: BQClient, state_filter: str = '', max_results: int = 50, all_users: bool = False) -> list[dict]` | Lista jobs del proyecto con filtro por estado (running, pending, done). Retorna una lista de dicts planos con metadatos de cada job. |
| `bq_list_routines_py_infra` | `def bq_list_routines(client: BQClient, dataset_id: str) -> list[dict]` | Lista routines de un dataset incluyendo tipo y lenguaje. |
| `bq_list_tables_py_infra` | `def bq_list_tables(client: BQClient, dataset_id: str) -> list[dict]` | Lista todas las tablas (y vistas) de un dataset BigQuery con informacion resumida. Usa client._client.list_tables() del SDK oficial. |
| `bq_load_from_file_py_infra` | `def bq_load_from_file(client: BQClient, file_path: 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` | Carga datos desde un archivo local a una tabla BigQuery usando load_table_from_file del SDK. Equivalente a bq_load_from_gcs pero para disco local. |
| `bq_load_from_gcs_py_infra` | `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` | Carga datos desde uno o varios URIs de Google Cloud Storage a una tabla BigQuery configurando un LoadJob. Espera la finalizacion del job. |
| `bq_preview_rows_py_infra` | `def bq_preview_rows(client: BQClient, dataset_id: str, table_id: str, max_results: int = 10) -> dict` | Obtiene una muestra de filas de una tabla BigQuery sin ejecutar query SQL, sin coste de procesamiento. Usa client._client.list_rows() del SDK oficial. |
| `bq_query_py_infra` | `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. |
| `bq_update_dataset_py_infra` | `def bq_update_dataset(client: BQClient, dataset_id: str, description: str \| None = None, labels: dict[str, str] \| None = None, default_table_expiration_ms: int \| None = None) -> dict` | Actualiza campos de un dataset de Google BigQuery. Solo modifica los campos pasados explicitamente (no-None). Usa client._client.update_dataset() del SDK oficial. |
| `bq_update_table_py_infra` | `def bq_update_table(client: BQClient, dataset_id: str, table_id: str, schema: list[dict] \| None = None, description: str \| None = None, labels: dict \| None = None) -> dict` | Actualiza metadatos de una tabla BigQuery: schema (solo adicion de columnas), descripcion y etiquetas. Usa client._client.update_table() del SDK oficial. |
| `fetch_data_frame_go_datascience` | `func FetchDataFrame(dsn, query string) ([]map[string]any, error)` | Ejecuta una consulta SQL contra un DSN y retorna los resultados como slice de mapas columna-valor. |
| `metabase_smartscalar_kpi_sql_py_infra` | `def metabase_smartscalar_kpi_sql(*, act_expr: str, n1_expr: str, body_sql: str, date_expr: str = 'MIN(fecha)') -> str` | Envuelve agregaciones actual+n-1 en el patron de 2 filas (periodo, valor) que el display smartscalar de Metabase v0.59 requiere para mostrar comparacion vs ano anterior sin pedir breakout temporal. Genera SQL nativo BigQuery con UNION ALL d_min/d_min-52w. |


## Ejemplo canonico

_(Anadir 1-2 bloques de codigo end-to-end)_

## Fronteras

_(Que NO cubre este grupo)_