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:

  • Con Cloud Console o la IU web clásica de BigQuery
  • Con el comando bq update de la herramienta de línea de comandos
  • Con una llamada al método datasets.patch de la API
  • Con las 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 Cloud 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).

    Lápiz de etiqueta

  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.

IU clásica

  1. En la IU web, selecciona el conjunto de datos.

  2. En la página Dataset Details (Detalles del conjunto de datos), a la derecha de Etiquetas, haz clic en Edit (Editar).

    Editar etiquetas

  3. En el diálogo Edit Labels (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 Aceptar.

      Etiqueta nueva

CLI

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 para una etiqueta que desees agregar o actualizar. Si especificas la misma clave que usa una etiqueta existente, se actualiza el valor de esa etiqueta existente. La clave debe ser exclusiva.
  • project_id es el ID del proyecto.
  • dataset es el conjunto de datos que quieres actualizar.

Ejemplo:

Para actualizar la etiqueta department en mydataset, ingresa el comando bq update y especifica 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 esta muestra, sigue las instrucciones de configuración para Go que se encuentran en la Guía de inicio rápido: Usa bibliotecas cliente. A fin de obtener más información, consulta la documentación de referencia de la API de BigQuery para Go.

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)
	}

	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 esta muestra, sigue las instrucciones de configuración para Java que se encuentran en la Guía de inicio rápido: Usa bibliotecas cliente. Si deseas obtener más información, consulta la página sobre la documentación de referencia de la API de BigQuery para Java.

static final HttpTransport HTTP_TRANSPORT = new NetHttpTransport();
static final JsonFactory JSON_FACTORY = new JacksonFactory();

public static class Dataset {
  @Key private Map<String, String> labels;

  public Map<String, String> getLabels() {
    return this.labels;
  }

  public Dataset addLabel(String key, String value) {
    if (this.labels == null) {
      this.labels = new HashMap<>();
    }
    this.labels.put(key, value);
    return this;
  }
}

/**
 * Add or modify a label on a dataset.
 *
 * <p>See <a href="https://cloud.google.com/bigquery/docs/labeling-datasets">the BigQuery
 * documentation</a>.
 */
public static void labelDataset(
    String projectId, String datasetId, String labelKey, String labelValue) throws IOException {

  // Authenticate requests using Google Application Default credentials.
  GoogleCredential credential = GoogleCredential.getApplicationDefault();
  credential = credential.createScoped(Arrays.asList("https://www.googleapis.com/auth/bigquery"));

  // Get a new access token.
  // Note that access tokens have an expiration. You can reuse a token rather than requesting a
  // new one if it is not yet expired.
  credential.refreshToken();
  String accessToken = credential.getAccessToken();

  // Set the content of the request.
  Dataset dataset = new Dataset();
  dataset.addLabel(labelKey, labelValue);
  HttpContent content = new JsonHttpContent(JSON_FACTORY, dataset);

  // Send the request to the BigQuery API.
  String urlFormat =
      "https://www.googleapis.com/bigquery/v2/projects/%s/datasets/%s"
          + "?fields=labels&access_token=%s";
  GenericUrl url = new GenericUrl(String.format(urlFormat, projectId, datasetId, accessToken));
  HttpRequestFactory requestFactory = HTTP_TRANSPORT.createRequestFactory();
  HttpRequest request = requestFactory.buildPostRequest(url, content);
  request.setParser(JSON_FACTORY.createJsonObjectParser());

  // Workaround for transports which do not support PATCH requests.
  // See: http://stackoverflow.com/a/32503192/101923
  request.setHeaders(new HttpHeaders().set("X-HTTP-Method-Override", "PATCH"));
  HttpResponse response = request.execute();

  // Check for errors.
  if (response.getStatusCode() != 200) {
    throw new RuntimeException(response.getStatusMessage());
  }

  Dataset responseDataset = response.parseAs(Dataset.class);
  System.out.printf(
      "Updated label \"%s\" with value \"%s\"\n",
      labelKey, responseDataset.getLabels().get(labelKey));
}

Node.js

Antes de probar esta muestra, sigue las instrucciones de configuración para Node.js que se encuentran en la Guía de inicio rápido: Usa bibliotecas cliente. A fin de obtener más información, consulta la documentación de referencia de la API de BigQuery para Node.js.

// 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 que se encuentran en la Guía de inicio rápido: Usa bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de BigQuery para Python.

# TODO(developer): Import the client library.
# from google.cloud import bigquery

# TODO(developer): 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:

  • Con Cloud Console o la IU web clásica de BigQuery
  • Con el comando bq update de la herramienta de línea de comandos
  • Con una llamada 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 una tabla o vista, debes tener los permisos bigquery.tables.update. Las siguientes funciones predefinidas de Cloud 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 de Cloud IAM y los permisos en BigQuery, consulta Funciones y permisos predefinidos.

Actualiza una etiqueta de vista o tabla

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.

IU clásica

  1. En la IU web, selecciona la tabla o vista.

  2. En la página de detalles, a la derecha de Etiquetas, haz clic en Editar. En este ejemplo, se muestran los detalles de una tabla.

    Editar etiquetas

  3. En el diálogo Edit Labels (Editar etiquetas), sigue estos pasos:

    • Para agregar 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 Aceptar.

      Etiqueta nueva

