---
name: bq_create_table
kind: function
lang: py
domain: infra
version: "1.0.0"
purity: impure
signature: "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"
description: "Crea una tabla en BigQuery con schema, particionamiento opcional y clustering. Usa client._client.create_table() del SDK oficial."
tags: [bigquery, gcp, table, create, 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 de BigQuery donde crear la tabla"
  - name: table_id
    desc: "nombre (ID) de la tabla a crear"
  - name: schema
    desc: "lista de dicts con definicion de columnas: [{name, type, mode, description}]. Tipos: STRING, INTEGER, FLOAT, BOOLEAN, DATE, TIMESTAMP, RECORD, etc."
  - name: partitioning
    desc: "dict opcional con tipo y campo de particion: {type: DAY|MONTH|YEAR|HOUR, field: nombre_col}. None = sin particion"
  - name: clustering
    desc: "lista de hasta 4 columnas para clustering (ordenacion fisica). None = sin clustering"
  - name: description
    desc: "descripcion legible de la tabla (vacio = sin descripcion)"
  - name: labels
    desc: "etiquetas clave-valor para la tabla, ej: {env: prod, team: data}"
output: "dict con metadata de la tabla creada: table_id, dataset_id, project, full_id, schema, num_rows, num_bytes, created, modified, type, partitioning, clustering, description, labels"
tested: false
tests: []
test_file_path: ""
file_path: "python/functions/bigquery/tables.py"
---

## Ejemplo

```python
from bigquery import bq_auth, bq_create_table

client = bq_auth("mi-proyecto")

tabla = bq_create_table(
    client,
    dataset_id="ventas_ds",
    table_id="transacciones",
    schema=[
        {"name": "id", "type": "INTEGER", "mode": "REQUIRED", "description": "ID unico"},
        {"name": "fecha", "type": "DATE", "mode": "NULLABLE", "description": "Fecha de la transaccion"},
        {"name": "monto", "type": "FLOAT", "mode": "NULLABLE", "description": "Monto en USD"},
        {"name": "pais", "type": "STRING", "mode": "NULLABLE", "description": "Codigo de pais"},
    ],
    partitioning={"type": "MONTH", "field": "fecha"},
    clustering=["pais"],
    description="Transacciones de ventas por mes",
    labels={"env": "prod", "team": "data"},
)
print(tabla["full_id"])
```

## Notas

El schema se convierte internamente de dicts a objetos `bigquery.SchemaField`. El particionamiento `TIME` soporta DAY, MONTH, YEAR y HOUR sobre columnas DATE/DATETIME/TIMESTAMP. Si `field` se omite en `partitioning`, BigQuery usa la pseudo-columna `_PARTITIONTIME`. El clustering requiere que las columnas existan en el schema y mejora rendimiento en filtros frecuentes.