Actualiza etiquetas

En esta página, se explica cómo actualizar las etiquetas de los recursos de BigQuery.

Antes de comenzar

Otorga roles de Identity and Access Management (IAM) que les brindan a los usuarios los permisos necesarios para hacer cada tarea de este documento. Los permisos necesarios para realizar una tarea (si existen) se enumeran en la sección “Permisos necesarios” de la tarea.

Actualiza las etiquetas de conjuntos de datos

Puedes actualizar la etiqueta de un conjunto de datos de las siguientes maneras:

Usa la consola de Google Cloud
Usar declaraciones DDL de SQL
Usa el comando bq update de la herramienta de línea de comandos de bq.
Llamar al método de la API datasets.patch
Con las bibliotecas cliente

Permisos necesarios

Para actualizar una etiqueta de conjunto de datos, necesitas el permiso bigquery.datasets.update de IAM.

Cada una de las siguientes funciones predefinidas de IAM incluye los permisos que necesitas para actualizar la etiqueta de un conjunto de datos:

roles/bigquery.dataOwner
roles/bigquery.admin

Además, si tienes el permiso bigquery.datasets.create, puedes actualizar las etiquetas de los conjuntos de datos que crees.

Para obtener más información sobre las funciones de IAM y los permisos en BigQuery, consulta Funciones y permisos predefinidos.

Actualiza una etiqueta de conjunto de datos

Para actualizar las etiquetas en un conjunto de datos, selecciona una de las siguientes opciones:

Console

En la consola de Google Cloud, selecciona el conjunto de datos.
En la página de detalles del conjunto de datos, haz clic en el ícono de lápiz a la derecha de Labels (Etiquetas).
En el diálogo Editar etiquetas (Edit Labels), haz lo siguiente:
- Para aplicar etiquetas adicionales, haz clic en Agregar etiqueta (Add Label). Se puede usar cada clave solo una vez por conjunto de datos, pero puedes usar la misma clave en otros conjuntos de datos del mismo proyecto.
- Modifica las claves o valores existentes para actualizar una etiqueta.
- Haz clic en Actualizar para guardar los cambios.

SQL

Usa la declaración DDL ALTER SCHEMA SET OPTIONS para configurar las etiquetas en un conjunto de datos existente. La configuración de etiquetas reemplaza cualquier etiqueta existente en el conjunto de datos. En el siguiente ejemplo, se establece una etiqueta en el conjunto de datos mydataset:

En la consola de Google Cloud, ve a la página de BigQuery.

Ir a BigQuery

En el editor de consultas, escribe la siguiente sentencia:

ALTER SCHEMA mydataset
SET OPTIONS (labels = [('sensitivity', 'high')]);

Haz clic en Ejecutar.

Si deseas obtener información sobre cómo ejecutar consultas, visita Ejecuta una consulta interactiva.

bq

Para agregar etiquetas adicionales o actualizar una etiqueta de conjunto de datos, emite el comando bq update con la marca set_label. Repite la marca para agregar o actualizar varias etiquetas.

Si el conjunto de datos está en un proyecto que no es tu proyecto predeterminado, agrega el ID del proyecto al conjunto de datos en el siguiente formato: [PROJECT_ID]:[DATASET].

bq update \
--set_label key:value \
project_id:dataset

Donde:

key:value corresponde a un par clave-valor de una etiqueta que deseas agregar o actualizar. Si especificas la misma clave que una etiqueta existente, se actualiza el valor de esa etiqueta existente. La clave debe ser única.
project_id es el ID del proyecto.
dataset es el conjunto de datos que estás actualizando.

Ejemplo:

Para actualizar la etiqueta department en mydataset, ingresa el comando bq update y especifica department como la clave de etiqueta. Por ejemplo, para actualizar la etiqueta department:shipping a department:logistics, ingresa el siguiente comando: mydataset está en myotherproject, no en tu proyecto predeterminado.

    bq update \
    --set_label department:logistics \
    myotherproject:mydataset

El resultado se verá de la siguiente manera.

Dataset 'myotherproject:mydataset' successfully updated.

API

Para agregar etiquetas adicionales o actualizar una etiqueta en un conjunto de datos existente, llama al método datasets.patch y agrega o actualiza la propiedad labels del recurso de conjunto de datos.

Debido a que el método datasets.update reemplaza todo el recurso del conjunto de datos, es preferible usar el método datasets.patch.

Go

Antes de probar este ejemplo, sigue las instrucciones de configuración para Go incluidas 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 Go.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

