Administrar canalizaciones

Las canalizaciones de BigQuery te permiten inspeccionar el historial de ejecuciones, configurar alertas de fallas y controlar los recursos de código con la tecnología de Dataform. También puedes enriquecer los metadatos del flujo de trabajo en Knowledge Catalog para hacer un seguimiento de la calidad de los datos y borrar los flujos de trabajo obsoletos para mantener tu proyecto organizado. Según dónde almacene el código tu equipo, puedes acceder a las canalizaciones en Archivos y carpetas, incluidas las carpetas de usuario y de equipo, o en repositorios de Git de BigQuery Studio (carpetas de Git) (versión preliminar).

Antes de comenzar

1. Crea una canalización de BigQuery.
2. Para administrar los metadatos de la canalización en Knowledge Catalog, asegúrate de que la API de Dataplex esté habilitada en tu proyecto de Google Cloud .

Roles obligatorios

Para obtener los permisos que necesitas para administrar canalizaciones, pídele a tu administrador que te otorgue los siguientes roles de IAM:

• Para ver y ejecutar canalizaciones, haz lo siguiente:
  • Visualizador de Dataform (roles/dataform.Viewer) en el proyecto
  • Usuario de trabajo de BigQuery (roles/bigquery.jobUser) en el proyecto
• Para ejecutar canalizaciones con credenciales de usuario de una Cuenta de Google: Editor de datos de BigQuery (roles/bigquery.dataEditor) en el proyecto o en conjuntos de datos específicos de BigQuery
• Para borrar canalizaciones: Administrador de Dataform (roles/dataform.Admin) en la canalización
• Para administrar canalizaciones en las carpetas de los usuarios, haz lo siguiente:
  • Propietario del código (roles/dataform.codeOwner) en la carpeta
  • Editor de código (roles/dataform.codeEditor) en la carpeta
  • Visualizador de código (roles/dataform.codeViewer) en la carpeta
• Para administrar canalizaciones en carpetas de equipo, haz lo siguiente:
  • Propietario de la carpeta de equipo (roles/dataform.teamFolderOwner) en la carpeta de equipo
  • Colaborador de carpetas de equipo (roles/dataform.teamFolderContributor) en la carpeta de equipo
  • Visualizador de carpetas de equipo (roles/dataform.teamFolderViewer) en la carpeta de equipo
• Para administrar canalizaciones en repositorios de Git: Usuario de OAuth de Developer Connect (roles/developerconnect.oauthUser) en el proyecto
• Para ver y administrar metadatos en Knowledge Catalog: Editor de Dataplex Catalog (roles/dataplex.catalogEditor) en el proyecto o el grupo de entradas de @bigquery
• Para ver el linaje de datos de las canalizaciones: Visualizador de linaje de datos (roles/datalineage.viewer) en el proyecto
• Para abrir canalizaciones desde el gráfico de linaje: Visualizador de Dataform (roles/dataform.viewer) en el proyecto que contiene la canalización

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Para obtener más información sobre la IAM de Dataform, consulta Controla el acceso con la IAM. Para obtener más información sobre los roles de las carpetas, consulta Crea y administra carpetas. Para obtener más información sobre los roles de los repositorios de Git, consulta Administra código con repositorios de Git de BigQuery Studio.

Nota: Cuando creas una canalización, BigQuery te otorga el rol de administrador de Dataform (roles/dataform.admin) en esa canalización. Todos los usuarios con el rol de administrador de Dataform otorgado en el proyecto de Google Cloud tienen acceso de propietario a todas las canalizaciones creadas en el proyecto.

Si usas una cuenta de servicio personalizada para ejecutar canalizaciones, debes otorgarle los siguientes roles:

• Usuario de trabajo de BigQuery (roles/bigquery.jobUser) en el proyecto
• Editor de datos de BigQuery (roles/bigquery.dataEditor) en el proyecto o en conjuntos de datos específicos de BigQuery
• Editor del catálogo de Dataplex (roles/dataplex.catalogEditor) en el proyecto o grupo de entradas @bigquery
• Productor de eventos de linaje de datos (roles/datalineage.producer) en el proyecto que contiene la canalización para informar el linaje de datos

