---
name: bq_update_table
kind: function
lang: py
domain: infra
version: "1.0.0"
purity: impure
signature: "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"
description: "Actualiza metadatos de una tabla BigQuery: schema (solo adicion de columnas), descripcion y etiquetas. Usa client._client.update_table() del SDK oficial."
tags: [bigquery, gcp, table, update, 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 autenticado BQClient obtenido con bq_auth"
  - name: dataset_id
    desc: "ID del dataset que contiene la tabla"
  - name: table_id
    desc: "nombre (ID) de la tabla a actualizar"
  - name: schema
    desc: "schema completo nuevo (columnas existentes + nuevas al final). BigQuery SOLO permite agregar columnas, no eliminar ni renombrar. None = no modificar"
  - name: description
    desc: "nueva descripcion de la tabla. None = no modificar"
  - name: labels
    desc: "nuevas etiquetas clave-valor (reemplaza las existentes). None = no modificar"
output: "dict con la metadata actualizada de la tabla (misma estructura que bq_get_table)"
tested: false
tests: []
test_file_path: ""
file_path: "python/functions/bigquery/tables.py"
---

## Ejemplo

```python
from bigquery import bq_auth, bq_update_table

client = bq_auth("mi-proyecto")

# Actualizar descripcion y etiquetas
tabla = bq_update_table(
    client, "ventas_ds", "transacciones",
    description="Transacciones de ventas — actualizado",
    labels={"env": "prod", "team": "data", "version": "2"},
)

# Agregar columna nueva al schema existente
tabla = bq_update_table(
    client, "ventas_ds", "transacciones",
    schema=[
        {"name": "id", "type": "INTEGER", "mode": "REQUIRED"},
        {"name": "fecha", "type": "DATE", "mode": "NULLABLE"},
        {"name": "monto", "type": "FLOAT", "mode": "NULLABLE"},
        {"name": "nueva_col", "type": "STRING", "mode": "NULLABLE"},  # nueva
    ],
)
```

## Notas

BigQuery tiene restricciones estrictas sobre modificacion de schema: se pueden agregar columnas NULLABLE o REPEATED al final, pero NO se pueden eliminar columnas, renombrar columnas ni cambiar el tipo de una columna existente. Si se necesita ese tipo de cambio, la alternativa es crear una tabla nueva con `CREATE TABLE AS SELECT`. Los campos `None` no generan actualizacion — solo se envian al API los campos que cambian.