Actualizar etiquetas

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

Antes de empezar

Concede roles de gestión de identidades y accesos (IAM) que proporcionen a los usuarios los permisos necesarios para realizar cada tarea de este documento. Los permisos necesarios para realizar una tarea (si los hay) se indican en la sección "Permisos necesarios" de la tarea.

Actualizar etiquetas de conjuntos de datos

Para actualizar la etiqueta de un conjunto de datos, puedes hacer lo siguiente:

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

Permisos obligatorios

Para actualizar una etiqueta de conjunto de datos, necesitas el permiso de gestión de identidades y accesos bigquery.datasets.update.

Cada uno de los siguientes roles de gestión de identidades y accesos predefinidos incluye los permisos que necesitas para actualizar una 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 los roles y permisos de gestión de identidades y accesos en BigQuery, consulta el artículo sobre roles y permisos predefinidos.

Actualizar una etiqueta de un conjunto de datos

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

Consola

  1. En la Google Cloud consola, selecciona el conjunto de datos.

  2. En la página de detalles del conjunto de datos, haz clic en el icono de lápiz situado a la derecha de Etiquetas.

    Lápiz de etiquetas

  3. En el cuadro de diálogo Editar etiquetas, haz lo siguiente:

    • Para aplicar más etiquetas, haz clic en Añadir etiqueta. Cada clave solo se puede usar una vez por conjunto de datos, pero puedes usar la misma clave en diferentes conjuntos de datos del mismo proyecto.
    • Modifica las claves o los valores para actualizar una etiqueta.
    • Haz clic en Update (Actualizar) para guardar los cambios.

SQL

Usa la declaración de DDL ALTER SCHEMA SET OPTIONS para definir las etiquetas de un conjunto de datos. Al definir etiquetas, se sobrescriben las etiquetas que ya tenga el conjunto de datos. En el siguiente ejemplo se asigna una sola etiqueta al conjunto de datos mydataset:

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

    Ir a BigQuery

  2. En el editor de consultas, introduce la siguiente instrucción:

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

  3. Haz clic en Ejecutar.

Para obtener más información sobre cómo ejecutar consultas, consulta Ejecutar una consulta interactiva.

bq

Para añadir más etiquetas o actualizar una etiqueta de un conjunto de datos, ejecuta el comando bq update con la marca set_label. Repite la marca para añadir o actualizar varias etiquetas.

Si el conjunto de datos está en un proyecto que no es el predeterminado, añada el ID del proyecto al conjunto de datos con 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 quiere añadir o actualizar. Si especificas la misma clave que una etiqueta ya creada, se actualizará el valor de la etiqueta. 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, introduce el comando bq update y especifica department como clave de etiqueta. Por ejemplo, para actualizar la etiqueta department:shipping a department:logistics, introduce el siguiente comando. mydataset está en myotherproject, no en tu proyecto predeterminado.

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

La salida tiene el siguiente aspecto.

Dataset 'myotherproject:mydataset' successfully updated.

API

Para añadir etiquetas o actualizar la de un conjunto de datos, llama al método datasets.patch y añade o actualiza la propiedad labels del recurso de conjunto de datos.

Como el método datasets.update sustituye todo el recurso del conjunto de datos, es preferible usar el método datasets.patch.

Go

Antes de probar este ejemplo, sigue las Goinstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Go de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de 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 de cliente HTTP de Google para Java para enviar una solicitud a la API de BigQuery.

Antes de probar este ejemplo, sigue las Javainstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Java de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de 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 Node.jsinstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Node.js de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de 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 Pythoninstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Python de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de 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))

Actualizar etiquetas de tablas y vistas

Una etiqueta se puede actualizar después de crear una tabla o una vista de la siguiente forma:

  • Usar la Google Cloud consola
  • Usar el comando bq update de la herramienta de línea de comandos bq
  • Llamar al método de la API tables.patch
    • Como las vistas se tratan como recursos de tabla, puedes usar el método tables.patch para modificar tanto las vistas como las tablas.
  • Usar las bibliotecas de cliente

Permisos obligatorios

Para actualizar una etiqueta de tabla o de vista, necesitas el permiso de gestión de identidades y accesos bigquery.tables.update.

Cada uno de los siguientes roles de gestión de identidades y accesos predefinidos incluye los permisos que necesitas para actualizar una tabla o una etiqueta de 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 las vistas de los conjuntos de datos que crees.