Visualiza canalizaciones

Puedes ver y, también, inspeccionar las canalizaciones almacenadas en carpetas o carpetas de Git en el panel Archivos. Puedes ver las canalizaciones independientes y las almacenadas en carpetas en el panel Explorador. Las canalizaciones almacenadas en carpetas de Git no se muestran en el panel Explorador.

Visualiza canalizaciones en el panel Archivos

Las canalizaciones almacenadas en carpetas o en carpetas de Git aparecen directamente en el panel Archivos.

Para ver una canalización almacenada en una carpeta o una carpeta de Git, sigue estos pasos:

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

   Ir a BigQuery

2. En el panel izquierdo, haz clic en Archivos para abrir el navegador de archivos.

   Si no ves el panel izquierdo, haz clic en Expandir panel izquierdo para abrirlo.

3. Expande tu carpeta Usuario, una carpeta de equipo o una carpeta de repositorio de Git conectada.

   Las canalizaciones se muestran con un ícono de Canalización en lugar de un ícono de carpeta estándar.

4. Haz clic en una carpeta de canalización para abrir el Visualizador de canalizaciones.

   El Visualizador de canalizaciones muestra el grafo acíclico dirigido (DAG) compilado de las tareas de tu canalización, el estado de ejecución y las pestañas de configuración.

5. Expande el directorio de la canalización en el navegador de archivos para explorar los directorios anidados (como definitions/) y los archivos de tareas individuales.

Nota: Si un repositorio de Git conectado contiene workflow_settings.yaml en su directorio raíz, BigQuery Studio lo reconoce como una canalización de nivel raíz. La carpeta del repositorio de Git muestra el ícono de Canalización. Cuando haces clic en la carpeta del repositorio de Git, se abre el Visualizador de canalizaciones, que muestra el DAG compilado para todo el repositorio.

Visualiza canalizaciones en el panel Explorador

Para ver una lista de las canalizaciones independientes y las almacenadas en carpetas, haz lo siguiente:

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

   Ir a BigQuery

2. En el panel de la izquierda, haz clic en Explorar.

   

   Si no ves el panel izquierdo, haz clic en Expandir panel izquierdo para abrirlo.

3. En el panel Explorador, expande tu proyecto y haz clic en Canalizaciones.

4. Selecciona una canalización para abrirla en el Visualizador de canalizaciones.

Ver ejecuciones manuales anteriores

Para ver las ejecuciones manuales anteriores de una canalización seleccionada, sigue estos pasos:

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

   Ir a BigQuery

2. En el panel de la izquierda, haz clic en Explorar.

   

3. En el panel Explorador, expande tu proyecto, haz clic en Canalizaciones y, luego, selecciona una canalización.

4. Haz clic en Ejecuciones.

5. Opcional: Para actualizar la lista de ejecuciones anteriores, haz clic en Actualizar.

Configura alertas para las ejecuciones de canalizaciones con errores

Cada canalización tiene un ID de repositorio de Dataform correspondiente. Cada ejecución de canalización de BigQuery se registra en Cloud Logging con el ID del repositorio de Dataform correspondiente. Puedes usar Cloud Monitoring para observar las tendencias en los registros de Cloud Logging de las ejecuciones de canalizaciones de BigQuery y recibir notificaciones cuando se cumplan las condiciones que describas.

Para recibir alertas cuando falla una ejecución de canalización de BigQuery, puedes crear una política de alertas basada en registros para el ID del repositorio de Dataform correspondiente. Para obtener instrucciones, consulta Configura alertas para invocaciones de flujos de trabajo con errores.

Para encontrar el ID del repositorio de Dataform de tu canalización, haz lo siguiente:

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

   Ir a BigQuery

2. En el panel de la izquierda, haz clic en Explorar.

   

3. En el panel Explorador, expande tu proyecto, haz clic en Canalizaciones y, luego, selecciona una canalización.

