Search for resources in Knowledge Catalog

Knowledge Catalog (formerly Dataplex Universal Catalog) search lets you discover resources across your organization with support of natural language search with semantic matching, keyword search, and an extensive search syntax.

Use cases

The following list describes common search use cases, along with descriptions and example queries:

• Targeted asset lookup: Find a specific asset by searching for keywords related to the asset name, columns, or description.

  Example queries

  • retail_transactions_2026
  • customer_id
  • column:customer_id

• Broad data discovery: Identify relevant assets across your organization using open-ended natural language or keyword queries.

  Example queries

  • quarterly financial reports
  • ad campaign click through rates tables
  • server health metrics
  • audit logs system=bigquery

• Scoped asset retrieval for workflows: Enumerate assets within a specific container, such as a project, or with specific properties, such as type or system. This approach is frequently used for programmatic and agentic workflows.

  Example queries

  • type=table projectid:banking-prod aspect:classification.tier=PII
  • system=spanner projectid:inventory-service (parent=marketing_analytics OR parent=finance_analytics)

Access search in Knowledge Catalog

You have the following options to access search in Knowledge Catalog:

• Through the Search page in Google Cloud console. For more information, see the Search for resources section in this document.
• gcloud dataplex entries search gcloud CLI.
• searchEntries API and Cloud Client Libraries.
• Remote MCP server and MCP Toolbox for Databases for interactive usage and to power your agentic and programmatic workloads.

How it works

Search automatically indexes all context for data assets maintained in Knowledge Catalog. This includes the following:

• Metadata automatically ingested from Google Cloud data sources such as BigQuery and Cloud SQL
• Context for resources you ingest through connectors and integrations
• Additional context you create for resources (for example representing business context or describing data semantics) and captured in the form of aspects or linked business terms.

When processing your query, search applies a combination of semantic and keyword matching. The following table describes the query types you can use with Knowledge Catalog search along with descriptions and sample queries:

Search scope

The search results in Knowledge Catalog respect permissions that you have over the corresponding resources in source systems.

For example, if you have BigQuery metadata read access to an object, that object appears in your Knowledge Catalog search results. If you have access to a BigQuery table but not to the dataset containing that table, the table still appears as expected in the Knowledge Catalog search.

By default, search is scoped to your organization. Results include only resources from the same organization as the project you're searching in.

The search results include only those resources that belong to the same VPC Service Controls perimeter as the project under which search is performed. When using the Google Cloud console, this is the project that is selected in the console.

To broaden the scope of your search results beyond the resources within your project's VPC Service Controls perimeter, use VPC Service Controls ingress and egress rules. These rules facilitate private and efficient data exchange across your organization. You can configure ingress and egress rules using the Google Cloud console or through JSON or YAML files. Refer to the following YAML example and consult the VPC Service Controls documentation to tailor the rule to your specific requirements.

egressPolicies:
  - egressFrom:
      identityType: ANY_USER_ACCOUNT
    egressTo:
      # Specify which resources should be present in the search results. In this example,
      # BigQuery.
      operations:
      - methodSelectors:
        - method: '*'
        serviceName: bigquery.googleapis.com
      # Specify project ids under which the search is performed.
      resources:
      - projects/SEARCH_PROJECT_ID
ingressPolicies:
  - ingressFrom:
      identityType: ANY_USER_ACCOUNT
      sources:
      - accessLevel: '*'
    ingressTo:
      # Specify which resources should be present in the search results. In this example,
      # BigQuery.
      operations:
      - methodSelectors:
        - method: '*'
        serviceName: bigquery.googleapis.com
      # Specify project ids to expose in search results.
      resources:
      - projects/INGRESS_PROJECT_ID

For more information about the Identity and Access Management roles that you need to use Knowledge Catalog search, see Knowledge Catalog IAM roles.

Isolate search results by environment using VPC Service Controls

To isolate Knowledge Catalog search results between environments like development, test, and production, configure separate VPC Service Controls perimeters for each environment. Assign both the projects that contain the data assets and the projects that are used for performing searches to the corresponding environment's perimeter. Searches that are performed from a project within a specific perimeter will only return results for assets that are also located within that same perimeter.

Recall limitations in search

Knowledge Catalog search queries don't guarantee full recall, which means that the search might not return results that match your query. Additionally, returned (and not returned) results might vary if you repeat search queries.

To query all Knowledge Catalog metadata, you can export the metadata to Cloud Storage and then query it from BigQuery. For more information, see Export metadata.

Before you begin

Before you perform search, ensure that you are granted the required roles and have enabled the necessary API.

Required roles

To get the permissions that you need to search for entries and access search results in Knowledge Catalog, ask your administrator to grant you the following IAM roles:

• Search for entries:
  • Dataplex Catalog Admin (roles/dataplex.catalogAdmin) on the project used for search
  • Dataplex Catalog Editor (roles/dataplex.catalogEditor) on the project used for search
  • Dataplex Catalog Viewer (roles/dataplex.catalogViewer) on the project used for search
• Search for metadata for BigQuery datasets and tables: BigQuery Metadata Viewer (roles/bigquery.metadataViewer) on the dataset or table
• Search for custom entries: Dataplex Catalog Viewer (roles/dataplex.catalogViewer) on the project

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.

Permissions on search results are checked independently of the selected project.

The search results in Knowledge Catalog are scoped according to your role. To search for an asset in Knowledge Catalog, you must have permissions to access the corresponding resource in the source system. For more information, see the Search scope section of this document.

For example, to search for BigQuery datasets, tables, views, and models, you need respective permissions for those entries. For more information, see BigQuery permissions.

The following list describes the minimum permissions required:

• To search for a table, you need bigquery.tables.get permission for that table.
• To search for a dataset, you need bigquery.datasets.get permission for that dataset.

As another example, to search for Cloud SQL instances, databases, schemas, tables, and views, you need respective permissions on those entries. For more information, see Cloud SQL roles and permissions.

Enable the API

Enable the Dataplex API.

Enable the API

Search for resources

gcloud dataplex entries search 'foo' \
  --project=PROJECT_ID \
  --semantic-search

using Google.Api.Gax;
using Google.Api.Gax.ResourceNames;
using Google.Cloud.Dataplex.V1;
using System;

public sealed partial class GeneratedCatalogServiceClientSnippets
{
    /// <summary>Snippet for SearchEntries</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void SearchEntriesRequestObject()
    {
        // Create client
        CatalogServiceClient catalogServiceClient = CatalogServiceClient.Create();
        // Initialize request argument(s)
        SearchEntriesRequest request = new SearchEntriesRequest
        {
            LocationName = LocationName.FromProjectLocation("[PROJECT]", "[LOCATION]"),
            Query = "",
            OrderBy = "",
            Scope = "",
            SemanticSearch = false,
        };
        // Make the request
        PagedEnumerable<SearchEntriesResponse, SearchEntriesResult> response = catalogServiceClient.SearchEntries(request);

        // Iterate over all response items, lazily performing RPCs as required
        foreach (SearchEntriesResult item in response)
        {
            // Do something with each item
            Console.WriteLine(item);
        }

        // Or iterate over pages (of server-defined size), performing one RPC per page
        foreach (SearchEntriesResponse page in response.AsRawResponses())
        {
            // Do something with each page of items
            Console.WriteLine("A page of results:");
            foreach (SearchEntriesResult item in page)
            {
                // Do something with each item
                Console.WriteLine(item);
            }
        }

        // Or retrieve a single page of known size (unless it's the final page), performing as many RPCs as required
        int pageSize = 10;
        Page<SearchEntriesResult> singlePage = response.ReadPage(pageSize);