Para obtener más información sobre los roles y permisos de IAM en BigQuery, consulta el artículo sobre funciones y permisos predefinidos.

Actualizar la etiqueta de una tabla o una vista

Para actualizar la etiqueta de una tabla o una vista, sigue estos pasos:

Consola

  1. En la Google Cloud consola, selecciona la tabla o la vista.

  2. Haz clic en la pestaña Detalles y, a continuación, en el icono de lápiz situado a la derecha de Etiquetas.

  3. En el cuadro de diálogo Editar etiquetas, haz lo siguiente:

    • Para aplicar más etiquetas, haz clic en Añadir etiqueta. Cada clave solo se puede usar una vez por tabla o vista, pero puedes usar la misma clave en tablas o vistas de diferentes conjuntos de datos.
    • Modifica las claves o los valores para actualizar una etiqueta.
    • Haz clic en Update (Actualizar) para guardar los cambios.

SQL

Usa la declaración de DDL ALTER TABLE SET OPTIONS para definir las etiquetas de una tabla que ya tengas o la declaración de DDL ALTER VIEW SET OPTIONS para definir las etiquetas de una vista que ya tengas. Al definir etiquetas, se sobrescriben las etiquetas que ya haya en la tabla o en la vista. En el siguiente ejemplo se definen dos etiquetas en la tabla mytable:

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

    Ir a BigQuery

  2. En el editor de consultas, introduce la siguiente instrucción:

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

  3. Haz clic en Ejecutar.

Para obtener más información sobre cómo ejecutar consultas, consulta Ejecutar una consulta interactiva.

bq

Para añadir más etiquetas o actualizar una etiqueta de tabla o de vista, ejecuta el comando bq update con la marca set_label. Repite la marca para añadir o actualizar varias etiquetas.

Si la tabla o la vista están en un proyecto que no es el predeterminado, añade el ID del proyecto al conjunto de datos con 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 quiere añadir o actualizar. Si especificas la misma clave que una etiqueta ya creada, se actualizará el valor de la etiqueta. 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 quieres actualizar.
  • table_or_view es el nombre de la tabla o la vista que vas a actualizar.

Ejemplo:

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

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

La salida tiene este aspecto:

Table 'myotherproject:mydataset.mytable' successfully updated.

API

Para añadir etiquetas o actualizar una etiqueta de una tabla o una vista, llama al método tables.patch y añade o actualiza la propiedad labels del recurso de tabla.

Como las vistas se tratan como recursos de tabla, puedes usar el método tables.patch para modificar tanto las vistas como las tablas.

Como el método tables.update sustituye todo el recurso del conjunto de datos, es preferible usar el método tables.patch.

Go

Antes de probar este ejemplo, sigue las Goinstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Go de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de 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 de cliente HTTP de Google para Java para enviar una solicitud a la API de BigQuery.

Antes de probar este ejemplo, sigue las Javainstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Java de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de 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

Antes de probar este ejemplo, sigue las Node.jsinstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Node.js de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de 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

Antes de probar este ejemplo, sigue las Pythoninstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Python de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de 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

Actualizar etiquetas de tareas

No se pueden actualizar las etiquetas de los trabajos. Para actualizar la etiqueta de un trabajo, vuelve a enviarlo con una etiqueta nueva.

Actualizar etiquetas de reserva

Puedes actualizar una etiqueta de una reserva. Si actualizas una etiqueta mediante SQL, se sobrescribirán las etiquetas que ya tenga la reserva.

Roles de gestión de identidades y accesos necesarios

Para obtener el permiso que necesitas para actualizar una etiqueta de una reserva, pide a tu administrador que te conceda el rol de gestión de identidades y accesos Editor de recursos de BigQuery (roles/bigquery.resourceEditor) en el proyecto de administración. Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene el permiso bigquery.reservations.update, que es necesario para actualizar una etiqueta a una reserva.

También puedes obtener este permiso con roles personalizados u otros roles predefinidos.

Actualizar una etiqueta de una reserva

Para actualizar una etiqueta de una reserva, sigue estos pasos:

bq

Para actualizar una etiqueta de una reserva, ejecuta el comando bq update con las marcas set_label y --reservation. Para actualizar varias etiquetas, repite la marca.

bq update --set_label KEY:VALUE  --reservation RESERVATION_NAME