4. Haz clic en Configuración.

   El ID del repositorio de Dataform de tu canalización se muestra en la parte inferior de la pestaña Configuración.

Borra una canalización

Para borrar una canalización de forma permanente, sigue estos pasos:

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

• Para borrar una canalización almacenada en una carpeta o una carpeta de Git, haz lo siguiente:

  1. En el panel izquierdo, haz clic en Archivos.

  2. En el árbol de archivos, busca la carpeta de la canalización que quieres borrar.

  3. Haz clic en Ver acciones junto a la carpeta de la canalización y, luego, en Borrar.

  4. En el diálogo de confirmación, haz clic en Borrar.

     La carpeta de la canalización y todas las tareas y los archivos que contiene se borran de tu espacio de trabajo.

• Para borrar una canalización que aparece en el panel Explorador, haz lo siguiente:

  1. En el panel de la izquierda, haz clic en Explorar.

     

  2. En el panel Explorador, expande tu proyecto y haz clic en Canalizaciones.

  3. Busca la canalización que quieres borrar.

  4. Haz clic en Ver acciones junto a la canalización y, luego, en Borrar.

  5. Haz clic en Borrar.

Administrar metadatos en Knowledge Catalog

Knowledge Catalog te permite almacenar y administrar metadatos para las canalizaciones. Las canalizaciones están disponibles en Knowledge Catalog de forma predeterminada, sin configuración adicional.

Puedes usar Knowledge Catalog para administrar canalizaciones en todas las ubicaciones de canalizaciones. La administración de canalizaciones en Knowledge Catalog está sujeta a las cuotas y los límites de Knowledge Catalog y a los precios de Knowledge Catalog.

Knowledge Catalog recupera automáticamente los siguientes metadatos de las canalizaciones:

• Nombre del recurso de datos
• Recurso de datos superior
• Ubicación del recurso de datos
• Tipo de recurso de datos
• Proyecto de Google Cloud correspondiente

Knowledge Catalog registra las canalizaciones como entradas con los siguientes valores de entrada:

Grupo de entradas del sistema

El grupo de entradas del sistema para las canalizaciones es @dataform. Para ver los detalles de las entradas de canalización en Knowledge Catalog, debes ver el grupo de entradas del sistema dataform. Para obtener instrucciones sobre cómo ver una lista de todas las entradas de un grupo de entradas, consulta Visualiza los detalles de un grupo de entradas en la documentación de Knowledge Catalog.

Tipo de entrada del sistema

El tipo de entrada del sistema para las canalizaciones es dataform-code-asset. Para ver los detalles de las canalizaciones, debes ver el tipo de entrada del sistema dataform-code-asset, filtrar los resultados con un filtro basado en aspectos y establecer el campo type dentro del aspecto dataform-code-asset en WORKFLOW. Luego, selecciona una entrada de la canalización elegida. Para obtener instrucciones sobre cómo ver los detalles de un tipo de entrada seleccionado, consulta Cómo ver los detalles de un tipo de entrada en la documentación de Knowledge Catalog. Para obtener instrucciones sobre cómo ver los detalles de una entrada seleccionada, consulta Visualiza los detalles de una entrada en la documentación de Knowledge Catalog.

Tipo de aspecto del sistema

El tipo de aspecto del sistema para las canalizaciones es dataform-code-asset. Para proporcionar contexto adicional a las canalizaciones en Knowledge Catalog anotando las entradas de canalización de datos con aspectos, consulta el tipo de aspecto dataform-code-asset, filtra los resultados con un filtro basado en aspectos y establece el campo type dentro del aspecto dataform-code-asset en WORKFLOW. Para obtener instrucciones sobre cómo anotar entradas con aspectos, consulta Administra aspectos y enriquece metadatos en la documentación de Knowledge Catalog.

Tipo

El tipo de lienzo de datos es WORKFLOW. Este tipo te permite filtrar canalizaciones en el tipo de entrada del sistema dataform-code-asset y el tipo de aspecto dataform-code-asset con la consulta aspect:dataplex-types.global.dataform-code-asset.type=WORKFLOW en un filtro basado en aspectos.

