Melihat silsilah data untuk sistem Google Cloud

Lihat silsilah data untuk memahami hubungan antara resource project Anda dan proses yang membuatnya. Hubungan ini menunjukkan bagaimana aset data, seperti tabel dan set data, diubah oleh proses seperti kueri dan pipeline. Panduan ini menjelaskan cara melihat detail silsilah data di konsol Google Cloud atau mengambilnya menggunakan Data Lineage API.

Peran dan izin

Silsilah data melacak informasi silsilah secara otomatis saat Anda mengaktifkan Data Lineage API. Anda tidak memerlukan peran administrator atau editor untuk merekam silsilah aset data Anda.

Untuk melihat silsilah data, Anda memerlukan izin Identity and Access Management (IAM) tertentu. Informasi silsilah dicatat di seluruh project, sehingga Anda memerlukan izin di beberapa project.

  • Saat melihat silsilah di Knowledge Catalog, BigQuery, atau Vertex AI: Anda memerlukan izin untuk melihat informasi silsilah di project tempat Anda melihatnya.

  • Saat melihat silsilah yang direkam dalam project lain: Anda memerlukan izin untuk melihat informasi silsilah dalam project tempat silsilah tersebut direkam.

Untuk mendapatkan izin yang Anda perlukan untuk melihat silsilah data, minta administrator untuk memberi Anda peran IAM berikut:

  • Viewer Silsilah Data (roles/datalineage.viewer) pada project tempat silsilah dicatat, dan project tempat silsilah dilihat
  • Melihat detail tabel BigQuery: BigQuery Data Viewer (roles/bigquery.dataViewer) pada project penyimpanan tabel
  • Melihat detail tugas BigQuery: BigQuery Resource Viewer (roles/bigquery.resourceViewer) di project komputasi tugas
  • Melihat detail aset yang dikatalogkan lainnya: Pelihat Katalog Dataplex (roles/dataplex.catalogViewer) pada project tempat entri katalog disimpan

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran bawaan ini berisi izin yang diperlukan untuk melihat silsilah data. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk melihat asal data:

  • Lihat detail tabel BigQuery: bigquery.tables.get - project penyimpanan tabel
  • Melihat detail tugas BigQuery: bigquery.jobs.get - project komputasi tugas

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Jenis tampilan silsilah data

Anda dapat melihat informasi silsilah sebagai grafik interaktif atau daftar terstruktur di konsol Google Cloud .

Untuk deskripsi mendetail tentang elemen grafik (seperti node, tepi, ikon proses, dan label) serta kolom yang tersedia di tampilan daftar, lihat Tentang visualisasi silsilah data di Knowledge Catalog.

Mengaktifkan silsilah data

Aktifkan silsilah data untuk mulai melacak informasi silsilah secara otomatis untuk sistem yang didukung. Secara default, mengaktifkan API akan mengaktifkan pelacakan asal untuk sebagian besar layanan yang didukung. Untuk mengontrol penyerapan silsilah Managed Service untuk Apache Spark, lihat Mengontrol penyerapan silsilah untuk layanan.

Anda harus mengaktifkan Data Lineage API di project tempat Anda melihat silsilah dan project tempat silsilah dicatat. Untuk mengetahui informasi selengkapnya, lihat Jenis project.

  1. Untuk merekam informasi silsilah, selesaikan langkah-langkah berikut:

    1. Di konsol Google Cloud , di halaman Project selector, pilih project tempat Anda ingin merekam silsilah.

      Buka Pemilih project

    2. Aktifkan Data Lineage API.

      Aktifkan API

    3. Ulangi langkah-langkah sebelumnya untuk setiap project yang ingin Anda rekam silsilahnya.

  2. Di project tempat Anda melihat silsilah, aktifkan Data Lineage API dan Dataplex API.

    Aktifkan API

Mengontrol penyerapan silsilah untuk layanan

Anda dapat mengaktifkan atau menonaktifkan pelacakan silsilah otomatis secara selektif untuk layanan tertentu di tingkat project, folder, atau organisasi.

Untuk mengetahui detail tentang cara penerapan konfigurasi ini secara hierarkis melalui hierarki resource, lihat Mengontrol penyerapan silsilah.

Melihat silsilah

Untuk melacak cara data ditransformasi dan berpindah di seluruh sistem, Anda dapat melihat silsilah data menggunakan konsol Google Cloud atau API.

Konsol

Anda dapat mengakses informasi silsilah data di konsol Google Cloud dari berbagai titik awal:

  • Knowledge Catalog: Buka halaman Penelusuran Knowledge Catalog, pilih Knowledge Catalog sebagai mode penelusuran, telusuri entri yang ingin Anda lihat, lalu klik entri tersebut. Untuk mengetahui informasi selengkapnya, lihat Menelusuri resource di Knowledge Catalog.
  • BigQuery: Buka halaman BigQuery dan buka tabel yang silsilah datanya ingin Anda lihat.
  • Vertex AI: Buka halaman Datasets atau Model Registry, lalu klik set data atau model yang ingin Anda lihat asal-usul datanya.