Haz los cambios siguientes:

  • KEY:VALUE: un par clave-valor de una etiqueta que quieras actualizar en la reserva. La clave debe ser única. Las claves y los valores solo pueden contener letras en minúscula, caracteres numéricos, guiones y guiones bajos. Todos los caracteres deben usar la codificación UTF-8 y se pueden usar caracteres internacionales. Para actualizar varias etiquetas de una reserva, repite la marca --label y especifica una clave única para cada etiqueta.
  • RESERVATION_NAME: el nombre de la reserva.

SQL

Para actualizar una etiqueta a una reserva, usa la ALTER RESERVATION SET OPTIONS instrucción DDL statement para definir las etiquetas en una reserva. Al definir etiquetas, se sobrescriben las etiquetas que ya tenga la reserva. En el siguiente ejemplo se asigna una etiqueta a la reserva myreservation:

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

    Ir a BigQuery

  2. En el editor de consultas, introduce la siguiente instrucción:

    ALTER RESERVATION myreservation
    SET OPTIONS (
      labels = [('sensitivity', 'high')]);

  3. Haz clic en Ejecutar.

Para obtener más información sobre cómo ejecutar consultas, consulta Ejecutar una consulta interactiva.

Convertir etiquetas en tags

Una etiqueta que tiene una clave con un valor vacío se usa como etiqueta. Puedes crear una etiqueta sin valor o convertir una etiqueta en una etiqueta de un conjunto de datos, una tabla o una vista. No puedes convertir una etiqueta de tarea en una etiqueta.

Las etiquetas pueden ser útiles en situaciones en las que se etiqueta un recurso, pero no se necesita el formato key:value. Por ejemplo, si tiene una tabla que contiene datos de prueba que utilizan varios grupos (asistencia, desarrollo, etc.), puede añadir una etiqueta test_data a la tabla para identificarla.

Permisos obligatorios

Para convertir una etiqueta en una marca, necesitas los siguientes permisos de gestión de identidades y accesos:

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

Cada uno de los siguientes roles de gestión de identidades y accesos predefinidos incluye los permisos que necesitas para convertir una etiqueta de un conjunto de datos:

  • roles/bigquery.dataOwner
  • roles/bigquery.admin

Cada uno de los siguientes roles de gestión de identidades y accesos predefinidos incluye los permisos que necesitas para convertir una etiqueta de tabla o de 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, así como las tablas y las vistas de esos conjuntos de datos.

Para obtener más información sobre los roles y permisos de IAM en BigQuery, consulta el artículo sobre funciones y permisos predefinidos.

Convertir una etiqueta en una etiqueta

Para convertir una etiqueta en una etiqueta:

Consola

  1. En la Google Cloud consola, selecciona el conjunto de datos, la tabla o la vista.

  2. En el caso de los conjuntos de datos, se abre automáticamente la página de detalles del conjunto de datos. En el caso de las tablas y las vistas, haz clic en Detalles para abrir la página de detalles.

    Detalles de la tabla

  3. En la página de detalles, haz clic en el icono de lápiz situado a la derecha de Etiquetas.

    Lápiz de etiquetas

  4. En el cuadro de diálogo Editar etiquetas, haz lo siguiente:

    • Elimina el valor de una etiqueta.
    • Haz clic en Actualizar.

bq

Para convertir una etiqueta en una etiqueta, usa el comando bq update con la set_label marca. Especifique la clave, seguida de dos puntos, pero deje el valor sin especificar. De esta forma, se actualiza una etiqueta a una etiqueta.

bq update \
--set_label key: \
resource_id

Donde:

  • key: es la clave de la etiqueta que quieres actualizar.
  • resource_id es un nombre de conjunto de datos, tabla o vista válido. Si el recurso está en un proyecto que no es el predeterminado, añade el ID del proyecto con el siguiente formato: project_id:dataset.

Ejemplos:

Introduce el siguiente comando para cambiar la etiqueta test_data:development de mydataset por una etiqueta. mydataset está en myotherproject, no en tu proyecto predeterminado.

bq update --set_label test_data: myotherproject:mydataset

La salida tiene este aspecto:

Dataset 'myotherproject:mydataset' successfully updated.

API

Para convertir una etiqueta en una marca, llama al método datasets.patch o al método tables.patch y sustituye los valores de la etiqueta por la cadena vacía ("") en el recurso de conjunto de datos o en el recurso de tabla.

Como las vistas se tratan como recursos de tabla, puedes usar el método tables.patch para modificar tanto las vistas como las tablas. Además, como el método tables.update sustituye todo el recurso del conjunto de datos, es preferible usar el método tables.patch.

Siguientes pasos