Confira a linhagem de dados para entender as relações entre os recursos do projeto e os processos que os criaram. Essas relações mostram como os ativos de dados, como tabelas e conjuntos de dados, são transformados por processos como consultas e pipelines. Este guia descreve como conferir os detalhes da linhagem de dados no Google Cloud console do Google Cloud ou recuperá-los usando a API Data Lineage.
Papéis e permissões
A linhagem de dados rastreia informações de linhagem automaticamente quando você ativa a API Data Lineage. Não é necessário ter papéis de administrador ou editor para capturar a linhagem dos seus ativos de dados.
Para conferir a linhagem de dados, você precisa de permissões específicas do Identity and Access Management (IAM). As informações de linhagem são capturadas em projetos, então você precisa de permissões em vários projetos.
Ao conferir a linhagem no Knowledge Catalog, no BigQuery ou na Vertex AI, você precisa de permissões para conferir as informações de linhagem no projeto em que está conferindo.
Ao conferir a linhagem que foi gravada em outros projetos, você precisa de permissões para conferir as informações de linhagem nos projetos em que ela foi gravada.
Para receber as permissões necessárias para conferir a linhagem de dados, peça ao administrador para conceder a você os seguintes papéis do IAM:
- Leitor da linhagem de dados (
roles/datalineage.viewer) no projeto em que a linhagem é gravada e no projeto em que ela é conferida -
Conferir detalhes da tabela do BigQuery:
Leitor de dados do BigQuery (
roles/bigquery.dataViewer) no projeto de armazenamento da tabela -
Conferir detalhes do job do BigQuery:
Leitor de recursos do BigQuery (
roles/bigquery.resourceViewer) no projeto de computação do job -
Conferir detalhes de outros ativos catalogados:
Leitor do Dataplex Catalog (
roles/dataplex.catalogViewer) no projeto em que as entradas do catálogo são armazenadas
Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.
Esses papéis predefinidos contêm as permissões necessárias para conferir a linhagem de dados. Para acessar as permissões exatas que são necessárias, expanda a seção Permissões necessárias:
Permissões necessárias
As seguintes permissões são necessárias para conferir a linhagem de dados:
-
Conferir detalhes da tabela do BigQuery:
bigquery.tables.get- o projeto de armazenamento da tabela -
Conferir detalhes do job do BigQuery:
bigquery.jobs.get- o projeto de computação do job
Essas permissões também podem ser concedidas com papéis personalizados ou outros papéis predefinidos.
Tipos de visualizações de linhagem de dados
É possível conferir informações de linhagem como um gráfico interativo ou uma lista estruturada no Google Cloud console.
Para uma descrição detalhada dos elementos do gráfico (como nós, arestas, ícones de processo e rótulos) e das colunas disponíveis nas visualizações de lista, consulte Sobre a visualização da linhagem de dados no Knowledge Catalog.
Ativar a linhagem de dados
Ative a linhagem de dados para começar a rastrear automaticamente as informações de linhagem dos sistemas compatíveis. Por padrão, a ativação da API ativa o rastreamento de linhagem para a maioria dos serviços compatíveis. Para controlar a ingestão de linhagem do Serviço Gerenciado para Apache Spark, consulte Controlar a ingestão de linhagem de um serviço.
A API Data Lineage é faturada na SKU de processamento premium do Knowledge Catalog. Para mais informações, consulte Preços do Knowledge Catalog.
É necessário ativar a API Data Lineage no projeto em que você confere a linhagem e nos projetos em que ela é gravada. Para mais informações, consulte Tipos de projetos.
- Para capturar informações de linhagem, siga estas etapas:
-
No Google Cloud console do Google Cloud, na página do Seletor de projetos, selecione o projeto em que você quer gravar a linhagem.
Ative a API Data Lineage.
- Repita as etapas anteriores para cada projeto em que você quer gravar a linhagem.
-
No projeto em que você confere a linhagem, ative a API Data Lineage e a API Dataplex.
Controlar a ingestão de linhagem de um serviço
É possível ativar ou desativar seletivamente o rastreamento automático de linhagem para serviços específicos no nível do projeto, da pasta ou da organização.
Para detalhes sobre como essas configurações são aplicadas hierarquicamente na árvore de recursos, consulte Controlar a ingestão de linhagem.
Ver linhagem
Para rastrear como os dados são transformados e se movem entre sistemas, é possível conferir a linhagem de dados usando o Google Cloud console ou a API.
Console
É possível acessar informações de linhagem de dados no Google Cloud console em vários pontos de partida:
- Knowledge Catalog:acesse a página Pesquisar do Knowledge Catalog, selecione Knowledge Catalog como o modo de pesquisa, pesquise a entrada que você quer conferir e clique nela. Para mais informações, consulte Pesquisar recursos no Knowledge Catalog.
- BigQuery:acesse a página BigQuery e abra a tabela para a qual você quer conferir a linhagem de dados.
- Vertex AI:acesse a página Conjuntos de dados ou Model Registry e clique no conjunto de dados ou modelo para o qual você quer conferir a linhagem de dados.
Para conferir o gráfico de linhagem, siga estas etapas:
Clique na guia Linhagem.
A visualização Gráfico padrão é aberta, mostrando a linhagem no nível da tabela em sistemas e regiões. Para mais informações, consulte Visualização do gráfico de linhagem.
Para explorar manualmente o gráfico de linhagem, clique em Expandir ao lado de um nó para carregar mais cinco nós por vez.
Para mais informações, consulte Explorar manualmente o gráfico de linhagem.
Clique em um nó na visualização Gráfico.
O painel Detalhes é aberto com informações sobre o ativo, como nome totalmente qualificado e tipo. Para mais informações, consulte Detalhes do nó.
Clique em uma aresta com um ícone de processo na visualização Gráfico.
O painel Consulta é aberto. Para mais informações, consulte Inspecionar a lógica de transformação e Auditoria e histórico de execuções.
- Para inspecionar a lógica de transformação, clique na guia Detalhes.
- Para conferir a auditoria e o histórico de execuções, clique na guia Execuções.
No painel Explorador de linhagem, selecione critérios de filtro, por exemplo, Direção, Tipo de dependência ou Intervalo de tempo e clique em Aplicar.
Isso abre uma visualização focada em uma região específica (visualização). Essa visualização expande automaticamente o gráfico em até três níveis de nós. Para mais informações, consulte Aplicar filtros para uma visualização de linhagem focada.
Na visualização Gráfico focada, selecione um nó e, no painel de detalhes do nó, clique em Visualizar caminho para visualizar o caminho de linhagem do nó selecionado de volta à entrada raiz (somente na visualização focada).
Para mais informações, consulte Visualização do caminho de linhagem.
Para conferir a linhagem no nível da coluna (somente para jobs do BigQuery e do Serviço Gerenciado para Apache Spark), faça uma das seguintes ações:
- Em uma visualização Gráfico focada, clique no ícone de coluna em uma tabela.
Ícone de coluna - No painel Explorador de linhagem , filtre por nome da coluna e clique em Aplicar.
Para mais informações, consulte Linhagem no nível da coluna.
- Em uma visualização Gráfico focada, clique no ícone de coluna em uma tabela.
Clique em Redefinir.
Essa ação remove todos os filtros aplicados e leva você ao início da visualização do gráfico.
Clique em Lista para mudar para a visualização em lista.
A visualização Lista oferece representações tabulares simplificadas e detalhadas da linhagem para linhagem no nível da tabela e da coluna, sincronizadas com a visualização Gráfico. Por padrão, a visualização em lista simplificada é exibida, e é possível alternar para a visualização em lista detalhada para analisar relações de origem-destino individuais. É possível configurar quais colunas são exibidas e exportar dados de linhagem. Para mais informações, consulte Visualização em lista de linhagem.
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}")
Refinar a visualização de linhagem
Para refinar a visualização de linhagem, use as opções de destaque e filtragem no Explorador de linhagem:
Para pesquisar projetos, conjuntos de dados ou nomes de entidades específicos, use o painel Filtros.
Depois de aplicar filtros, os nós de linhagem que correspondem aos critérios de filtro são considerados nós correspondentes. É possível refinar como os nós correspondentes e não correspondentes são exibidos.
No gráfico de linhagem, clique no Mais ações ícone localizado ao lado do botão Limpar filtros para conferir as opções de exibição.
Selecione uma ou ambas as opções a seguir:
É possível selecionar as duas opções ao mesmo tempo. Se as duas opções estiverem selecionadas, os nós não filtrados serão ocultos e os nós correspondentes serão destacados na visualização do gráfico filtrado.
Desativar a linhagem de dados
Para interromper o rastreamento de linhagem e evitar cobranças de linhagem de dados, desative a API Data Lineage (datalineage.googleapis.com) em cada projeto em que ela está ativada.
A desativação da API Dataplex não desativa a linhagem de dados nem interrompe as cobranças. É necessário desativar a API Data Lineage.
Para desativar a linhagem de dados, selecione uma das seguintes guias e conclua as etapas para cada projeto em que o rastreamento de linhagem foi ativado:
Console
No Google Cloud console do Google Cloud, acesse a página APIs e serviços ativados.
Na lista de APIs, clique em API Data Lineage.
Clique em Desativar API.
Botão "Desativar API" na página de detalhes da API Data Lineage. Quando solicitado, clique em Desativar.
gcloud
Para desativar a API Data Lineage, use o
gcloud services disable comando:
gcloud services disable datalineage.googleapis.com --project=PROJECT_ID
Substitua:
PROJECT_ID: o ID do Google Cloud projeto
Se você quiser interromper o rastreamento de linhagem para serviços específicos sem desativar a API completamente, consulte Controlar a ingestão de linhagem de um serviço.
A seguir
- Rastrear a linhagem de dados dos jobs de cópia e consulta de uma tabela do BigQuery.
- Saiba mais sobre o modelo de informações de linhagem de dados.
- Saiba mais sobre as considerações e limitações da linhagem de dados.
- Saiba mais sobre a geração de registros de auditoria de linhagem de dados.
- Saiba como resolver problemas de linhagem de dados.
- Saiba como fazer a integração com o OpenLineage.
- Saiba como usar a linhagem de dados com o Serviço Gerenciado para Apache Spark.