Para obtener instrucciones sobre cómo buscar recursos en Knowledge Catalog, consulta Busca recursos de datos en Knowledge Catalog en la documentación de Knowledge Catalog.

Integración del enriquecimiento de metadatos y el cuadro de evaluación de la calidad de los datos

Dataform puede publicar los siguientes metadatos en Knowledge Catalog:

• Tipo de aspecto de descripción general
• Tipo de aspecto genérico
• Tipo de aspecto del cuadro de evaluación de la calidad de los datos

Las aserciones de Dataform se integran automáticamente en el cuadro de evaluación de la calidad de los datos de Knowledge Catalog. Durante la ejecución de la canalización, los resultados de cualquier aserción de Dataform se publican automáticamente en Knowledge Catalog. Estos resultados propagan el cuadro de evaluación de la calidad de los datos de Knowledge Catalog con un estado de aprobación o falla.

Nota: Cada ejecución reemplaza los cuadros de evaluación de calidad de los datos existentes publicados por ejecuciones anteriores de Dataform, pero no afecta los cuadros de evaluación creados por los análisis de datos de Knowledge Catalog.

Para verificar el estado de una actualización de metadatos, sigue las instrucciones que se indican en Visualiza ejecuciones manuales anteriores.

Después de que se hayan sincronizado los metadatos, puedes buscar y ver la entrada en Knowledge Catalog. Para obtener más información, consulta Busca recursos.

Realizar un seguimiento de linaje de datos

BigQuery informa el linaje de datos a nivel de la tabla a Knowledge Catalog para las acciones que se ejecutan en tu canalización de BigQuery. Para cada acción ejecutada, el gráfico de linaje en BigQuery y Knowledge Catalog muestra un proceso entre las tablas que lee la acción y la tabla en la que escribe. No es necesario que cambies tus archivos SQLX para informar el linaje.

Las tablas, las vistas, las tablas incrementales, las vistas materializadas, las aserciones, los grafos de propiedades, las preparaciones de datos y las operaciones con hasOutput: true informan el linaje de tabla a tabla. Las operaciones sin hasOutput: true solo informan el proceso y la ejecución. Las declaraciones, los notebooks y las pruebas de unidades de SQL no informan el linaje. Las declaraciones aparecen solo como entradas para otras acciones.

Informar el linaje nunca hace que falle una ejecución de canalización. Si la API de Data Lineage está inhabilitada, falta un permiso o se supera una cuota, la ejecución de la canalización continúa sin informar el linaje.

La transferencia del linaje de datos se factura con el SKU de procesamiento premium de Knowledge Catalog, y solo se facturan los eventos que escriben vínculos de linaje de tabla a tabla. El almacenamiento del linaje de datos se factura con el SKU de almacenamiento de metadatos. Para obtener más información, consulta los precios de Knowledge Catalog.

Limitaciones del linaje de datos

El linaje de datos para las canalizaciones está sujeto a las siguientes limitaciones:

• Solo se informa el linaje a nivel de tabla. No se informa el linaje a nivel de columna.

• Los informes de linaje de datos están sujetos a las cuotas de la API de Data Lineage para las escrituras por proyecto, identidad y región.

Habilita el linaje de datos

Nota: Durante el período de lanzamiento inicial, los informes de linaje de datos son de habilitación voluntaria.

Para habilitar el linaje de datos en tu canalización, sigue estos pasos:

1. Habilita la API de Data Lineage (datalineage.googleapis.com) en el proyecto que contiene la canalización y en el proyecto en el que los usuarios ven el linaje.

2. En el proyecto que contiene la canalización, otorga el rol de productor de eventos de linaje de datos (roles/datalineage.producer) a la identidad que ejecuta la canalización. Esta identidad es la cuenta de servicio personalizada de la canalización o el agente de servicio de Dataform (service-PROJECT_NUMBER@gcp-sa-dataform.) si no se establece una cuenta de servicio personalizada.