import (
	"context"
	"fmt"

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

// addDatasetLabel demonstrates adding label metadata to an existing dataset.
func addDatasetLabel(projectID, datasetID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	ds := client.Dataset(datasetID)
	meta, err := ds.Metadata(ctx)
	if err != nil {
		return err
	}

	update := bigquery.DatasetMetadataToUpdate{}
	update.SetLabel("color", "green")
	if _, err := ds.Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	return nil
}

Java

En este ejemplo, se usa la biblioteca cliente HTTP de Google para Java a fin de enviar una solicitud a la API de BigQuery.

Antes de probar este ejemplo, sigue las instrucciones de configuración para Java incluidas 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.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;
import java.util.HashMap;
import java.util.Map;

// Sample to updates a label on dataset
public class LabelDataset {

  public static void runLabelDataset() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    labelDataset(datasetName);
  }

  public static void labelDataset(String datasetName) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // This example dataset starts with existing label { color: 'green' }
      Dataset dataset = bigquery.getDataset(datasetName);
      // Add label to dataset
      Map<String, String> labels = new HashMap<>();
      labels.put("color", "green");

      dataset.toBuilder().setLabels(labels).build().update();
      System.out.println("Label added successfully");
    } catch (BigQueryException e) {
      System.out.println("Label was not added. \n" + e.toString());
    }
  }
}

Node.js

Antes de probar este ejemplo, sigue las instrucciones de configuración para Node.js incluidas 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 Node.js.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function labelDataset() {
  // Updates a label on a dataset.

  /**
   * TODO(developer): Uncomment the following lines before running the sample
   */
  // const datasetId = "my_dataset";

  // Retrieve current dataset metadata.
  const dataset = bigquery.dataset(datasetId);
  const [metadata] = await dataset.getMetadata();

  // Add label to dataset metadata
  metadata.labels = {color: 'green'};
  const [apiResponse] = await dataset.setMetadata(metadata);

  console.log(`${datasetId} labels:`);
  console.log(apiResponse.labels);
}

Python

Antes de probar este ejemplo, sigue las instrucciones de configuración para Python incluidas 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 Python.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.


from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set dataset_id to the ID of the dataset to fetch.
# dataset_id = "your-project.your_dataset"

dataset = client.get_dataset(dataset_id)  # Make an API request.
dataset.labels = {"color": "green"}
dataset = client.update_dataset(dataset, ["labels"])  # Make an API request.

print("Labels added to {}".format(dataset_id))

Actualiza etiquetas de tabla y vista

Después de crear una tabla o vista, puedes actualizar una etiqueta de las siguientes maneras:

Usa la consola de Google Cloud
Usa el comando bq update de la herramienta de línea de comandos de bq.
Llamar al método tables.patch de la API
- Debido a que las vistas se tratan como recursos de tabla, debes usar el método tables.patch para modificar las vistas y las tablas.
Con las bibliotecas cliente

Permisos necesarios

Para actualizar la etiqueta de una vista o tabla, necesitas el permiso bigquery.tables.update de IAM.

Cada una de las siguientes funciones predefinidas de IAM incluye los permisos que necesitas para actualizar la etiqueta de una tabla o vista:

roles/bigquery.dataEditor
roles/bigquery.dataOwner
roles/bigquery.admin

Además, si tienes el permiso bigquery.datasets.create, puedes actualizar las etiquetas de las tablas y vistas en los conjuntos de datos que crees.

Para obtener más información sobre las funciones y los permisos de IAM en BigQuery, consulta Funciones y permisos predefinidos.

Actualiza etiquetas de vistas o tablas

Sigue estos pasos para actualizar una etiqueta de vista o tabla:

Console

En la consola de Google Cloud, selecciona la tabla o vista.
Haz clic en la pestaña Detalles (Details) y, luego, en el ícono de lápiz a la derecha de Etiquetas (Labels).
En el diálogo Editar etiquetas (Edit Labels), haz lo siguiente:
- Para aplicar etiquetas adicionales, haz clic en Agregar etiqueta (Add Label). Se puede usar cada clave solo una vez por tabla o vista, pero puedes usar la misma clave en tablas o vistas de otros conjuntos de datos.
- Modifica las claves o valores existentes para actualizar una etiqueta.
- Haz clic en Actualizar para guardar los cambios.

SQL

