Agregar y usar etiquetas

Para organizar tus recursos de BigQuery, puedes agregar etiquetas a tus conjuntos de datos, tablas y vistas. Las etiquetas son pares clave-valor que puedes adjuntar a un recurso. Cuando creas recursos de BigQuery, las etiquetas son opcionales.

Después de etiquetar tus recursos, puedes buscarlos según los valores de las etiquetas. Por ejemplo, con las etiquetas puedes agrupar conjuntos de datos por propósito, entorno, departamento, etcétera.

Esta página explica cómo etiquetar los recursos de BigQuery.

Para obtener más información sobre la administración de etiquetas, consulta Cómo administrar etiquetas.

¿Qué son las etiquetas?

Una etiqueta es un par clave-valor que te ayuda a organizar tus recursos de BigQuery en Google Cloud Platform. Puedes adjuntar una etiqueta a cada recurso y filtrar cada uno según sus etiquetas. La información sobre las etiquetas se reenvía al sistema de facturación a fin de que puedas desglosar tus cargos de facturación según las etiquetas.

Usos comunes de las etiquetas

Estos son algunos casos prácticos comunes de las etiquetas:

  • Etiquetas por equipo o centro de costo: Agrega etiquetas por equipo o centro de costo a fin de distinguir los recursos de BigQuery que sean propiedad de distintos equipos (por ejemplo, team:research y team:analytics). Puedes usar este tipo de etiquetas para la contabilidad de costos o la creación de presupuestos.

  • Etiquetas de componentes: Por ejemplo, component:redis, component:frontend, component:ingest y component:dashboard.

  • Etiquetas de entorno o de etapa: Por ejemplo, environment:production y environment:test.

  • Etiquetas de estado: Por ejemplo, state:active, state:readytodelete y state:archive.

Requisitos para las etiquetas

Las etiquetas que se aplican a un recurso deben cumplir los siguientes requisitos:

  • Cada recurso puede tener varias etiquetas, hasta 64.
  • Cada etiqueta debe ser un par clave-valor.
  • La longitud de las claves debe ser de entre 1 y 63 caracteres, y no pueden estar vacías. Los valores pueden estar vacíos y su longitud máxima es de 63 caracteres.
  • 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, además, se permiten los caracteres internacionales.
  • La porción de clave de una etiqueta debe ser única. Sin embargo, puedes usar la misma clave en varios recursos.
  • Las claves deben comenzar con una letra en minúscula o un carácter internacional.

Cómo agregar etiquetas de conjunto de datos

Cuando se crea una etiqueta, esta se puede agregar a un conjunto de datos de BigQuery mediante el comando bq mk de la herramienta de línea de comandos o con una llamada al método de API datasets.insert. Actualmente, no puedes agregar una etiqueta a un conjunto de datos cuando se crea a través de la IU web de BigQuery.

Esta página explica cómo agregar una etiqueta a un conjunto de datos después de crearla. Para obtener más información sobre cómo agregar una etiqueta cuando creas un conjunto de datos, consulta Cómo crear un conjunto de datos.

Una etiqueta se incluye en tus datos de facturación de almacenamiento cuando la agregas a un conjunto de datos, pero no verás etiquetas de conjuntos de datos en los datos de facturación relacionados con el trabajo.

Permisos necesarios

Para agregar una etiqueta a un conjunto de datos existente debes tener acceso de OWNER a nivel de conjunto de datos o tener asignada una función de IAM a nivel de proyecto que incluya permisos bigquery.datasets.update. Las siguientes funciones de IAM a nivel de proyecto predefinidas incluyen los permisos bigquery.datasets.update:

Además, debido a que la función bigquery.user tiene permisos bigquery.datasets.create, un usuario asignado a la función bigquery.user puede actualizar cualquier conjunto de datos que cree el usuario. Cuando un usuario asignado a la función bigquery.user crea un conjunto de datos, se le otorga acceso de OWNER al conjunto de datos. El acceso de OWNER a un conjunto de datos permite al usuario un control total sobre este.

Para obtener más información sobre las funciones de IAM y los permisos en BigQuery, consulta Control de acceso. A fin de obtener más información sobre las funciones a nivel de conjunto de datos, consulta Funciones básicas para conjuntos de datos.

Cómo agregar una etiqueta a un conjunto de datos

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

