Knowledge Catalog discovers potential links between data assets, helping you to discover the related data and understand the nature of the relationship.
Before you begin
Before you view relationships between data assets, ensure that you are granted the required roles and have enabled the necessary API.
Required roles
To get the permissions that you need to view relationships between data assets, ask your administrator to grant you the following IAM roles on your project:
- To view relationships in BigQuery tables and views: BigQuery Metadata Viewer
(
roles/bigquery.metadataViewer)
For more information about granting roles, see Manage access to projects, folders, and organizations .
You might also be able to get the required permissions through custom roles or other predefined roles .
Enable APIs
To use data relationships, enable the following APIs in your project: Dataplex API and BigQuery API.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM
role ( roles/serviceusage.serviceUsageAdmin
), which
contains the serviceusage.services.enable
permission. Learn how to grant
roles
.
About data relationships
Data relationships illustrate how data assets connect. For example, if you locate a table with customer data, its relationships can reveal related tables listing orders or support tickets. Additionally, relationships act as a structural guide, providing essential context to Large Language Models. As a result, AI generates more precise responses, formulating accurate queries to retrieve specific information.
Knowledge Catalog automatically discovers and stores common relationships between the data assets. The relationship data originates from various sources, such as the following:
- Historical query logs Knowledge Catalog that continuously analyze query history to detect potential
JOINpatterns between tables. - Data insights suggest data relationships on demand by analyzing schema attributes and data overlaps using large language models.
Supported data assets
You can view data relationships for BigQuery tables and views.
View data relationships
To view data relationships for BigQuery tables and views, use Google Cloud console or Knowledge Catalog API.
console
To view data relationships for a table in BigQuery, do the following:
-
In the Google Cloud console, go to the Knowledge Catalog Searchpage.
-
Search for a BigQuery table that you want to view relationships for.
-
In the search results, click the table to open its entry page.
The Relationshipstab lists relationships along with the following information:
- Target: The name of the connected data asset.
- Relationship: The specific columns used to link the assets.
- Type:The nature of the link. For example,
JOIN. - Origin:The origin of the relationship. For example, query history.
- Action:A sample query that can be used to discover the link between the assets.
REST
Discovered relationships are stored in Knowledge Catalog as EntryLinks
that establish a relationship between two data assets (entries) in Knowledge Catalog. The details about the relationship, such as the joined columns and the relationship source, are stored as aspects of EntryLinks
.
To view data relationships, use the following methods:
-
LookupEntryLinksretrieves allEntryLinksthat reference a specific data entry as either the source or the target to return the full set of relationships associated with a given entry. -
LookupContextprovides a single endpoint for grounding AI agents with contextual metadata. It returns a concise, pre-formatted package of metadata, including related data assets.
Locations
You can use data relationships in all BigQuery locations .
Limitations
- Automatic discovery of relationships from query logs is available only for BigQuery tables and views.
- Knowledge Catalog analyzes a sample of query history to identify relationships, which means that some queries might not lead to link discovery.
- Relationships discovery might take up to 48 hours after the query is executed.
What's next
- Learn how to use Knowledge Catalog with MCP, Gemini, and other agents .
