Veja 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 recursos de dados, como tabelas e conjuntos de dados, são transformados por processos como consultas e pipelines. Neste guia, descrevemos como visualizar detalhes da linhagem de dados no console do Google Cloud ou recuperá-los usando a API Data Lineage.
Papéis e permissões
A linhagem de dados rastreia as 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 recursos de dados.
Para visualizar 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 vários projetos. Portanto, você precisa de permissões em vários projetos.
Ao visualizar a linhagem no Knowledge Catalog, no BigQuery ou na Vertex AI: você precisa de permissões para visualizar as informações de linhagem no projeto em que está visualizando.
Ao visualizar a linhagem que foi registrada em outros projetos: você precisa de permissões para visualizar as informações de linhagem nesses projetos em que ela foi registrada.
Para receber as permissões necessárias para visualizar a linhagem de dados, peça ao administrador para conceder a você os seguintes papéis do IAM:
-
Todos:
Leitor da linhagem de dados (
roles/datalineage.viewer) no projeto em que a linhagem é registrada e no projeto em que ela é visualizada -
Acessar detalhes da tabela do BigQuery:
Leitor de metadados do BigQuery (
roles/bigquery.metadataViewer) no projeto de armazenamento da tabela -
Ver detalhes do job do BigQuery:
Leitor de recursos do BigQuery (
roles/bigquery.resourceViewer) no projeto de computação do job -
Ver detalhes de outros recursos catalogados:
Leitor do Dataplex Catalog (
roles/dataplex.catalogViewer) no projeto em que as entradas do catálogo estã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 visualizar a linhagem de dados. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:
Permissões necessárias
As seguintes permissões são necessárias para visualizar a linhagem de dados:
-
Veja os detalhes da tabela do BigQuery:
bigquery.tables.get: o projeto de armazenamento da tabela -
Ver detalhes do job do BigQuery:
bigquery.jobs.get: o projeto de computação do job
Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.
Tipos de visualizações de linhagem de dados
É possível ver as informações de linhagem como um gráfico interativo ou uma lista estruturada no console do Google Cloud .
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 em 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 mais informações, consulte Rastreamento automatizado de linhagem de dados e Sobre o controle de ingestão de linhagem de dados.
A API Data Lineage é faturada de acordo com a 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ê visualiza a linhagem e nos projetos em que ela é registrada. Para mais informações, consulte Tipos de projeto.
- Para capturar informações de linhagem, siga estas etapas:
-
No console do Google Cloud , na página Seletor de projetos, selecione o projeto em que você quer registrar a linhagem.
Ative a API Data Lineage.
- Repita as etapas anteriores para cada projeto em que você quer registrar a linhagem.
-
No projeto em que você visualiza 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 por meio da árvore de recursos, consulte Sobre o controle de ingestão de linhagem de dados.
Ver linhagem
Para acompanhar como os dados são transformados e se movem entre os sistemas, é possível visualizar a linhagem de dados usando o console do Google Cloud ou a API.
Console
É possível acessar as informações de linhagem de dados no console do Google Cloud de vários pontos de partida:
- Knowledge Catalog:acesse a página de Pesquisa do Knowledge Catalog, selecione Knowledge Catalog como o modo de pesquisa, procure a entrada que você quer visualizar e clique nela. Para mais informações, consulte Pesquisar recursos de dados no Knowledge Catalog.
- BigQuery:acesse a página do BigQuery e abra a tabela em que você quer ver a linhagem de dados.
- Vertex AI:acesse a página Conjuntos de dados ou Model Registry e clique no conjunto de dados ou modelo em que você quer ver a linhagem de dados.
Para visualizar o gráfico de linhagem, siga estas etapas:
Clique na guia Linhagem.
A visualização padrão de Gráfico é 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 analisar 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 Analisar o gráfico de linhagem.
Clique em um nó na visualização Gráfico.
O painel Detalhes é aberto com informações sobre o recurso, como nome totalmente qualificado e tipo. Para mais informações, consulte Ver detalhes do nó de linhagem.
Clique em uma borda 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 ver a auditoria e o histórico de execuções, clique na guia Execuções.
No painel Explorador de linhagem, selecione os critérios de filtro, por exemplo, Direção, Tipo de dependência ou Período, e clique em Aplicar.
Isso abre uma visualização focada em uma região específica (pré-lançamento). Essa visualização expande automaticamente o gráfico em até três níveis de nós. Para mais informações, consulte Filtrar e destacar visualizações de linhagem de dados.
Na visualização Gráfico em foco, selecione um nó e, no painel de detalhes do nó, clique em Visualizar caminho para ver o caminho de linhagem do nó selecionado de volta à entrada raiz (somente na visualização em foco).
Para mais informações, consulte Visualizar um caminho de linhagem de dados.
Para conferir a linhagem no nível da coluna (somente para jobs do BigQuery e do Serviço Gerenciado para Apache Spark), siga um destes procedimentos:
- Em uma visualização de gráfico em foco, clique no ícone de coluna em uma tabela.
Ícone de coluna - No painel Análise de linhagem, filtre por nome de coluna e clique em Aplicar.
Para mais informações, consulte Quando usar a linhagem no nível da coluna.
- Em uma visualização de gráfico em foco, 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 de gráfico.
Clique em Lista para mudar para a visualização em lista.
A visualização em lista oferece representações tabulares simplificadas e detalhadas da linhagem no nível da tabela e da coluna, sincronizadas com a visualização em 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 individuais de origem-destino. É 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 da 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 ícone Mais ações 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 forem selecionadas, os nós não filtrados serão ocultados, e os nós correspondentes serão destacados na visualização de gráfico filtrada.
Desativar a linhagem de dados
Para interromper o rastreamento da linhagem e evitar cobranças de linhagem de dados, desative a
API Data Lineage (datalineage.googleapis.com) em cada projeto em que ela estiver
ativada.
Desativar a 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 guias a seguir e conclua as etapas para cada projeto em que o rastreamento de linhagem foi ativado:
Console
No 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 comando gcloud services
disable:
gcloud services disable datalineage.googleapis.com --project=PROJECT_ID
Substitua:
PROJECT_ID: ID do seu projeto do Google Cloud
Se você quiser interromper o rastreamento de linhagem para serviços específicos sem desativar a API completamente, consulte Configurar a ingestão de linhagem de dados para um serviço.
A seguir
- Rastrear a linhagem de dados 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 da API Data Lineage.
- Resolver problemas de linhagem de dados.
- Integrar com o OpenLineage.
- Usar a linhagem de dados com o Serviço Gerenciado para Apache Spark.