IU clásica

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

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

    Editar etiquetas

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

    • Ingresa la clave y el valor para agregar una etiqueta. Para aplicar etiquetas adicionales, haz clic en Agregar etiqueta. 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

Línea de comandos

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

Si el conjunto de datos se encuentra en otro proyecto que no sea el 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. La clave debe ser exclusiva.
  • [PROJECT_ID] es tu ID del proyecto.
  • [DATASET] es el conjunto de datos que etiquetas.

Ejemplos:

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

    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 exclusiva para cada etiqueta. Por ejemplo, para agregar una etiqueta department:shipping y una etiqueta cost_center:logistics a mydataset en tu proyecto predeterminado, ingresa lo siguiente:

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

API

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

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

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 de BigQuery con bibliotecas cliente. Para obtener más información, consulta la Documentación de referencia de la API de Go de BigQuery.

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
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
}

Java

Esta muestra usa la biblioteca cliente HTTP de Google para Java a fin de enviar una solicitud a la API de BigQuery.
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));
}

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 de BigQuery con bibliotecas cliente. Para obtener más información, consulta la Documentación de referencia de la API de Python de BigQuery.

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_ref = client.dataset('my_dataset')
# dataset = client.get_dataset(dataset_ref)  # API request

assert dataset.labels == {}
labels = {'color': 'green'}
dataset.labels = labels

dataset = client.update_dataset(dataset, ['labels'])  # API request

assert dataset.labels == labels

Cómo agregar etiquetas de tabla y vista

Cuando se crea una etiqueta, esta se puede agregar a una tabla o vista mediante el comando bq mk de la herramienta de línea de comandos o con una llamada al método de API tables.insert.

Esta página explica 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 Cómo crear una vista.

Después de crear una tabla o vista, se puede agregar una etiqueta con la IU web de BigQuery, el comando bq update de la herramienta de línea de comandos o una llamada al método de API tables.patch. 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.

Permisos necesarios

Para agregar una etiqueta a una tabla o vista existente, debes tener acceso de OWNER a nivel de conjunto de datos o tener asignada una función de IAM a nivel de proyecto que incluya permisos bigquery.tables.update. Las siguientes funciones de IAM a nivel de proyecto predefinidas incluyen los permisos bigquery.tables.update:

Además, debido a que la función bigquery.user tiene permisos bigquery.datasets.create, un usuario asignado a la función bigquery.user puede actualizar tablas y vistas en cualquier conjunto de datos que cree el usuario. Cuando un usuario asignado a la función bigquery.user crea un conjunto de datos, se le otorga acceso de OWNER al conjunto de datos. El acceso de OWNER a un conjunto de datos permite al usuario un control total sobre este y las tablas y vistas que contenga.

Para obtener más información sobre las funciones de IAM y los permisos en BigQuery, consulta Control de acceso. A fin de obtener más información sobre las funciones a nivel de conjunto de datos, consulta Funciones básicas para conjuntos de datos.

Cómo agregar una etiqueta a una tabla o vista

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

IU web

  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. Este ejemplo muestra los detalles de una tabla.

    Editar etiquetas

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

    • Ingresa la clave y el valor para agregar una etiqueta. Para aplicar etiquetas adicionales, haz clic en Agregar etiqueta. 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.
    • Haz clic en Aceptar.

      Etiqueta nueva

Línea de comandos

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

Si la tabla o vista se encuentra en otro proyecto que no sea el 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. La clave debe ser exclusiva.
  • [PROJECT_ID] es tu ID del proyecto.
  • [DATASET] es el conjunto de datos que contiene la tabla o vista que etiquetas.
  • [TABLE_OR_VIEW] es el nombre de la tabla o vista que etiquetas.

Ejemplos:

Para agregar una etiqueta de tabla que realice un seguimiento de los departamentos, ingresa 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, ingresa:

    bq update --set_label department:shipping mydataset.mytable

Para agregar una etiqueta de vista que realice un seguimiento de los departamentos, ingresa 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, ingresa:

    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 una etiqueta cost_center:logistics a mytable en tu proyecto predeterminado, ingresa:

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

API

A fin de 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 de conjunto de datos, el método tables.patch es preferible.

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 de BigQuery con bibliotecas cliente. Para obtener más información, consulta la Documentación de referencia de la API de Go de BigQuery.

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
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
}

Java