Usa la declaración DDL ALTER TABLE SET OPTIONS para configurar las etiquetas en una tabla existente o la declaración DDL ALTER VIEW SET OPTIONS para configurar las etiquetas en una vista existente. Si configuras etiquetas, se reemplazan las etiquetas existentes en la tabla o vista. En el siguiente ejemplo, se establecen dos etiquetas en la tabla mytable:

En la consola de Google Cloud, ve a la página de BigQuery.

Ir a BigQuery

En el editor de consultas, escribe la siguiente sentencia:

ALTER TABLE mydataset.mytable
SET OPTIONS (
  labels = [('department', 'shipping'), ('cost_center', 'logistics')]);

Haz clic en Ejecutar.

Si deseas obtener información sobre cómo ejecutar consultas, visita Ejecuta una consulta interactiva.

bq

Para agregar etiquetas adicionales, actualizar una etiqueta de tabla o vista, emite el comando bq update con la marca set_label. Repite la marca para agregar o actualizar varias etiquetas.

Si la tabla o vista está en un proyecto que no es tu proyecto predeterminado, agrega el ID del proyecto al conjunto de datos en el siguiente formato: project_id:dataset.

bq update \
--set_label key:value \
project_id:dataset.table_or_view

Donde:

key:value corresponde a un par clave-valor de una etiqueta que deseas agregar o actualizar. Si especificas la misma clave que una etiqueta existente, se actualiza el valor de esa etiqueta existente. La clave debe ser única.
project_id es el ID del proyecto.
dataset es el conjunto de datos que contiene la tabla o la vista que deseas actualizar.
table_or_view es el nombre de la tabla o la vista que deseas actualizar.

Ejemplo:

A fin de actualizar la etiqueta department para mytable, ingresa el comando bq update y especifica department como la clave de etiqueta. Por ejemplo, a fin de actualizar la etiqueta department:shipping a department:logistics para mytable, ingresa el siguiente comando: mytable está en myotherproject, no en tu proyecto predeterminado.

    bq update \
    --set_label department:logistics \
    myotherproject:mydataset.mytable

El resultado tiene el siguiente aspecto:

Table 'myotherproject:mydataset.mytable' successfully updated.

API

A fin de agregar etiquetas o actualizar una etiqueta para una tabla o vista existentes, llama al método tables.patch y agrega o actualiza la propiedad labels del recurso de tabla.

Debido a que las vistas se tratan como recursos de tabla, debes usar el método tables.patch para modificar las vistas y las tablas.

Debido a que, con el método tables.update se reemplaza todo el recurso del conjunto de datos, es preferible usar el método tables.patch.

Go

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

import (
	"context"
	"fmt"

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

// addTableLabel demonstrates adding Label metadata to a BigQuery table.
func addTableLabel(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()

	tbl := client.Dataset(datasetID).Table(tableID)
	meta, err := tbl.Metadata(ctx)
	if err != nil {
		return err
	}

	update := bigquery.TableMetadataToUpdate{}
	update.SetLabel("color", "green")
	if _, err := tbl.Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	return nil
}

Java

En este ejemplo, se usa la biblioteca cliente HTTP de Google para Java a fin de enviar una solicitud a la API de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Table;
import com.google.cloud.bigquery.TableId;
import java.util.HashMap;
import java.util.Map;

// Sample to adds a label to an existing table
public class LabelTable {

  public static void runLabelTable() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    labelTable(datasetName, tableName);
  }

  public static void labelTable(String datasetName, String tableName) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // This example table starts with existing label { color: 'green' }
      Table table = bigquery.getTable(TableId.of(datasetName, tableName));
      // Add label to table
      Map<String, String> labels = new HashMap<>();
      labels.put("color", "green");

      table.toBuilder().setLabels(labels).build().update();
      System.out.println("Label added successfully");
    } catch (BigQueryException e) {
      System.out.println("Label was not added. \n" + e.toString());
    }
  }
}

Node.js

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function labelTable() {
  // Adds a label to an existing table.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  const dataset = bigquery.dataset(datasetId);
  const [table] = await dataset.table(tableId).get();

  // Retrieve current table metadata
  const [metadata] = await table.getMetadata();

  // Add label to table metadata
  metadata.labels = {color: 'green'};
  const [apiResponse] = await table.setMetadata(metadata);

  console.log(`${tableId} labels:`);
  console.log(apiResponse.labels);
}

Python

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

# from google.cloud import bigquery
# client = bigquery.Client()
# project = client.project
# dataset_ref = bigquery.DatasetReference(project, dataset_id)
# table_ref = dataset_ref.table('my_table')
# table = client.get_table(table_ref)  # API request

