Visualiza el linaje de datos para comprender las relaciones entre los recursos de tu proyecto y los procesos que los crearon. Estas relaciones muestran cómo los procesos, como las consultas y las canalizaciones, transforman los activos de datos, como las tablas y los conjuntos de datos. En esta guía, se describe cómo ver los detalles del linaje de datos en la Google Cloud consola de o recuperarlos con la API de Data Lineage.
Funciones y permisos
El linaje de datos realiza un seguimiento de la información de linaje automáticamente cuando habilitas la API de Data Lineage. No necesitas ninguna función de administrador ni de editor para capturar el linaje de tus activos de datos.
Para ver el linaje de datos, necesitas permisos específicos de Identity and Access Management (IAM). La información de linaje se captura en todos los proyectos, por lo que necesitas permisos en varios proyectos.
Cuando ves el linaje en Knowledge Catalog, BigQuery o Vertex AI, necesitas permisos para ver la información de linaje en el proyecto en el que lo estás viendo.
Cuando ves el linaje que se registró en otros proyectos, necesitas permisos para ver la información de linaje en esos proyectos en los que se registró.
Para obtener los permisos que necesitas para ver el linaje de datos, pídele a tu administrador que te otorgue los siguientes roles de IAM:
- Visualizador de linaje de datos (
roles/datalineage.viewer) en el proyecto en el que se registra el linaje y en el que se ve -
Ver detalles de la tabla de BigQuery:
Visualizador de datos de BigQuery (
roles/bigquery.dataViewer) en el proyecto de almacenamiento de la tabla -
Ver detalles del trabajo de BigQuery:
Visualizador de recursos de BigQuery (
roles/bigquery.resourceViewer) en el proyecto de procesamiento del trabajo -
Ver detalles de otros activos catalogados:
Visualizador de Data Catalog de Dataplex (
roles/dataplex.catalogViewer) en el proyecto en el que se almacenan las entradas de catálogo
Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.
Estos roles predefinidos contienen los permisos necesarios para ver el linaje de datos. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:
Permisos necesarios
Se requieren los siguientes permisos para ver el linaje de datos:
-
Ver detalles de la tabla de BigQuery:
bigquery.tables.get(el proyecto de almacenamiento de la tabla) -
Ver detalles del trabajo de BigQuery:
bigquery.jobs.get(el proyecto de procesamiento del trabajo)
También puedes obtener estos permisos con roles personalizados o otros roles predefinidos.
Tipos de vistas de linaje de datos
Puedes ver la información de linaje como un gráfico interactivo o una lista estructurada en la Google Cloud consola.
Para obtener una descripción detallada de los elementos del gráfico (como nodos, bordes, íconos de proceso y etiquetas) y las columnas disponibles en las vistas de lista, consulta Acerca de la visualización del linaje de datos en Knowledge Catalog.
Habilita el linaje de datos
Habilita el linaje de datos para comenzar a hacer un seguimiento automático de la información de linaje para los sistemas compatibles. De forma predeterminada, habilitar la API activa el seguimiento de linaje para la mayoría de los servicios compatibles. Para controlar la ingesta de linaje de Managed Service para Apache Spark, consulta Controla la ingesta de linaje para un servicio.
Debes habilitar la API de Data Lineage en el proyecto en el que ves el linaje y en los proyectos en los que se registra. Para obtener más información, consulta Tipos de proyectos.
- Para capturar información de linaje, completa los siguientes pasos:
-
En la Google Cloud consola de, en la página del Selector de proyectos, selecciona el proyecto en el que deseas registrar el linaje.
Habilita la API de Data Lineage.
- Repite los pasos anteriores para cada proyecto en el que deseas registrar el linaje.
-
En el proyecto en el que ves el linaje, habilita la API de Data Lineage y la API de Dataplex.
Controla la ingesta de linaje para un servicio
Puedes habilitar o inhabilitar de forma selectiva el seguimiento automático de linaje para servicios específicos a nivel de proyecto, carpeta o organización.
Para obtener detalles sobre cómo se aplican estas configuraciones de forma jerárquica a través del árbol de recursos, consulta Controla la ingesta de linaje.
Ver linaje
Para hacer un seguimiento de cómo se transforman y mueven los datos en los sistemas, puedes ver el linaje de datos con la Google Cloud consola de o la API.
Console
Puedes acceder a la información de linaje de datos en la Google Cloud consola de desde varios puntos de partida:
- Knowledge Catalog: Ve a la página Búsqueda de Knowledge Catalog, selecciona Knowledge Catalog como el modo de búsqueda, busca la entrada que deseas ver y, luego, haz clic en ella. Para obtener más información, consulta Busca recursos en Knowledge Catalog.
- BigQuery: Ve a la página de BigQuery y abre la tabla para la que deseas ver el linaje de datos.
- Vertex AI: Ve a la página Conjuntos de datos o Model Registry y haz clic en el conjunto de datos o el modelo para el que deseas ver el linaje de datos.
Para ver el gráfico de linaje, sigue estos pasos:
Haz clic en la pestaña Linaje.
Se abre la vista Gráfico predeterminada, que muestra el linaje a nivel de la tabla en todos los sistemas y regiones. Para obtener más información, consulta Vista de gráfico de linaje.
Para explorar manualmente el gráfico de linaje, haz clic en Expandir junto a un nodo para cargar cinco nodos más a la vez.
Para obtener más información, consulta Explora manualmente el gráfico de linaje.
Haz clic en un nodo en la vista Gráfico.
Se abre el panel Detalles con información sobre el activo, como el nombre y el tipo completamente calificados. Para obtener más información, consulta Detalles del nodo.
Haz clic en un borde con un ícono de proceso en la vista Gráfico.
Se abre el panel Consulta. Para obtener más información, consulta Inspecciona la lógica de transformación y Auditoría e historial de ejecuciones.
- Para inspeccionar la lógica de transformación, haz clic en la pestaña Detalles.
- Para ver la auditoría y el historial de ejecuciones, haz clic en la pestaña Ejecuciones.
En el panel Explorador de linaje, selecciona los criterios de filtro (por ejemplo, Dirección, Tipo de dependencia o Intervalo de tiempo) y, luego, haz clic en Aplicar.
Se abre una vista enfocada dentro de una región específica (vista previa). Esta vista expande automáticamente el gráfico hasta tres niveles de nodos. Para obtener más información, consulta Aplica filtros para una vista de linaje enfocada.
En la vista Gráfico enfocada, selecciona un nodo y, luego, en el panel de detalles del nodo, haz clic en Visualizar ruta para visualizar la ruta de linaje desde el nodo seleccionado hasta la entrada raíz (solo en la vista enfocada).
Para obtener más información, consulta Visualización de rutas de linaje.
Para ver el linaje a nivel de la columna (solo para trabajos de BigQuery y Managed Service para Apache Spark), haz una de las siguientes acciones:
- En una vista Gráfico enfocada, haz clic en el ícono de columna en una tabla.
Ícono de columna - En el panel Explorador de linaje , filtra por nombre de columna y haz clic en Aplicar.
Para obtener más información, consulta Linaje a nivel de la columna.
- En una vista Gráfico enfocada, haz clic en el ícono de columna en una tabla.
Haz clic en Restablecer.
Esta acción quita todos los filtros aplicados y te lleva al comienzo de la vista de gráfico.
Haz clic en Lista para cambiar a la vista de lista.
La vista Lista ofrece representaciones tabulares simplificadas y detalladas del linaje para el linaje a nivel de la tabla y de la columna, sincronizadas con la vista Gráfico. De forma predeterminada, se muestra la vista de lista simplificada, y puedes alternar a la vista de lista detallada para analizar las relaciones individuales de origen y destino. Puedes configurar qué columnas se muestran y exportar datos de linaje. Para obtener más información, consulta Vista de lista de linaje.
Java
import com.google.api.gax.rpc.ApiException;
import com.google.cloud.datacatalog.lineage.v1.BatchSearchLinkProcessesRequest;
import com.google.cloud.datacatalog.lineage.v1.EntityReference;
import com.google.cloud.datacatalog.lineage.v1.EventLink;
import com.google.cloud.datacatalog.lineage.v1.LineageClient;
import com.google.cloud.datacatalog.lineage.v1.LineageEvent;
import com.google.cloud.datacatalog.lineage.v1.Link;
import com.google.cloud.datacatalog.lineage.v1.ListLineageEventsRequest;
import com.google.cloud.datacatalog.lineage.v1.ListRunsRequest;
import com.google.cloud.datacatalog.lineage.v1.LocationName;
import com.google.cloud.datacatalog.lineage.v1.ProcessLinks;
import com.google.cloud.datacatalog.lineage.v1.Run;
import com.google.cloud.datacatalog.lineage.v1.SearchLinksRequest;
import java.io.IOException;
import java.util.ArrayList;
import java.util.HashSet;
import java.util.LinkedList;
import java.util.List;
import java.util.Queue;
import java.util.Set;
public class ViewLineageExample {
public static void main(String[] args) throws IOException {
// TODO(developer): Replace these variables before running the sample.
String projectId = "my-project-id";
String location = "us";
String targetFullyQualifiedName = "bigquery:my-project-id.my_dataset.my_table";
int maxDepth = 3;
viewLineage(projectId, location, targetFullyQualifiedName, maxDepth);
}
static class Node {
String fqn;
int depth;
Node(String fqn, int depth) {
this.fqn = fqn;
this.depth = depth;
}
}
public static void viewLineage(
String projectId, String location, String targetFullyQualifiedName, int maxDepth)
throws IOException {
// Initialize client that will be used to send requests. This client only needs
// to be created once, and can be reused for multiple requests.
try (LineageClient client = LineageClient.create()) {
String parent = LocationName.of(projectId, location).toString();
Set<String> visitedNodes = new HashSet<>();
Queue<Node> queue = new LinkedList<>();
visitedNodes.add(targetFullyQualifiedName);
queue.offer(new Node(targetFullyQualifiedName, 0));
while (!queue.isEmpty()) {
Node current = queue.poll();
System.out.printf("\nExploring node (Depth %d): %s\n", current.depth, current.fqn);
if (current.depth >= maxDepth) {
continue;
}
EntityReference targetEntity =
EntityReference.newBuilder().setFullyQualifiedName(current.fqn).build();
SearchLinksRequest searchLinksRequest =
SearchLinksRequest.newBuilder().setParent(parent).setTarget(targetEntity).build();
List<String> linkNames = new ArrayList<>();
try {
// 1. Search for links related to the target entity
for (Link link : client.searchLinks(searchLinksRequest).iterateAll()) {
linkNames.add(link.getName());
}
} catch (ApiException e) {
System.out.printf(" Failed to retrieve links for %s: %s\n", current.fqn, e.getMessage());
continue;
}
if (linkNames.isEmpty()) {
continue;
}
// 2. Batch search for processes in chunks of 100
for (int i = 0; i < linkNames.size(); i += 100) {
List<String> batch = linkNames.subList(i, Math.min(linkNames.size(), i + 100));
BatchSearchLinkProcessesRequest batchSearchRequest =
BatchSearchLinkProcessesRequest.newBuilder()
.setParent(parent)
.addAllLinks(batch)
.build();
try {
for (ProcessLinks processLinks :
client.batchSearchLinkProcesses(batchSearchRequest).iterateAll()) {
String processName = processLinks.getProcess();
System.out.printf(" Process: %s\n", processName);
// 3. List runs for the process
ListRunsRequest runsRequest =
ListRunsRequest.newBuilder().setParent(processName).build();
for (Run run : client.listRuns(runsRequest).iterateAll()) {
System.out.printf(" Run: %s\n", run.getName());
// 4. List events for the run
ListLineageEventsRequest eventsRequest =
ListLineageEventsRequest.newBuilder().setParent(run.getName()).build();
for (LineageEvent event : client.listLineageEvents(eventsRequest).iterateAll()) {
for (EventLink eventLink : event.getLinksList()) {
String sourceFqn = eventLink.getSource().getFullyQualifiedName();
// If exploring upstream, queue the source
if (!sourceFqn.isEmpty() && !visitedNodes.contains(sourceFqn)) {
visitedNodes.add(sourceFqn);
queue.offer(new Node(sourceFqn, current.depth + 1));
}
}
}
}
}
} catch (ApiException e) {
System.out.printf(" Failed to retrieve processes/runs: %s\n", e.getMessage());
}
}
}
}
}
}
Python
from google.cloud import datacatalog_lineage_v1
from google.api_core.exceptions import GoogleAPICallError
def view_lineage(project_id: str, location: str, target_fully_qualified_name: str, max_depth: int = 3):
"""Retrieves lineage for a given entity using a depth-limited search."""
client = datacatalog_lineage_v1.LineageClient()
parent = f"projects/{project_id}/locations/{location}"
# Store visited nodes to avoid infinite loops in cyclic graphs
visited_nodes = set([target_fully_qualified_name])
queue = [(target_fully_qualified_name, 0)]
while queue:
current_node, current_depth = queue.pop(0)
print(f"\nExploring node (Depth {current_depth}): {current_node}")
if current_depth >= max_depth:
continue
target_entity = datacatalog_lineage_v1.EntityReference(
fully_qualified_name=current_node
)
search_links_request = datacatalog_lineage_v1.SearchLinksRequest(
parent=parent,
target=target_entity,
)
try:
links = list(client.search_links(request=search_links_request))
except GoogleAPICallError as e:
print(f" Failed to retrieve links for {current_node}: {e.message}")
continue
if not links:
continue
# Extract link names to query processes in batches
link_names = [link.name for link in links]
# Batch max size is 100
for i in range(0, len(link_names), 100):
batch = link_names[i:i + 100]
batch_request = datacatalog_lineage_v1.BatchSearchLinkProcessesRequest(
parent=parent,
links=batch
)
try:
for process_links in client.batch_search_link_processes(request=batch_request):
process_name = process_links.process
print(f" Process: {process_name}")
runs_request = datacatalog_lineage_v1.ListRunsRequest(parent=process_name)
for run in client.list_runs(request=runs_request):
print(f" Run: {run.name}")
events_request = datacatalog_lineage_v1.ListLineageEventsRequest(parent=run.name)
for event in client.list_lineage_events(request=events_request):
for event_link in event.links:
source_fqn = event_link.source.fully_qualified_name
# If exploring upstream, queue the source
if source_fqn and source_fqn not in visited_nodes:
visited_nodes.add(source_fqn)
queue.append((source_fqn, current_depth + 1))
except GoogleAPICallError as e:
print(f" Failed to retrieve processes/runs: {e.message}")
Refina la visualización del linaje
Para refinar la visualización del linaje, puedes usar las opciones de resaltado y filtrado en Explorador de linaje:
Para buscar proyectos, conjuntos de datos o nombres de entidades específicos, usa el panel Filtros.
Después de aplicar los filtros, los nodos de linaje que coinciden con tus criterios de filtro se consideran nodos coincidentes. Puedes refinar la forma en que se muestran los nodos coincidentes y no coincidentes.
En el gráfico de linaje, haz clic en el Más acciones ícono ubicado junto al botón Borrar filtros para ver las opciones de visualización.
Selecciona una o ambas de las siguientes opciones:
Puedes seleccionar ambas opciones al mismo tiempo. Si se seleccionan ambas opciones, se ocultan los nodos sin filtrar y se resaltan los nodos coincidentes en la vista de gráfico filtrada.
¿Qué sigue?
- Realiza un seguimiento del linaje de datos de los trabajos de copia y consulta de una tabla de BigQuery.
- Obtén información sobre el modelo de información de linaje de datos.
- Obtén información sobre las consideraciones y limitaciones del linaje de datos.
- Obtén información sobre el registro de auditoría del linaje de datos.
- Obtén información para solucionar problemas relacionados con el linaje de datos.
- Obtén información para realizar la integración en OpenLineage.
- Obtén información para usar el linaje de datos con Managed Service para Apache Spark.