Untuk melihat grafik silsilah, ikuti langkah-langkah berikut:

  1. Klik tab Silsilah.

    Tampilan Grafik default akan terbuka, yang menampilkan silsilah tingkat tabel di seluruh sistem dan region. Untuk mengetahui informasi selengkapnya, lihat Tampilan grafik silsilah.

  2. Untuk menjelajahi grafik silsilah secara manual, klik Luaskan di samping node untuk memuat lima node lagi sekaligus.

    Untuk mengetahui informasi selengkapnya, lihat Menjelajahi grafik silsilah secara manual.

  3. Klik node dalam tampilan Graph.

    Panel Detail akan terbuka dengan informasi tentang aset, seperti nama dan jenis yang sepenuhnya memenuhi syarat. Untuk mengetahui informasi selengkapnya, lihat Detail node.

  4. Klik tepi dengan ikon proses di tampilan Grafik.

    Panel Query akan terbuka. Untuk mengetahui informasi selengkapnya, lihat Memeriksa logika transformasi dan Audit dan histori proses.

    • Untuk memeriksa logika transformasi, klik tab Detail.
    • Untuk melihat audit dan histori operasi, klik tab Operasi.

  5. Di panel Lineage explorer, pilih kriteria filter—misalnya, Arah, Jenis dependensi, atau Rentang waktu—lalu klik Terapkan.

    Tindakan ini akan membuka tampilan fokus dalam wilayah tertentu (Pratinjau). Tampilan ini secara otomatis meluaskan grafik hingga tiga tingkat node. Untuk mengetahui informasi selengkapnya, lihat Menerapkan filter untuk tampilan silsilah yang terfokus.

  6. Dalam tampilan Grafik yang difokuskan, pilih sebuah node, lalu di panel detail node, klik Visualisasikan Jalur untuk memvisualisasikan jalur silsilah dari node yang dipilih kembali ke entri root (hanya dalam tampilan yang difokuskan).

    Untuk mengetahui informasi selengkapnya, lihat Visualisasi jalur silsilah.

  7. Untuk melihat silsilah tingkat kolom (hanya untuk tugas BigQuery dan Managed Service untuk Apache Spark), lakukan salah satu hal berikut:

    • Dalam tampilan Grafik yang difokuskan, klik ikon kolom pada tabel.
      Ikon yang digunakan untuk beralih ke silsilah tingkat kolom.
      Ikon kolom
    • Di panel Lineage explorer, filter menurut nama kolom, lalu klik Terapkan.

    Untuk mengetahui informasi selengkapnya, lihat Silsilah tingkat kolom.

  8. Klik Reset.

    Tindakan ini akan menghapus semua filter yang diterapkan dan membawa Anda ke awal tampilan grafik.

  9. Klik Daftar untuk beralih ke tampilan daftar.

    Tampilan Daftar menawarkan representasi tabular silsilah yang disederhanakan dan mendetail untuk silsilah tingkat tabel dan tingkat kolom, yang disinkronkan dengan tampilan Grafik. Secara default, tampilan daftar yang disederhanakan ditampilkan, dan Anda dapat beralih ke tampilan daftar detail untuk menganalisis hubungan sumber-target individual. Anda dapat mengonfigurasi kolom yang ditampilkan dan mengekspor data silsilah. Untuk mengetahui informasi selengkapnya, lihat Tampilan daftar silsilah.

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}")

Memperbaiki visualisasi silsilah

Untuk menyempurnakan visualisasi silsilah, Anda dapat menggunakan opsi penyorotan dan pemfilteran di Penjelajah silsilah:

  1. Untuk menelusuri project, set data, atau nama entitas tertentu, gunakan panel Filter.

    Setelah Anda menerapkan filter, node silsilah yang cocok dengan kriteria filter Anda dianggap sebagai node yang cocok. Anda dapat menyempurnakan cara node yang cocok dan tidak cocok ditampilkan.

  2. Dalam grafik silsilah, klik ikon Tindakan lainnya yang ada di samping tombol Hapus filter untuk melihat opsi tampilan.

  3. Pilih salah satu atau kedua opsi berikut:

Opsi penyorotan dan pemfilteran di penjelajah silsilah.
Opsi penyorotan dan pemfilteran.

Anda dapat memilih kedua opsi secara bersamaan. Jika kedua opsi dipilih, node yang tidak difilter akan disembunyikan, dan node yang cocok akan ditandai dalam tampilan grafik yang difilter.

Langkah berikutnya