Agrega etiquetas a los recursos

En este documento, se describe cómo agregar etiquetas a los recursos de BigQuery, incluidos los siguientes:

Para obtener más información sobre las etiquetas en BigQuery, consulta Introducción a las etiquetas.

Antes de comenzar

Otorga a los usuarios los roles de Identity and Access Management (IAM) necesarios para realizar cada tarea de este documento. En la sección “Roles de IAM obligatorios” de cada tarea, se enumeran los permisos necesarios para realizarla.

Agrega etiquetas a los conjuntos de datos

Puedes agregar una etiqueta a un conjunto de datos de BigQuery cuando lo creas con el comando bq mk de la herramienta de línea de comandos de bq o con una llamada al método datasets.insert de la API. No puedes agregar una etiqueta a un conjunto de datos cuando lo creas con la Google Cloud consola. Sin embargo, puedes agregar una etiqueta de conjunto de datos después de la creación. Para obtener más información sobre la creación de un conjunto de datos, consulta Crea un conjunto de datos.

Cuando agregas una etiqueta a un conjunto de datos, esta no se propaga a los recursos dentro del conjunto de datos. Las tablas o las vistas no heredan las etiquetas del conjunto de datos. Además, cuando agregas una etiqueta a un conjunto de datos, se incluye en tus datos de facturación de almacenamiento, pero no en tus datos de facturación relacionados con el trabajo.

Para obtener más información sobre el formato de las etiquetas, consulta Requisitos para las etiquetas.

Roles de IAM obligatorios

Para obtener el permiso que necesitas para agregar una etiqueta a un conjunto de datos existente, pídele a tu administrador que te otorgue el rol de IAM de propietario de datos de BigQuery (roles/bigquery.dataOwner). Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene el permiso bigquery.datasets.update, que se requiere para agregar una etiqueta a un conjunto de datos existente.

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

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

Agrega una etiqueta a un conjunto de datos

Sigue estos pasos para agregar una etiqueta a un conjunto de datos después de crearla:

Console

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

  2. En la página de detalles del conjunto de datos, en la sección Etiquetas, haz clic en  Editar.

    Ícono de lápiz junto a la sección Etiquetas.

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

    • Haz clic en Agregar etiqueta.
    • Ingresa la clave y el valor en los campos correspondientes. 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.
    • Para actualizar una etiqueta, modifica las claves o valores existentes.
    • Para guardar los cambios, haz clic en Update (Actualizar).

SQL

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

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

    Ir a BigQuery

  2. En el editor de consultas, escribe la siguiente sentencia:

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

  3. Haz clic en Ejecutar.

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

bq

Para agregar una etiqueta a un conjunto de datos existente, usa el comando bq update con la marca set_label. Para agregar varias etiquetas, repite la marca.

Si el conjunto de datos está en un proyecto que no es el predeterminado, especifica el ID del proyecto en el siguiente formato: PROJECT_ID:DATASET.

bq update --set_label KEY:VALUE PROJECT_ID:DATASET

Reemplaza lo siguiente:

  • KEY:VALUE: Es el par clave-valor de una etiqueta que deseas agregar. La clave debe ser única. Las claves y los valores pueden contener solo letras en minúscula, caracteres numéricos, guiones bajos y guiones. Todos los caracteres deben usar la codificación UTF-8 y se permiten los caracteres internacionales.
  • PROJECT_ID: el ID de tu proyecto
  • DATASET: Es el conjunto de datos que deseas etiquetar.

Ejemplos:

Si deseas agregar una etiqueta para realizar un seguimiento de los departamentos, usa el comando bq update y especifica department como la clave de la etiqueta. Por ejemplo, para agregar una etiqueta department:shipping a mydataset en tu proyecto predeterminado, usa el siguiente comando:

    bq update --set_label department:shipping mydataset

Para agregar varias etiquetas a un conjunto de datos, repite la marca set_label y especifica una clave única para cada etiqueta. Por ejemplo, para agregar una etiqueta department:shipping y cost_center:logistics a mydataset en tu proyecto predeterminado, usa lo siguiente:

    bq update \
    --set_label department:shipping \
    --set_label cost_center:logistics \
    mydataset

API

Para agregar una etiqueta a un conjunto de datos existente, llama al método datasets.patch y propaga la propiedad labels para el recurso de conjunto de datos.