assert table.labels == {}
labels = {"color": "green"}
table.labels = labels

table = client.update_table(table, ["labels"])  # API request

assert table.labels == labels

Actualiza etiquetas de trabajo

Actualmente, no se admite la actualización de una etiqueta de trabajo. Para actualizar la etiqueta en un trabajo, vuelve a enviar el trabajo con una nueva etiqueta especificada.

Convierte etiquetas en rótulos identificadores

Una etiqueta que tiene una clave con un valor vacío se usa como un rótulo identificador. Puedes crear una etiqueta nueva sin valor o puedes convertir una etiqueta existente en un rótulo identificador en un conjunto de datos, tabla o vista. No puedes convertir la etiqueta de un trabajo en un rótulo identificador.

Los rótulos identificadores pueden ser útiles en situaciones en las que etiquetes un recurso, pero que no sea necesario el formato key:value. Por ejemplo, si tienes una tabla que contiene datos de prueba que usan varios grupos (asistencia, desarrollo, etc.), puedes agregar un rótulo identificador test_data a la tabla para identificarla.

Permisos necesarios

Para convertir una etiqueta en un rótulo identificador, necesitas los siguientes permisos de IAM:

bigquery.datasets.update (te permite convertir una etiqueta de conjunto de datos)
bigquery.tables.update (te permite convertir una etiqueta de tabla o vista)

Cada una de las siguientes funciones predefinidas de IAM incluye los permisos que necesitas para convertir una etiqueta de conjunto de datos:

roles/bigquery.dataOwner
roles/bigquery.admin

Cada una de las siguientes funciones predefinidas de IAM incluye los permisos que necesitas para convertir una etiqueta de una tabla o vista:

roles/bigquery.dataEditor
roles/bigquery.dataOwner
roles/bigquery.admin

Además, si tienes el permiso bigquery.datasets.create, puedes actualizar las etiquetas de los conjuntos de datos que crees y las tablas y vistas de esos conjuntos de datos.

Para obtener más información sobre las funciones y los permisos de IAM en BigQuery, consulta Funciones y permisos predefinidos.

Convierte una etiqueta en un rótulo identificador

Sigue estos pasos para convertir una etiqueta en un rótulo identificador:

Console

En la consola de Google Cloud, selecciona el conjunto de datos, tabla o vista.
Para los conjuntos de datos, la página Detalles de conjuntos de datos (Dataset Details) se abre de forma automática. Para las tablas y vistas, haz clic en Detalles a fin de abrir la página de detalles.
En la página de detalles, haz clic en el ícono de lápiz a la derecha de Labels (Etiquetas).
En el diálogo Editar etiquetas (Edit Labels), haz lo siguiente:
- Borra el valor de una etiqueta existente.
- Haz clic en Actualizar.

bq

Para convertir una etiqueta en un rótulo identificador, usa el comando bq update con la marca set_label. Especifica la clave, seguida de dos puntos, pero no especifiques el valor. Esto actualiza una etiqueta existente en un rótulo identificador.

bq update \
--set_label key: \
resource_id

Donde:

key: es la clave de etiqueta que deseas actualizar a un rótulo identificador.
resource_id es un nombre válido de conjunto de datos, tabla o vista. Si el recurso está en un proyecto que no es el predeterminado, debes agregar el ID del proyecto al comando con el formato siguiente: project_id:dataset.

Ejemplos:

Ingresa el siguiente comando para cambiar la etiqueta test_data:development existente en mydataset a un rótulo: mydataset está en myotherproject, no en tu proyecto predeterminado.

bq update --set_label test_data: myotherproject:mydataset

El resultado tiene el siguiente aspecto:

Dataset 'myotherproject:mydataset' successfully updated.

API

Para convertir una etiqueta existente en un rótulo, llama al método datasets.patch o al método tables.patch y reemplaza los valores de la etiqueta con la string vacía ("") en el recurso de conjunto de datos o el recurso de tabla.

Debido a que las vistas se tratan como recursos de tabla, debes usar el método tables.patch para modificar las vistas y las tablas. Además, debido a que con el método tables.update se reemplaza todo el recurso del conjunto de datos, es preferible usar el método tables.patch.

¿Qué sigue?

Aprende a agregar etiquetas a los recursos de BigQuery.
Aprende a ver etiquetas en los recursos de BigQuery.
Aprende a filtrar recursos mediante etiquetas.
Aprende a borrar etiquetas de los recursos de BigQuery.
Aprende a usar etiquetas en la documentación de Resource Manager.