Esta muestra usa la biblioteca cliente HTTP de Google para Java a fin de enviar una solicitud a la API de BigQuery.
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));
}

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 de BigQuery con bibliotecas cliente. Para obtener más información, consulta la Documentación de referencia de la API de Python de BigQuery.

# 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 agregar etiquetas de trabajo

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

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

No puedes agregar etiquetas a trabajos pendientes, en ejecución o completados, ni actualizarlas en ellos.

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

Permisos necesarios

No se requieren permisos especiales para agregar una etiqueta a un trabajo. Si tienes permisos jobs.create, puedes agregar una etiqueta a tu trabajo cuando lo envíes.

Debes tener permisos bigquery.jobs.create para ejecutar un trabajo. Se requieren permisos bigquery.jobs.create para trabajos que BigQuery crea automáticamente y trabajos que ejecutas de manera programática.

Otorga permisos bigquery.jobs.create a tu cuenta de usuario o de servicio para ejecutar trabajos de BigQuery, o puedes otorgar a tu proyecto una función de IAM predefinida a nivel de proyecto que incluya permisos bigquery.jobs.create. Las siguientes funciones de IAM predefinidas incluyen permisos bigquery.jobs.create:

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

Cómo agregar una etiqueta a un trabajo

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

IU web

La IU web de BigQuery no admite que se agreguen etiquetas a trabajos.

Línea de comandos

Ejecuta el comando bq query con la marca --label para agregar una etiqueta a un trabajo de consulta. Repite la marca para agregar varias etiquetas. La marca --nouse_legacy_sql indica que tu consulta tiene una sintaxis SQL estándar.

bq query --label [KEY:VALUE] --nouse_legacy_sql '[QUERY]'

Donde:

  • [KEY:VALUE] corresponde a un par clave-valor para una etiqueta que desees agregar al trabajo de consulta. La clave debe ser exclusiva. Para agregar varias etiquetas a un trabajo de consulta, repite la marca --label y especifica una clave exclusiva para cada etiqueta.
  • [QUERY] es una consulta de SQL estándar válida.

Ejemplos:

Para agregar una etiqueta a un trabajo de consulta, ingresa lo siguiente:

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

A fin de agregar varias etiquetas a un trabajo de consulta, repite la marca --label y especifica una clave exclusiva para cada etiqueta. Por ejemplo, para agregar una etiqueta department:shipping y una etiqueta cost_center:logistics a un trabajo de consulta, ingresa lo siguiente:

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

API

A fin de agregar una etiqueta a un trabajo, llama al método jobs.insert y propaga la propiedad labels para el recurso de trabajo. Puedes usar la API para agregar etiquetas a cualquier tipo de trabajo.

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 de BigQuery con bibliotecas cliente. Para obtener más información, consulta la Documentación de referencia de la API de Go de BigQuery.

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
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
}

Cómo crear una etiqueta

Una etiqueta que tiene una clave con un valor vacío se usa como una etiqueta. Puedes crear una etiqueta nueva sin valor o convertir una que ya exista en una etiqueta.

Las etiquetas pueden ser útiles en situaciones en las que etiquetes un recurso, pero que no sea necesario el formato clave-valor. Por ejemplo, si tienes una tabla que contiene datos de prueba que varios grupos usan (asistencia, desarrollo, etcétera), puedes agregar una etiqueta test_data a la tabla para identificarla.

Sigue estos pasos para crear una etiqueta:

IU web

  1. En la IU web, selecciona el recurso adecuado (un conjunto de datos, una tabla o una vista).

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

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

    • Ingresa una clave nueva y deja el valor en blanco. Para aplicar etiquetas adicionales, haz clic en Agregar etiqueta.
    • Haz clic en Aceptar.

      Agregar etiqueta

Línea de comandos

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

bq update --set_label [KEY]: [RESOURCE_ID]

Donde:

  • [KEY] es la clave de etiqueta personalizada que deseas usar como etiqueta.
  • [RESOURCE_ID] es un nombre válido de conjunto de datos, tabla o vista. Si el recurso se encuentra en otro proyecto que no sea el predeterminado, agrega el ID del proyecto en el siguiente formato: [PROJECT_ID]:[DATASET].

Ejemplos:

Ingresa el siguiente comando a fin de crear una etiqueta test_data para mydataset.mytable. mydataset se encuentra en tu proyecto predeterminado.