3. En el archivo workflow_settings.yaml de tu canalización, agrega el siguiente bloque lineage:

   lineage:
     enabled: true
   

Las ejecuciones de canalización que usan credenciales de usuario final para una Cuenta de Google no informan el linaje. Para informar el linaje, ejecuta la canalización con una cuenta de servicio personalizada.

Para detener los informes de linaje de datos de una canalización, establece enabled en false en el bloque lineage. Para detener los informes de linaje de datos de un proyecto completo, inhabilita la API de Data Lineage en el proyecto. Inhabilitar la API también detiene los informes de linaje de datos de otros servicios del proyecto.

Visualiza el linaje de datos

Para ver el linaje de datos de una tabla que produce una acción de canalización, sigue estos pasos:

1. En la consola de Google Cloud , ve a BigQuery Studio.

   Ir a BigQuery Studio

2. En el panel Explorador, expande tu proyecto y conjunto de datos y, luego, selecciona una tabla que produzca una acción de canalización.

3. Haz clic en la pestaña Linaje.

4. Para ver la acción, la canalización y las ejecuciones, selecciona el nodo del proceso.

5. Para abrir la canalización, haz clic en Abrir en Dataform.

Para obtener más información sobre cómo navegar por los gráficos de linaje, consulta Visualiza el linaje de datos en Knowledge Catalog.

Soluciona problemas del linaje de datos

En la siguiente tabla, se describen los problemas comunes de linaje de datos para las canalizaciones y cómo solucionarlos:

Síntoma	Causa probable	Corregir
La pestaña Linaje no muestra los nodos de proceso de la canalización.	La API de Data Lineage está inhabilitada.	Habilita la API en el proyecto que contiene la canalización y en el proyecto en el que ves el linaje.
Una canalización no informa el linaje.	La identidad que ejecuta la canalización no tiene el rol de productor de eventos de linaje de datos.	Otorga roles/datalineage.producer a la cuenta de servicio personalizada o al agente de servicio de Dataform.
Las ejecuciones de canalización que usan credenciales de usuario final no informan el linaje.	Los informes de linaje no admiten credenciales de usuario final.	Ejecuta la canalización con una cuenta de servicio personalizada.
Una canalización no informa el linaje, aunque se otorgue el rol.	Dataform no puede actuar como la cuenta de servicio personalizada.	Otorga al agente de servicio de Dataform el rol de creador de tokens de cuenta de servicio (roles/iam.serviceAccountTokenCreator) en la cuenta de servicio personalizada.
Una canalización no informa el linaje.	Se inhabilitó la canalización.	Quita lineage.enabled: false de workflow_settings.yaml.
Falta el linaje de algunas ejecuciones.	Se superó la cuota de la API de Data Lineage.	Distribuye las ejecuciones de canalización o solicita una cuota más alta.
Si haces clic en Abrir en Dataform, se muestra un error de permiso.	El usuario no tiene acceso a la canalización.	Otorga al usuario el rol de visualizador de Dataform (roles/dataform.viewer).

Después del primer error de permiso o de API en una ejecución de canalización, BigQuery deja de informar el linaje para el resto de esa ejecución. La próxima ejecución de la canalización intenta volver a informar el linaje.

Para verificar si una ejecución de canalización informó el linaje, consulta las entradas de registro de dataform.googleapis.com/lineage_emission en Cloud Logging. Para filtrar los informes de linaje omitidos o con errores en el Explorador de registros, ejecuta la siguiente consulta:

log_id("dataform.googleapis.com/lineage_emission")
jsonPayload.outcome=("SKIPPED" OR "FAILED")

¿Qué sigue?

• Obtén más información sobre las canalizaciones de BigQuery.
• Obtén más información para crear canalizaciones.
• Obtén información para programar canalizaciones.
• Aprende a administrar código con repositorios de Git de BigQuery Studio.
• Obtén más información para organizar los recursos de código con carpetas.
• Obtén más información sobre las implementaciones de Dataform.