Debido a que el método datasets.update reemplaza todo el recurso del conjunto de datos, usa el método datasets.patch en su lugar.

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 main(String[] args) {
    // 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))

Agrega etiquetas a las tablas y vistas

En este documento, se describe cómo agregar una etiqueta a una tabla o vista existente. Para obtener más información sobre cómo agregar una etiqueta cuando creas una tabla o vista, consulta cómo crear una tabla o crear una vista.

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.

Las etiquetas de tablas y vistas no se incluyen en los datos de facturación.

Roles de IAM obligatorios

Para obtener los permisos que necesitas para agregar una etiqueta a una tabla o vista existente, pídele a tu administrador que te otorgue el rol de IAM Editor de datos de BigQuery (roles/bigquery.dataEditor). Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para agregar una etiqueta a una tabla o vista existente. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para agregar una etiqueta a una tabla o vista existente:

  • bigquery.tables.update
  • bigquery.tables.get

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

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

Agrega una etiqueta a una tabla o vista

Sigue estos pasos para agregar una etiqueta a una tabla o vista existente:

Console

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

  2. Haz clic en la pestaña Detalles.

    Página de detalles de la tabla en la consola de Google Cloud .

  3. En la sección Etiquetas, haz clic en  Editar.

    Ícono de lápiz junto a la sección Etiquetas.

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

    • Haz clic en Agregar etiqueta.
    • Ingresa la clave y el valor en los campos correspondientes. 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 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. Esta acción reemplaza las etiquetas existentes en la tabla o vista. En el siguiente ejemplo, se establecen dos etiquetas en la tabla mytable:

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

    Ir a BigQuery

  2. En el editor de consultas, escribe la siguiente sentencia:

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

  3. Haz clic en Ejecutar.

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

bq

Para agregar una etiqueta a una tabla o vista existente, usa el comando bq update con la marca set_label. Para agregar varias etiquetas, repite la marca.

Si la tabla o la vista están en un proyecto que no es el predeterminado, especifica el ID del proyecto en el siguiente formato: PROJECT_ID:DATASET.

bq update \
--set_label KEY:VALUE \
PROJECT_ID:DATASET.TABLE_OR_VIEW

Reemplaza lo siguiente:

  • KEY:VALUE: Es el par clave-valor de una etiqueta que deseas agregar. La clave debe ser única. Las claves y los valores pueden contener solo letras en minúscula, caracteres numéricos, guiones bajos y guiones. Todos los caracteres deben usar la codificación UTF-8 y se permiten los caracteres internacionales.
  • PROJECT_ID: el ID de tu proyecto
  • DATASET: Es el conjunto de datos que contiene la tabla o vista que deseas etiquetar.
  • TABLE_OR_VIEW: Es el nombre de la tabla o vista que deseas etiquetar.

Ejemplos:

Para agregar una etiqueta de tabla que rastrea los departamentos, usa el comando bq update y especifica department como la clave de etiqueta. Por ejemplo, para agregar una etiqueta department:shipping a mytable en tu proyecto predeterminado, usa el siguiente comando:

    bq update --set_label department:shipping mydataset.mytable

Para agregar una etiqueta de vista que realice un seguimiento de los departamentos, usa el comando bq update y especifica department como la clave de etiqueta. Por ejemplo, para agregar una etiqueta department:shipping a myview en tu proyecto predeterminado, usa el siguiente comando:

    bq update --set_label department:shipping mydataset.myview

Para agregar varias etiquetas a una tabla o vista, repite la marca set_label y especifica una clave exclusiva para cada etiqueta. Por ejemplo, para agregar una etiqueta department:shipping y cost_center:logistics a mytable en tu proyecto predeterminado, usa lo siguiente:

    bq update \
    --set_label department:shipping \
    --set_label cost_center:logistics \
    mydataset.mytable

API

Para agregar una etiqueta a una tabla o vista existente, llama al método tables.patch y propaga la propiedad labels para 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.

Debido a que el método tables.update reemplaza todo el recurso del conjunto de datos, usa el método tables.patch en su lugar.

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

// 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 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.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 main(String[] args) {
    // 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 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 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 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

client = bigquery.Client()

# TODO(dev): Change table_id to the full name of the table you want to create.
table_id = "your-project.your_dataset.your_table_name"

table = client.get_table(table_id)  # API request

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

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

print(f"Added {table.labels} to {table_id}.")

Agrega etiquetas a los trabajos

Se pueden agregar etiquetas a los trabajos de consulta con la marca --label en la herramienta de línea de comandos de bq. La herramienta bq admite que se agreguen etiquetas solo a trabajos de consulta.

También puedes agregar una etiqueta a un trabajo cuando se envía a través de la API si especificas la propiedad labels en la configuración del trabajo cuando llamas al método jobs.insert. La API se puede usar para agregar etiquetas a cualquier tipo de trabajo.

No puedes agregar ni actualizar etiquetas en trabajos pendientes, en ejecución o completados.

Cuando agregas una etiqueta a un trabajo, la etiqueta se incluye en tus datos de facturación.

Roles de IAM obligatorios

Para obtener el permiso que necesitas para agregar una etiqueta a un trabajo, pídele a tu administrador que te otorgue el rol de IAM Usuario de BigQuery (roles/bigquery.user). Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene el permiso bigquery.jobs.create, que se requiere para agregar una etiqueta a un trabajo.

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

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

Agrega una etiqueta a un trabajo

Para agregar una etiqueta a un trabajo, considera lo siguiente:

bq

Para agregar una etiqueta a un trabajo de consulta, usa el comando bq query con la marca --label. Para agregar varias etiquetas, repite la marca. La marca indica que tu consulta usa la sintaxis de GoogleSQL.

bq query --label KEY:VALUE  'QUERY'

Reemplaza lo siguiente:

  • KEY:VALUE: Es el par clave-valor de una etiqueta que deseas agregar al trabajo de consulta. La clave debe ser única. Las claves y los valores pueden contener solo letras en minúscula, caracteres numéricos, guiones bajos y guiones. Todos los caracteres deben usar la codificación UTF-8 y se permiten los caracteres internacionales. Para agregar varias etiquetas a un trabajo de consulta, repite la marca --label y especifica una clave única para cada etiqueta.
  • QUERY: Es una consulta de GoogleSQL válida.

Ejemplos:

Para agregar una etiqueta a un trabajo de consulta, usa el siguiente comando:

    bq query \
    --label department:shipping \
     \
    'SELECT
       column1, column2
     FROM
       `mydataset.mytable`'

Para agregar varias etiquetas a un trabajo de consulta, repite la marca --label y especifica una clave única para cada etiqueta. Por ejemplo, para agregar una etiqueta department:shipping y una etiqueta cost_center:logistics a un trabajo de consulta, usa lo siguiente:

    bq query \
    --label department:shipping \
    --label cost_center:logistics \
     \
    'SELECT
       column1, column2
     FROM
       `mydataset.mytable`'

API

Si deseas agregar una etiqueta a un trabajo, llama al método jobs.insert y propaga la propiedad labels para la configuración del trabajo. Puedes usar la API para agregar etiquetas a cualquier tipo de trabajo.

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

client = bigquery.Client()

sql = """
    SELECT corpus
    FROM `bigquery-public-data.samples.shakespeare`
    GROUP BY corpus;
"""
labels = {"color": "green"}

config = bigquery.QueryJobConfig()
config.labels = labels
location = "us"
job = client.query(sql, location=location, job_config=config)
job_id = job.job_id

print(f"Added {job.labels} to {job_id}.")

Asocia trabajos en una sesión con una etiqueta

Si ejecutas consultas en una sesión, puedes asignar una etiqueta a todos los trabajos de consulta futuros en esa sesión con las consultas de varias declaraciones de BigQuery.

SQL

Configura la variable de sistema @@query_label en la sesión ejecutando la siguiente consulta:

  SET @@query_label = "KEY:VALUE";

  • KEY:VALUE: Es el par clave-valor de la etiqueta que se asignará a todas las consultas futuras en la sesión. También puedes agregar varios pares clave-valor separados por una coma, por ejemplo, SET @@query_label = "key1:value1,key2:value2". La clave debe ser única. Las claves y los valores pueden contener solo letras en minúscula, caracteres numéricos, guiones bajos y guiones. Todos los caracteres deben usar la codificación UTF-8 y se permiten los caracteres internacionales.

Ejemplo:

  SET @@query_label = "cost_center:logistics";

API

Para agregar una etiqueta a un trabajo de consulta en una sesión cuando ejecutas una consulta mediante una llamada a la API, llama al método jobs.insert y propaga la propiedad query_label de la configuración del trabajo connectionProperties.

Después de asociar una etiqueta de consulta con una sesión y ejecutar consultas en esa sesión, puedes recopilar registros de auditoría para esas consultas. Si deseas obtener más información, consulta la referencia del registro de auditoría para BigQuery.

Cómo agregar una etiqueta a una reserva

Cuando agregas una etiqueta a una reserva, se incluye en tus datos de facturación. Puedes usar etiquetas para filtrar el SKU de atribución de los espacios de análisis en tus datos de facturación de Cloud.

El SKU de atribución de ranuras de análisis solo registra el uso de ranuras. No registra los costos de los SKU de la API de BigQuery Reservation. Las etiquetas de reserva no se admiten como filtros para los SKU de la API de BigQuery Reservation.

Para obtener más información sobre el uso de etiquetas en tus datos de facturación, consulta Cómo usar filtros para definir mejor los datos.

Roles de IAM obligatorios

Para obtener el permiso que necesitas para agregar una etiqueta a una reserva, pídele a tu administrador que te otorgue el rol de IAM Editor de recursos de BigQuery (roles/bigquery.resourceEditor) en el proyecto de administración. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene el permiso bigquery.reservations.update, que se requiere para agregar una etiqueta a una reserva.

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

Cómo agregar una etiqueta a una reserva

Para agregar una etiqueta a una reserva, sigue estos pasos:

Console

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

    Ir a BigQuery

  2. En el menú de navegación, haz clic en Administración de la capacidad.

  3. Haz clic en la pestaña Reservas de ranuras.

  4. Busca la reserva que deseas actualizar.

  5. Expande la opción Actions.

  6. Haz clic en Editar.

  7. Para expandir la sección Configuración avanzada, haz clic en la flecha de expansión.

  8. Haz clic en Agregar etiqueta.

  9. Ingresa el par clave-valor en los campos correspondientes. Para aplicar etiquetas adicionales, haz clic en Agregar etiqueta.

  10. Haz clic en Guardar.

SQL

Para agregar una etiqueta a una reserva, usa la sentencia DDL ALTER RESERVATION SET OPTIONS. Esta acción reemplaza las etiquetas existentes en la reserva. En el siguiente ejemplo, se establece una etiqueta en la reserva myreservation:

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

    Ir a BigQuery

  2. En el editor de consultas, escribe la siguiente sentencia:

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

  3. Haz clic en Ejecutar.

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

bq

Para agregar una etiqueta a una reserva, usa el comando bq update con las marcas set_label y --reservation. Para agregar varias etiquetas, repite la marca set_label.

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

Reemplaza lo siguiente:

  • KEY:VALUE: Es el par clave-valor de una etiqueta que deseas agregar a la reserva. La clave debe ser única. Las claves y los valores pueden contener solo letras en minúscula, caracteres numéricos, guiones bajos y guiones. Todos los caracteres deben usar la codificación UTF-8 y se permiten los caracteres internacionales. Para agregar varias etiquetas a una reserva, repite la marca --set_label y especifica una clave única para cada etiqueta.
  • LOCATION: la ubicación de la reserva. La marca location no puede ser la última en el comando, ya que, de lo contrario, se mostrará el error FATAL Flags positioning.
  • RESERVATION_NAME por el nombre de la reserva.

Agrega una etiqueta sin un valor

Una etiqueta que tiene una clave con un valor vacío a veces se denomina rótulo identificador. No se debe confundir con un recurso de etiqueta. Para obtener más información, consulta Etiquetas y rótulos identificadores. Puedes crear una etiqueta nueva sin valor o quitar un valor de una clave de etiqueta existente.

Las etiquetas sin valores son útiles cuando etiquetas un recurso, pero no necesitas el formato de clave-valor. Por ejemplo, si una tabla contiene datos de prueba que usan varios grupos, como la asistencia o el desarrollo, puedes agregar una etiqueta test_data a la tabla para identificarla.

Para agregar una etiqueta sin valor, haz lo siguiente:

Console

  1. En la consola de Google Cloud , selecciona el recurso adecuado (un conjunto de datos, una tabla o una vista).

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

    Página de detalles de la tabla en la consola de Google Cloud .

  3. En la página de detalles, en la sección Etiquetas, haz clic en  Editar.

    Ícono de lápiz junto a la sección Etiquetas.

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

    • Haz clic en Agregar etiqueta.
    • Ingresa una clave nueva en el campo correspondiente y deja el campo de valor en blanco. Para aplicar etiquetas adicionales, haz clic en Agregar etiqueta y repite el proceso.
    • Para guardar los cambios, haz clic en Update (Actualizar).

SQL

Para agregar una etiqueta sin un valor, usa la sentencia DDL ALTER TABLE SET OPTIONS:

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

    Ir a BigQuery

  2. En el editor de consultas, escribe la siguiente sentencia:

    ALTER TABLE mydataset.mytable
SET OPTIONS (
  labels=[("key1", ""), ("key2", "")]);

  3. Haz clic en Ejecutar.

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

bq

Para agregar una etiqueta sin un valor a un recurso existente, usa el comando bq update con la marca set_label. Especifica la clave, seguida de dos puntos, pero no especifiques el valor.

bq update --set_label KEY: RESOURCE_ID

Reemplaza lo siguiente:

  • KEY:: Es la clave de etiqueta que deseas usar.
  • 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, especifica el ID del proyecto con el siguiente formato: PROJECT_ID:DATASET.

Ejemplos:

Usa el siguiente comando para crear una etiqueta test_data para mydataset.mytable. mydataset está en tu proyecto predeterminado.

bq update --set_label test_data: mydataset

API

Llama al método datasets.patch o tables.patch y agrega etiquetas con el valor de string vacía ("") en el recurso de conjunto de datos o el recurso de tabla. Puedes quitar los valores de las etiquetas existentes si reemplazas sus valores por la string vacía.

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, usa el método tables.patch en su lugar.

¿Qué sigue?