bq update --set_label test_data: mydataset

API

Llama al método datasets.patch o al método tables.patch y agrega etiquetas con el valor configurado a la string vacía ("") en el recurso de conjunto de datos o el recurso de tabla. Puedes convertir las etiquetas personalizadas existentes en etiquetas si reemplazas sus valores con 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 de conjunto de datos, el método tables.patch es preferible.

Cómo ver las etiquetas

Puedes ver las etiquetas con la IU web de BigQuery, el comando bq show de la herramienta de línea de comandos o una llamada a los métodos de API datasets.get o tables.get. Debido a que las vistas se tratan como recursos de tabla, debes usar el método tables.get para obtener información de etiquetas de las vistas y las tablas.

Permisos necesarios

Los permisos necesarios para ver las etiquetas dependen del tipo de recurso al que accedas.

Permisos del conjunto de datos

Para obtener información sobre un conjunto de datos, debes tener asignada la función de READER a nivel de proyecto o una función de IAM a nivel de proyecto que incluya permisos bigquery.datasets.get. Todas las funciones predefinidas de IAM a nivel de proyecto incluyen permisos bigquery.datasets.get excepto bigquery.jobUser.

Además, un usuario a quien se le asigna la función bigquery.user tiene permisos bigquery.datasets.create. Esto permite a un usuario con la función bigquery.user obtener información sobre cualquier conjunto de datos que el usuario cree. Cuando un usuario asignado a la función bigquery.user crea un conjunto de datos, se le otorga acceso de OWNER al conjunto de datos. El acceso de OWNER a un conjunto de datos permite al usuario un control total sobre este.

Para obtener más información sobre las funciones de IAM y los permisos en BigQuery, consulta Control de acceso. A fin de obtener más información sobre las funciones a nivel de conjunto de datos, consulta Funciones básicas para conjuntos de datos.

Permisos de tabla y vista

Para obtener más información sobre tablas, debes tener asignada la función de READER en el conjunto de datos o una función de IAM predefinida a nivel de proyecto que incluya permisos bigquery.tables.get. Si tienes permisos bigquery.tables.get otorgados a nivel de proyecto, puedes obtener información sobre todas las tablas del proyecto. Todas las funciones de IAM predefinidas a nivel de proyecto incluyen permisos bigquery.tables.get excepto bigquery.user y bigquery.jobUser.

Además, un usuario a quien se le asigna la función bigquery.user tiene permisos bigquery.datasets.create. Esto permite a un usuario con la función bigquery.user obtener información sobre tablas en cualquier conjunto de datos que el usuario cree. Cuando un usuario asignado a la función bigquery.user crea un conjunto de datos, se le otorga acceso de OWNER al conjunto de datos. El acceso de OWNER a un conjunto de datos permite al usuario un control total sobre este y todas las tablas y vistas que contenga.

Para obtener más información sobre las funciones de IAM y los permisos en BigQuery, consulta Control de acceso. A fin de obtener más información sobre las funciones a nivel de conjunto de datos, consulta Funciones básicas para conjuntos de datos.

Permisos de trabajo

Para obtener datos y metadatos de trabajo, debes tener permisos bigquery.jobs.get. Las siguientes funciones de IAM a nivel de proyecto predefinidas incluyen permisos bigquery.jobs.get:

Si le otorgas a una cuenta la función bigquery.admin, el usuario podrá ver todos los datos del trabajo del proyecto sin importar quién haya enviado el trabajo.

A las siguientes funciones se les otorgan permisos bigquery.jobs.get en los trabajos que ellos mismos crearon. Estos usuarios solo podrán ver los datos del trabajo que envíen:

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

Cómo ver etiquetas de conjunto de datos, tabla y vista

Sigue estos pasos para ver las etiquetas de un recurso:

IU web

  1. En la IU web, selecciona el recurso adecuado (un conjunto de datos, una tabla o una vista).

  2. Para los conjuntos de datos, la página 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. La información de la etiqueta aparece en la tabla de información del recurso.

Línea de comandos

Usa el comando bq show con el ID de recurso. La marca --format se puede usar para controlar el resultado. Si el recurso se encuentra en otro proyecto que no sea el predeterminado, agrega el ID del proyecto en el siguiente formato: [PROJECT_ID]:[DATASET]. Para facilitar la lectura, el resultado se puede controlar si configuras la marca --format a pretty.

