Agrega etiquetas a los recursos
Esta página explica cómo etiquetar los recursos de BigQuery.
Antes de comenzar
Otorga roles de administración de identidades y accesos (IAM) que les brindan a los usuarios los permisos necesarios para realizar cada tarea de este documento. Todos los permisos necesarios para realizar una tarea se enumeran en la sección “Roles de IAM obligatorios” de la tarea.
Agrega etiquetas a los conjuntos de datos
Una etiqueta se puede agregar a un conjunto de datos de BigQuery cuando se crea mediante el comando bq mk
de la herramienta de línea de comandos de bq o mediante una llamada al método datasets.insert
de la API. En la actualidad, no puedes agregar una etiqueta a un conjunto de datos cuando este se crea con la consola de Google Cloud.
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 Crea un conjunto de datos.
Se puede agregar una etiqueta después de la creación de un conjunto de datos de las formas siguientes:
- Usa la consola de Google Cloud
- Usar declaraciones DDL de SQL
- Usa el comando
bq update
de la herramienta de línea de comandos de bq. - Llamar al método de la API
datasets.patch
- Usar bibliotecas cliente
Cuando agregas una etiqueta a un conjunto de datos, no se propaga a los recursos dentro de este. Las tablas ni las vistas 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 detalles sobre el formato de una etiqueta, consulta Requisitos de 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 Editor de datos de BigQuery (roles/bigquery.dataEditor
).
Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso.
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 los roles 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
En la consola de Google Cloud, selecciona el conjunto de datos.
En la página de detalles del conjunto de datos, haz clic en el ícono de lápiz a la derecha de Labels (Etiquetas).
En el diálogo Editar etiquetas, haz lo siguiente:
- Haz clic en Agregar etiqueta.
- Ingresa la clave y el valor. 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. La configuración de etiquetas reemplaza cualquier etiqueta existente en el conjunto de datos. En el siguiente ejemplo, se establece una etiqueta en el conjunto de datos mydataset
:
En la consola de Google Cloud, ve a la página de BigQuery.
En el editor de consultas, escribe la siguiente sentencia:
ALTER SCHEMA mydataset SET OPTIONS ( labels = [('sensitivity', 'high')]);
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, envía el comando bq update
con la marca set_label
. Repite la marca para agregar varias etiquetas.
Si el conjunto de datos está en un proyecto que no es 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
Reemplaza lo siguiente:
KEY:VALUE
: Es un par clave-valor para una etiqueta que deseas agregar. La clave debe ser exclusiva. 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 proyectoDATASET
: Es el conjunto de datos que deseas etiquetar.
Ejemplos:
Si deseas agregar una etiqueta para realizar un seguimiento de los departamentos, ingresa 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, ingresa lo siguiente:
bq update --set_label department:shipping mydataset
Si deseas agregar varias etiquetas a un conjunto de datos, repite la marca set_label
y especifica una clave única para cada etiqueta. Por ejemplo, a fin de 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
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, con el método datasets.update
se reemplaza todo el recurso del conjunto de datos, es preferible usar el método datasets.patch
.
Go
Antes de probar este ejemplo, sigue las instrucciones de configuración para Go 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.
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.
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.
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.
Agrega etiquetas a las tablas y vistas
Se puede agregar una etiqueta a una tabla o vista cuando se crea mediante alguna de estas acciones:
- Usar el comando
bq mk
de la herramienta de línea de comandos de bq - Llamar al método de la 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 crear una vista.
Se puede agregar una etiqueta cuando se crea una tabla o vista mediante estas acciones:
- Usa la consola de Google Cloud
- Usa el comando
bq update
de la herramienta de línea de comandos de bq - Llamar al método de la API
tables.patch
- Usar bibliotecas cliente
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.
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.
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 los roles 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
En la consola de Google Cloud, selecciona la tabla o vista.
Haz clic en la pestaña Detalles.
Haz clic en el ícono de lápiz a la derecha de Etiquetas (Labels).
En el diálogo Editar etiquetas, haz lo siguiente:
- Haz clic en Agregar etiqueta (Add label).
- Ingresa la clave y el valor para agregar una etiqueta. 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. Si configuras etiquetas, se reemplazan las etiquetas existentes en la tabla o vista. En el siguiente ejemplo, se establecen dos etiquetas en la tabla mytable
:
En la consola de Google Cloud, ve a la página de BigQuery.
En el editor de consultas, escribe la siguiente sentencia:
ALTER TABLE mydataset.mytable SET OPTIONS ( labels = [('department', 'shipping'), ('cost_center', 'logistics')]);
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, envía 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, 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
Reemplaza lo siguiente:
KEY:VALUE
: Es un par clave-valor para una etiqueta que deseas agregar. La clave debe ser exclusiva. 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 proyectoDATASET
: 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, 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 lo siguiente:
bq update --set_label department:shipping mydataset.mytable
Para agregar una etiqueta de vista que rastrea 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 lo siguiente:
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, ingresa 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, con el método tables.update
se reemplaza todo el recurso del conjunto de datos, es preferible usar el método tables.patch
.
Go
Antes de probar este ejemplo, sigue las instrucciones de configuración para Go 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.
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.
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.
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.
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.
Este rol predefinido contiene el permiso bigquery.jobs.create
, que es necesario 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 los roles 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, envía el comando bq query
con la marca --label
. Para agregar varias etiquetas, repite la marca. La marca --nouse_legacy_sql
indica que tu consulta está en la sintaxis de GoogleSQL.
bq query --label KEY:VALUE --nouse_legacy_sql 'QUERY'
Reemplaza lo siguiente:
KEY:VALUE
: Es un par clave-valor para una etiqueta que deseas agregar al trabajo de consulta. La clave debe ser exclusiva. 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, ingresa lo siguiente:
bq query \
--label department:shipping \
--nouse_legacy_sql \
'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, ingresa lo siguiente:
bq query \
--label department:shipping \
--label cost_center:logistics \
--nouse_legacy_sql \
'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.
Asocia trabajos en una sesión con una etiqueta
Si ejecutas consultas en una sesión, puedes asignar una etiqueta para todos los trabajos de consulta futuros en la sesión con las consultas de varias declaraciones de BigQuery.
SQL
Configura la variable de sistema @@query_label
en la sesión mediante la ejecución de esta consulta:
SET @@query_label = "KEY:VALUE";
- KEY:VALUE: es un par clave-valor que la etiqueta asignará a todas las consultas futuras en la sesión. La clave debe ser exclusiva. 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 dentro de la sesión, puedes recopilar registros de auditoría para las consultas con esa etiqueta de consulta. Si deseas obtener más información, consulta la referencia del registro de auditoría para BigQuery.
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 pueden ser útiles en situaciones en las que etiquetes un recurso, pero no necesites 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
En la consola de Google Cloud, selecciona el recurso adecuado (un conjunto de datos, una tabla o una vista).
Para los conjuntos de datos, la página Detalles de conjuntos de datos (Dataset Details) se abre de forma automática. Para las tablas y vistas, haz clic en Detalles (Details) a fin de abrir la página de detalles.
En la página de detalles, haz clic en el ícono de lápiz a la derecha de Labels (Etiquetas).
En el diálogo Editar etiquetas, haz lo siguiente:
- Haz clic en Agregar etiqueta (Add label).
- Ingresa una clave nueva y deja el 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
:
En la consola de Google Cloud, ve a la página de BigQuery.
En el editor de consultas, escribe la siguiente sentencia:
ALTER TABLE mydataset.mytable SET OPTIONS ( labels=[("key1", ""), ("key2", "")]);
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, debes agregar el ID del proyecto al comando con el formato siguiente:PROJECT_ID:DATASET
.
Ejemplos:
Ingresa el siguiente comando a fin de 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 con el método tables.update
se reemplaza todo el recurso del conjunto de datos, es preferible usar el método tables.patch
.
¿Qué sigue?
- Obtén más información sobre cómo ver etiquetas en los recursos de BigQuery.
- Aprende a actualizar etiquetas de los recursos de BigQuery.
- Aprende a filtrar recursos mediante etiquetas.
- Aprende a borrar etiquetas de los recursos de BigQuery.
- Aprende a usar etiquetas en la documentación de Resource Manager.