---
name: bq_copy_table
kind: function
lang: py
domain: infra
version: "1.0.0"
purity: impure
signature: "def bq_copy_table(client: BQClient, source_dataset: str, source_table: str, dest_dataset: str, dest_table: str, write_disposition: str = 'WRITE_EMPTY') -> dict"
description: "Copia una tabla BigQuery a otro dataset o tabla dentro del mismo proyecto usando copy_table del SDK. Espera la finalizacion del CopyJob."
tags: [bigquery, gcp, copy, table, google-cloud, python, pendiente-usar]
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: source_dataset
    desc: "ID del dataset de origen en BigQuery"
  - name: source_table
    desc: "ID de la tabla de origen en BigQuery"
  - name: dest_dataset
    desc: "ID del dataset de destino en BigQuery (puede ser el mismo que el origen)"
  - name: dest_table
    desc: "ID de la tabla de destino; si no existe, BigQuery la crea automaticamente"
  - name: write_disposition
    desc: "comportamiento si la tabla destino ya existe: WRITE_EMPTY falla, WRITE_APPEND agrega, WRITE_TRUNCATE sobreescribe"
output: "dict con {job_id: ID del CopyJob, status: DONE o FAILED}"
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_copy_table

client = bq_auth("my-project")

# Copia de produccion a staging (falla si ya existe)
result = bq_copy_table(
    client,
    "production", "users",
    "staging",   "users_backup",
)
print(f"Copia completada: {result['status']} — job: {result['job_id']}")

# Copia sobreescribiendo destino
result = bq_copy_table(
    client,
    "raw", "events_2024",
    "processed", "events_latest",
    write_disposition="WRITE_TRUNCATE",
)
```

## Notas

`copy_table` solo funciona dentro del mismo proyecto GCP. Para copiar entre proyectos,
usar `bq_export_to_gcs` + `bq_load_from_gcs`.

Si la tabla destino no existe, BigQuery la crea con el schema de la tabla origen
independientemente del `write_disposition`.

El CopyJob es asincrono; `job.result()` bloquea hasta completar. La copia no mueve
datos fisicamente — BigQuery usa referencias de bloques internamente hasta que se
modifica la copia.