bq show --format=pretty [RESOURCE_ID]

Donde [RESOURCE_ID] es un nombre válido de conjunto de datos, tabla o vista.

Ejemplos:

Ingresa el siguiente comando para mostrar las etiquetas de mydataset en tu proyecto predeterminado.

bq show --format=pretty mydataset

Ingresa el siguiente comando para mostrar las etiquetas de mydataset.mytable. mydataset se encuentra en myotherproject, no en tu proyecto predeterminado.

bq show --format=pretty myotherproject:mydataset.mytable

API

Llama al método datasets.get o al método tables.get. En la respuesta, se incluyen todas las etiquetas asociadas con ese recurso.

Como alternativa, puedes usar datasets.list a fin de ver las etiquetas de varios conjuntos de datos o tables.list para ver las etiquetas de varias tablas y vistas.

Debido a que las vistas se tratan como recursos de tabla, debes usar los métodos tables.get y tables.list para ver información de las etiquetas de las vistas y las tablas.

Go

Esta muestra usa la biblioteca cliente HTTP de Google para Java a fin de enviar una solicitud a la API de BigQuery.
// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
meta, err := client.Dataset(datasetID).Metadata(ctx)
if err != nil {
	return err
}
fmt.Fprintf(w, "Dataset %s labels:\n", datasetID)
if len(meta.Labels) == 0 {
	fmt.Fprintln(w, "Dataset has no labels defined.")
	return nil
}
for k, v := range meta.Labels {
	fmt.Fprintf(w, "\t%s:%s\n", k, v)
}

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 de BigQuery con bibliotecas cliente. Para obtener más información, consulta la Documentación de referencia de la API de Python de BigQuery.

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'my_dataset'

dataset_ref = client.dataset(dataset_id)
dataset = client.get_dataset(dataset_ref)  # API request

# View dataset labels
print('Dataset ID: {}'.format(dataset_id))
print('Labels:')
if dataset.labels:
    for label, value in dataset.labels.items():
        print('\t{}: {}'.format(label, value))
else:
    print("\tDataset has no labels defined.")

Cómo ver las etiquetas de trabajo

Después de enviar el trabajo de consulta, las etiquetas de trabajo no aparecen en la IU web de BigQuery. Para ver las etiquetas en un trabajo, ejecuta el comando bq show -j [JOB_ID].

IU web

No puedes ver las etiquetas de trabajo mediante la IU web de BigQuery.

CLI

Ingresa el comando bq show -j con el ID de trabajo del trabajo de consulta a fin de ver sus etiquetas con la herramienta de línea de comandos bq. Se puede usar la marca --format para controlar los resultados. Por ejemplo, si tu trabajo de consulta tiene el ID de trabajo bqjob_r1234d57f78901_000023746d4q12_1, ingresa el siguiente comando:

bq show -j --format=pretty bqjob_r1234d57f78901_000023746d4q12_1

El resultado debe verse de la siguiente manera:

+----------+---------+-----------------+----------+-------------------+-----------------+--------------+----------------------+
| Job Type |  State  |   Start Time    | Duration |    User Email     | Bytes Processed | Bytes Billed |        Labels        |
+----------+---------+-----------------+----------+-------------------+-----------------+--------------+----------------------+
| query    | SUCCESS | 03 Dec 15:00:41 | 0:00:00  | email@example.com | 255             | 10485760     | department:shipping  |
|          |         |                 |          |                   |                 |              | costcenter:logistics |
+----------+---------+-----------------+----------+-------------------+-----------------+--------------+----------------------+

API

Llama al método jobs.get. En la respuesta, se incluyen todas las etiquetas asociadas con ese recurso.

Cómo filtrar conjuntos de datos mediante etiquetas

A fin de filtrar conjuntos de datos según sus etiquetas, crea una especificación de filtro para usarla en la herramienta de línea de comandos bq o en la API de BigQuery que use la siguiente sintaxis:

    "field[:value][ field[:value]..."

Donde:

  • field se expresa como labels.[KEY], donde [KEY] es la clave de etiqueta.
  • value es un valor de etiqueta opcional.

Actualmente, no puedes enumerar tablas o vistas basadas en una especificación de filtro.

Limitaciones

