Actualiza etiquetas

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

Actualiza las etiquetas de conjuntos de datos

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

• 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 datasets.patch
• Mediante bibliotecas cliente

Permisos necesarios

Como mínimo, para actualizar una etiqueta de conjunto de datos, debes tener los permisos bigquery.datasets.update. Las siguientes funciones predefinidas de IAM incluyen los permisos bigquery.datasets.update:

• bigquery.dataOwner
• bigquery.admin

Además, si un usuario tiene permisos bigquery.datasets.create, se le otorga el acceso bigquery.dataOwner cuando crea un conjunto de datos. El acceso bigquery.dataOwner le da al usuario la capacidad de actualizar etiquetas en un conjunto de datos.

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 etiquetas en un conjunto de datos, debes hacer lo siguiente:

Console

1. En Cloud Console, selecciona el conjunto de datos.

2. En la página de detalles del conjunto de datos, haz clic en el ícono de lápiz a la derecha de Labels (Etiquetas).

   

3. En el diálogo Editar etiquetas, sigue estos pasos:

   • 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.

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

En el ejemplo anterior, se ilustra lo siguiente:

• 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 que se encuentran en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de Go de BigQuery.

Ver en GitHubComentarios

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 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.

Ver en GitHubComentarios

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 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 Node.js de BigQuery.

Ver en GitHubComentarios

// 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 esta muestra, 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. Si deseas obtener más información, consulta la documentación de referencia de la API de Python de BigQuery.

Ver en GitHubComentarios

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 Cloud Console.
• Usar 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

Como mínimo, para actualizar una etiqueta de tabla o vista, debes tener los permisos bigquery.tables.update. Las siguientes funciones predefinidas de IAM incluyen los permisos bigquery.tables.update:

• bigquery.dataEditor
• bigquery.dataOwner
• bigquery.admin

Además, si un usuario tiene permisos bigquery.datasets.create, se le otorga el acceso bigquery.dataOwner cuando crea un conjunto de datos. El acceso de bigquery.dataOwner permite al usuario actualizar las etiquetas de sus conjuntos de datos y de 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.

Actualiza etiquetas de vistas o tablas

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

Console

1. En Cloud Console, selecciona la tabla o vista.

2. Haz clic en la pestaña Detalles y, luego, en el ícono de lápiz a la derecha de Etiquetas.

3. En el cuadro de 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.

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

En el ejemplo anterior, se ilustra lo siguiente:

• 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 adicionales 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

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

Ver en GitHubComentarios

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.

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.

Ver en GitHubComentarios

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 instrucciones de configuración para Node.js 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 Node.js de BigQuery.

Ver en GitHubComentarios

// 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 esta muestra, 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. Si deseas obtener más información, consulta la documentación de referencia de la API de Python de BigQuery.

Ver en GitHubComentarios

# 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

Como mínimo, los permisos necesarios para convertir una etiqueta en un rótulo identificador son los mismos que se necesitan a fin de actualizar las etiquetas.

• bigquery.datasets.update para convertir una etiqueta de conjunto de datos
• bigquery.tables.update para convertir una etiqueta de tabla o vista

Las siguientes funciones predefinidas de IAM incluyen los permisos bigquery.datasets.update:

• bigquery.dataOwner
• bigquery.admin

Las siguientes funciones predefinidas de IAM incluyen los permisos bigquery.tables.update:

• bigquery.dataEditor
• bigquery.dataOwner
• bigquery.admin

Además, si un usuario tiene permisos bigquery.datasets.create, se le otorga el acceso bigquery.dataOwner cuando crea un conjunto de datos. El acceso de bigquery.dataOwner permite al usuario actualizar las etiquetas de sus conjuntos de datos y de 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

1. En Cloud Console, selecciona el conjunto de datos, tabla o vista.

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

   

3. En la página de detalles, haz clic en el ícono de lápiz a la derecha de Labels (Etiquetas).

   

4. En el diálogo Editar etiquetas, sigue estos pasos:

   • 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

En el ejemplo anterior, se ilustra lo siguiente:

• 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.