CLI

Para agregar etiquetas adicionales, actualizar una tabla o ver la etiqueta, 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 para una etiqueta que desees agregar o actualizar. Si especificas la misma clave que usa una etiqueta existente, se actualiza el valor de esa etiqueta existente. La clave debe ser exclusiva.
  • project_id es el ID del proyecto.
  • dataset es el conjunto de datos que contiene la tabla o vista que quieres actualizar.
  • table_or_view es el nombre de la tabla o vista que quieres actualizar.

Ejemplo:

A fin de actualizar la etiqueta department para mytable, ingresa el comando bq update y especifica 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 el método tables.update reemplaza todo el recurso del conjunto de datos, es preferible usar el método tables.patch.

Go

Antes de probar esta muestra, sigue las instrucciones de configuración para Go que se encuentran en la Guía de inicio rápido: Usa bibliotecas cliente. A fin de obtener más información, consulta la documentación de referencia de la API de BigQuery para Go.

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)
	}

	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 esta muestra, sigue las instrucciones de configuración para Java que se encuentran en la Guía de inicio rápido: Usa bibliotecas cliente. Si deseas obtener más información, consulta la página sobre la documentación de referencia de la API de BigQuery para Java.

public static class Table {
  @Key private Map<String, String> labels;

  public Map<String, String> getLabels() {
    return this.labels;
  }

  public Table addLabel(String key, String value) {
    if (this.labels == null) {
      this.labels = new HashMap<>();
    }
    this.labels.put(key, value);
    return this;
  }
}

/**
 * Add or modify a label on a table.
 *
 * <p>See <a href="https://cloud.google.com/bigquery/docs/labeling-datasets">the BigQuery
 * documentation</a>.
 */
public static void labelTable(
    String projectId,
    String datasetId,
    String tableId,
    String labelKey,
    String labelValue)
    throws IOException {

  // Authenticate requests using Google Application Default credentials.
  GoogleCredential credential = GoogleCredential.getApplicationDefault();
  credential = credential.createScoped(Arrays.asList("https://www.googleapis.com/auth/bigquery"));

  // Get a new access token.
  // Note that access tokens have an expiration. You can reuse a token rather than requesting a
  // new one if it is not yet expired.
  credential.refreshToken();
  String accessToken = credential.getAccessToken();

  // Set the content of the request.
  Table table = new Table();
  table.addLabel(labelKey, labelValue);
  HttpContent content = new JsonHttpContent(JSON_FACTORY, table);

  // Send the request to the BigQuery API.
  String urlFormat =
      "https://www.googleapis.com/bigquery/v2/projects/%s/datasets/%s/tables/%s"
          + "?fields=labels&access_token=%s";
  GenericUrl url =
      new GenericUrl(String.format(urlFormat, projectId, datasetId, tableId, accessToken));
  HttpRequestFactory requestFactory = HTTP_TRANSPORT.createRequestFactory();
  HttpRequest request = requestFactory.buildPostRequest(url, content);
  request.setParser(JSON_FACTORY.createJsonObjectParser());

  // Workaround for transports which do not support PATCH requests.
  // See: http://stackoverflow.com/a/32503192/101923
  request.setHeaders(new HttpHeaders().set("X-HTTP-Method-Override", "PATCH"));
  HttpResponse response = request.execute();

  // Check for errors.
  if (response.getStatusCode() != 200) {
    throw new RuntimeException(response.getStatusMessage());
  }

  Table responseTable = response.parseAs(Table.class);
  System.out.printf(
      "Updated label \"%s\" with value \"%s\"\n",
      labelKey, responseTable.getLabels().get(labelKey));
}

Node.js

Antes de probar esta muestra, sigue las instrucciones de configuración para Node.js que se encuentran en la Guía de inicio rápido: Usa bibliotecas cliente. A fin de obtener más información, consulta la documentación de referencia de la API de BigQuery para Node.js.

// 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 que se encuentran en la Guía de inicio rápido: Usa bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de BigQuery para Python.

# from google.cloud import bigquery
# client = bigquery.Client()
# table_ref = client.dataset('my_dataset').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

Cómo actualizar 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 tabla o ver la etiqueta

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

  • bigquery.dataOwner
  • bigquery.admin

Las siguientes funciones predefinidas de Cloud 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 de Cloud IAM y los permisos en BigQuery, consulta Funciones y permisos predefinidos.

Convierte una etiqueta en una etiqueta

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.

    Detalles de la tabla

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

    Lápiz de etiqueta

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

    • Borra el valor de una etiqueta existente.
    • Haz clic en Actualizar (Update).

IU clásica

  1. En la IU web, selecciona el conjunto de datos, la tabla o la vista.

  2. Para los conjuntos de datos, la página Detalles de conjuntos de datos se abre de forma automática. 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, a la derecha de Etiquetas, haz clic en Editar.

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

    • Borra el valor de una etiqueta existente.
    • Haz clic en Aceptar.

      Agregar etiqueta

CLI

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 la etiqueta que deseas convertir en 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 el método tables.update reemplaza todo el recurso del conjunto de datos, es preferible usar el método tables.patch.

Pasos siguientes