La especificación de filtro tiene las siguientes limitaciones:

  • Solo se admite el operador lógico AND. Las comparaciones separadas por espacios se tratan como si tuvieran operadores AND implícitos.
  • El único campo actualmente apto para filtrar es "labels.key" donde "key" es el nombre de una etiqueta.
  • El filtro puede incluir diez expresiones.
  • El filtro distingue mayúsculas y minúsculas.
  • No puedes filtrar tablas y vistas con una especificación de filtro.
  • Actualmente, no puedes filtrar conjuntos de datos mediante la IU web de BigQuery.

Ejemplos de especificación de filtro

Usa la siguiente especificación de filtro para enumerar conjuntos de datos que tengan una etiqueta department:shipping:

labels.department:shipping

Para enumerar conjuntos de datos mediante varias etiquetas, separa los pares clave-valor con un espacio. El espacio se trata como un operador lógico AND. Por ejemplo, para enumerar conjuntos de datos mediante la etiqueta department:shipping y la etiqueta location:usa, usa la siguiente especificación de filtro:

labels.department:shipping labels.location:usa

Puedes filtrar con la presencia de una clave sola, en lugar de hacerla coincidir con un par clave-valor. En la siguiente especificación de filtro, se enumeran todos los conjuntos de datos con la etiqueta department sin importar el valor:

labels.department

En una especificación de filtro equivalente, se usa un asterisco para representar todos los valores posibles asociados con la clave department:

labels.department:*

También puedes usar etiquetas en una especificación de filtro. Por ejemplo, para enumerar los conjuntos de datos con la etiqueta personalizada department:shipping y la etiqueta test_data, usa la siguiente especificación de filtro:

labels.department:shipping labels.test_data

Cómo generar listas con filtros

Para generar una lista con filtros de conjuntos de datos, considera lo siguiente:

IU web

Actualmente, no puedes filtrar conjuntos de datos mediante la IU web de BigQuery.

Línea de comandos

Ejecuta el comando bq ls con la marca --filter. Si haces una lista de conjuntos de datos en un proyecto que no sea el predeterminado, especifica la marca --project_id.

bq ls --filter "[FILTER_SPECIFICATION]" --project_id [PROJECT_ID]

Donde:

  • [FILTER_SPECIFICATION] es una especificación de filtro válida. La herramienta de línea de comandos muestra una lista de conjuntos de datos que cumplen con los requisitos de filtro.
  • [PROJECT_ID] es tu ID del proyecto.

Ejemplos:

Ingresa el siguiente comando para enumerar conjuntos de datos en tu proyecto predeterminado que tengan una etiqueta department:shipping:

bq ls --filter "labels.department:shipping"

Ingresa el siguiente comando para enumerar conjuntos de datos en tu proyecto predeterminado que tengan una etiqueta personalizada department:shipping y una etiqueta test_data.

bq ls --filter "labels.department:shipping labels.test_data"

Ingresa el siguiente comando para enumerar conjuntos de datos en myotherproject que tengan una etiqueta department:shipping:

bq ls --filter "labels.department:shipping" --project_id myotherproject

API

Llama al método de API datasets.list y proporciona la especificación de filtro con la propiedad filter.

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 de BigQuery con bibliotecas cliente. Para obtener más información, consulta la Documentación de referencia de la API de Go de BigQuery.

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
it := client.Datasets(ctx)
it.Filter = "labels.color:green"
for {
	dataset, err := it.Next()
	if err == iterator.Done {
		break
	}
	if err != nil {
		return err
	}
	fmt.Fprintf(w, "dataset: %s\n", dataset.DatasetID)
}

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 de BigQuery con bibliotecas cliente. Para obtener más información, consulta la Documentación de referencia de la API de Python de BigQuery.

# from google.cloud import bigquery
# client = bigquery.Client()

# The following label filter example will find datasets with an
# arbitrary 'color' label set to 'green'
label_filter = 'labels.color:green'
datasets = list(client.list_datasets(filter=label_filter))

if datasets:
    print('Datasets filtered by {}:'.format(label_filter))
    for dataset in datasets:  # API request(s)
        print('\t{}'.format(dataset.dataset_id))
else:
    print('No datasets found with this filter.')

¿Qué sigue?

¿Te ha resultado útil esta página? Enviar comentarios:

Enviar comentarios sobre...

Si necesitas ayuda, visita nuestra página de asistencia.