Modifica esquemas de tabla

En este documento, se describe cómo modificar las definiciones de esquema para tablas de BigQuery existentes. BigQuery es compatible con las modificaciones de esquema siguientes de forma nativa:

Agregar columnas a una definición de esquema
Disminuir la rigurosidad del modo de una columna de REQUIRED a NULLABLE

Es válido crear una tabla sin definir un esquema inicial y agregar una definición de esquema a la tabla más adelante.

Todas las demás modificaciones del esquema no son compatibles y requieren soluciones alternativas manuales, que incluyen las opciones siguientes:

Cambiar el nombre de una columna
Cambiar el tipo de datos de una columna
Cambiar el modo de una columna (además de disminuir la rigurosidad de las columnas REQUIRED a NULLABLE)
Borra una columna

Para obtener más información sobre cambios de esquema no compatibles que requieren soluciones alternativas, consulta Cambia esquemas de tablas de forma manual.

Agrega columnas a la definición de esquema de una tabla

Puedes agregar columnas a la definición de esquema de una tabla existente de las formas siguientes:

De forma manual (crea una columna vacía).
Cuando usas un trabajo o consulta de carga para reemplazar una tabla
Cuando adjuntas datos a una tabla con un trabajo de carga o consulta

Toda columna que agregas se debe adherir a las funciones de BigQuery para los nombres de consultas. Para obtener más información sobre cómo crear componentes de esquema, consulta Especifica un esquema.

Agrega una columna vacía de forma manual

Puedes agregar una columna vacía a una tabla existente con uno de estos métodos:

Usa Cloud Console.
Usar el comando bq update de la herramienta de línea de comandos de bq
Llamar al método de la API tables.patch
Mediante la ejecución de la declaración de lenguaje de definición de datos (DDL) ALTER TABLE ADD COLUMN
Usa bibliotecas cliente.

Si agregas columnas nuevas a un esquema de tabla existente, las columnas deben ser NULLABLE o REPEATED. No puedes agregar una columna REQUIRED a un esquema de tabla existente. Si intentas agregar una columna REQUIRED a un esquema de tabla existente en la API o la herramienta de línea de comandos de bq, se mostrará el siguiente error: BigQuery error in update operation: Provided Schema does not match Table project_id:dataset.table. Cannot add required columns to an existing schema. Las columnas REQUIRED solo pueden agregarse cuando creas una tabla mientras cargas datos, o cuando creas una tabla vacía con una definición de esquema.

Después de agregar una columna nueva a la definición de esquema de tu tabla, puedes cargar datos en la columna nueva si usas estos elementos:

Declaración DML para realizar una actualización de forma masiva en cada fila
Trabajo de carga que reemplaza la tabla.
Resultado de la consulta que reemplace la tabla.

Para agregar columnas vacías a la definición de esquema de una tabla, sigue estos pasos:

Console

En el panel Explorador, expande el proyecto y conjunto de datos y, luego, selecciona la tabla.

Nota: La experiencia predeterminada es la vista previa de Cloud Console. Si hiciste clic en Hide preview features para ir a Cloud Console con disponibilidad general, realiza el siguiente paso: en la sección Recursos del panel de navegación, expande tu proyecto y, luego, haz clic en el nombre de la tabla.
En el panel de detalles, haga clic en la pestaña Esquema.
Haz clic en Editar esquema. Es posible que deba desplazarse para ver este botón.
En la página Esquema actual, en Campos nuevos, haz clic en Agregar campo.
- Para Nombre, escribe el nombre de la columna.
- Para Tipo, elige el tipo de datos.
- Para Modo, elige NULLABLE o REPEATED.
Cuando termines de agregar columnas, haz clic en Guardar.

SQL

Para agregar una columna nueva a una tabla existente con la declaración DDL ALTER TABLE ADD COLUMN, sigue estos pasos:

En Cloud Console, haz clic en Redactar consulta nueva.

Escribe tu declaración DDL en el campo Editor de consultas.

    ALTER TABLE mydataset.mytable
      ADD COLUMN A STRING

Haga clic en Ejecutar.

Para obtener más información sobre el uso de SQL estándar, consulta Cambiar los dialectos de SQL.

bq

Ejecuta el comando bq update y proporciona un archivo de esquema JSON. Si la tabla que actualizas está en un proyecto que no es tu proyecto predeterminado, agrega el ID del proyecto al nombre del conjunto de datos en el siguiente formato: project_id:dataset.

bq update project_id:dataset.table schema

En el ejemplo anterior, se ilustra lo siguiente:

project_id es el ID del proyecto.
dataset es el nombre del conjunto de datos que contiene la tabla que deseas actualizar.
table es el nombre de la tabla que deseas actualizar.
schema es la ruta al archivo de esquema JSON en tu máquina local.

Cuando especificas el esquema con la herramienta de línea de comandos de bq, no puedes incluir un tipo RECORD (STRUCT) ni una descripción de columna, y tampoco puedes especificar el modo de la columna. Todos los modos están establecidos como NULLABLE de forma predeterminada.

Si intentas agregar columnas con una definición de esquema intercalada, debes suministrar la definición de esquema completa que incluye las columnas nuevas. Debido a que no puedes especificar los modos de columnas con una definición de esquema intercalada, la actualización intentará cambiar cualquier columna REQUIRED existente a NULLABLE. Esto genera el error siguiente: BigQuery error in update operation: Provided Schema does not match Table project_id:dataset.table. Field field has changed mode from REPEATED to NULLABLE.

El método recomendado para agregar columnas a una tabla existente mediante la herramienta de línea de comandos de bq es suministrar un archivo de esquema JSON.

Para agregar columnas vacías al esquema de una tabla con un archivo de esquema JSON, sigue estos pasos:

Primero, ejecuta el comando bq show con la marca --schema y escribe el esquema de tabla existente en un archivo. Si la tabla que actualizas está en un proyecto que no es tu proyecto predeterminado, agrega el ID del proyecto al nombre del conjunto de datos en el siguiente formato: project_id:dataset.
```
bq show \
--schema \
--format=prettyjson \
project_id:dataset.table > schema_file
```
En el ejemplo anterior, se ilustra lo siguiente:
- project_id es el ID del proyecto.
- dataset es el nombre del conjunto de datos que contiene la tabla que deseas actualizar.
- table es el nombre de la tabla que deseas actualizar.
- schema_file es el archivo de definición de esquema que se escribe en tu máquina local.
Por ejemplo, para escribir la definición de esquema de mydataset.mytable en un archivo, ingresa el siguiente comando. mydataset.mytable está en tu proyecto predeterminado.
```
   bq show \
   --schema \
   --format=prettyjson \
   mydataset.mytable > /tmp/myschema.json
```

Abre el archivo del esquema en un editor de texto. El esquema debe verse de la manera siguiente:

[
  {
    "mode": "REQUIRED",
    "name": "column1",
    "type": "STRING"
  },
  {
    "mode": "REQUIRED",
    "name": "column2",
    "type": "FLOAT"
  },
  {
    "mode": "REPEATED",
    "name": "column3",
    "type": "STRING"
  }
]

Agrega las columnas nuevas al final de la definición del esquema. Si intentas agregar columnas nuevas en otra parte del arreglo, se muestra el siguiente error: BigQuery error in update operation: Precondition Failed.

Con un archivo JSON, puedes especificar descripciones, modos NULLABLE o REPEATED, y tipos RECORD para columnas nuevas. Por ejemplo, mediante la definición de esquema del paso anterior, tu arreglo JSON nuevo se vería de la manera siguiente. En este ejemplo, se agrega una columna NULLABLE nueva llamada column4. column4 incluye una descripción.
```
  [
    {
      "mode": "REQUIRED",
      "name": "column1",
      "type": "STRING"
    },
    {
      "mode": "REQUIRED",
      "name": "column2",
      "type": "FLOAT"
    },
    {
      "mode": "REPEATED",
      "name": "column3",
      "type": "STRING"
    },
    {
      "description": "my new column",
      "mode": "NULLABLE",
      "name": "column4",
      "type": "STRING"
    }
  ]
  
```
Para obtener más información sobre cómo trabajar con archivos de esquema JSON, consulta Especifica un archivo de esquema JSON.
Después de actualizar tu archivo de esquema, ejecuta el comando siguiente para actualizar el esquema de la tabla. Si la tabla que actualizas está en un proyecto que no es tu proyecto predeterminado, agrega el ID del proyecto al nombre del conjunto de datos en el siguiente formato: project_id:dataset.
```
bq update project_id:dataset.table schema
```
En el ejemplo anterior, se ilustra lo siguiente:
- project_id es el ID del proyecto.
- dataset es el nombre del conjunto de datos que contiene la tabla que deseas actualizar.
- table es el nombre de la tabla que deseas actualizar.
- schema es la ruta al archivo de esquema JSON en tu máquina local.
Por ejemplo, ingresa el siguiente comando para actualizar la definición de esquema de mydataset.mytable en tu proyecto predeterminado. La ruta al archivo de esquema en tu máquina local es /tmp/myschema.json.
```
bq update mydataset.mytable /tmp/myschema.json
```

API

Llama al método tables.patch y usa la propiedad schema para agregar columnas vacías a la definición del esquema. Debido a que, con el método tables.update se reemplaza todo el recurso de tabla, es preferible usar el método tables.patch.

Go

Ver en GitHub

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// updateTableAddColumn demonstrates modifying the schema of a table to append an additional column.
func updateTableAddColumn(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	tableRef := client.Dataset(datasetID).Table(tableID)
	meta, err := tableRef.Metadata(ctx)
	if err != nil {
		return err
	}
	newSchema := append(meta.Schema,
		&bigquery.FieldSchema{Name: "phone", Type: bigquery.StringFieldType},
	)
	update := bigquery.TableMetadataToUpdate{
		Schema: newSchema,
	}
	if _, err := tableRef.Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	return nil
}

Java

Antes de probar este ejemplo, sigue las instrucciones de configuración para Java que se encuentran en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.

Modifica esquemas de tabla

Agrega columnas a la definición de esquema de una tabla

Agrega una columna vacía de forma manual

Console

SQL

bq

API

Go

Java

Node.js

Python

Agrega una columna anidada a RECORD

Console

bq

API

Agrega una columna cuando reemplazas o agregas datos

Agrega una columna en un trabajo de carga de anexo

Console

bq

API

Go

Java

Node.js

Python

Agrega una columna en un trabajo de anexo de consulta

Console

bq

API

Go

Java

Node.js

Python

Disminuye la rigurosidad del modo de una columna

Cambia las columnas REQUIRED a NULLABLE de forma manual

Console

bq

API

Go

Java

Node.js

Python

Cambia REQUIRED a NULLABLE en un trabajo de carga o consulta

Cambia REQUIRED a NULLABLE en un trabajo agregado de carga

Console

bq

API

Go

Java

Node.js

Python

Cambia de REQUIRED a NULLABLE en un trabajo de anexo de consulta

Console

bq

API

Go

Java

Python

Agrega una columna anidada a `RECORD`

Cambia las columnas `REQUIRED` a `NULLABLE` de forma manual

Cambia `REQUIRED` a `NULLABLE` en un trabajo de carga o consulta

Cambia `REQUIRED` a `NULLABLE` en un trabajo agregado de carga

Cambia de `REQUIRED` a `NULLABLE` en un trabajo de anexo de consulta