How to search with Data Catalog

This document explains how you can use Data Catalog to perform a search of data assets, such as datasets, tables, views, and Cloud Pub/Sub topics in your Google Cloud projects.

Search scope

Search results may be different for users with different permissions. Data Catalog search results are scoped according to the user's IAM role and permissions. If a user has BigQuery metadata read access to an object, that object will appear in their Data Catalog search results.

For example, 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 that dataset. The BigQuery Metadata Viewer role (roles/bigquery.metadataViewer) includes the minimum required metadata read permissions for a dataset, table, or view to appear in search results.

How to Search for data assets


  1. You can perform a search for data assets from the Data Catalog home page in the Google Cloud Console. You can also makes selections from the Data Assets and Search Tips panels to filter your search.

  2. When you click Search or make a selection from the Data Assets and Search Tips panels on the Data Catalog home page, the Search page opens. If you made a Data Asset or Search Tip selection on the home page, it will be carried over to the Type panel or search box expression in order to qualify your search.

  3. You can click a data asset Type in the left panel to filter your search to a particular data asset type.

    Example: To list any "trips" datasets in your project, click Dataset type, enter "trips" in the search box, then click Search.

  4. You can filter your search by adding a keyword:value to your search terms in the search box:

    name: Match data asset name
    column: Match column name
    description: Match table description

  5. You can perform a tag search by adding one of the following tag keyword prefixes to your search terms in the search box:

    tag:project-name.tag_template_name Match tag name
    tag.project-name.tag_template_name.key Match an tag key
    tag.project-name.tag_template_name.key:value Match tag key:string value pair


"""This application demonstrates how to perform search operations with the
Cloud Data Catalog API.

For more information, see the under /datacatalog and the
documentation at

import argparse

def search(organization_id, search_string):
    """Searches Data Catalog entries for a given organization."""
    from import datacatalog_v1

    datacatalog = datacatalog_v1.DataCatalogClient()

    scope = datacatalog_v1.types.SearchCatalogRequest.Scope()

    # Alternatively, search using project scopes.
    # scope.include_project_ids.append("my_project_id")

    return datacatalog.search_catalog(

if __name__ == '__main__':
    parser = argparse.ArgumentParser(

                        help='Your Google Cloud organization ID')
    parser.add_argument('query', help='Your custom query')

    args = parser.parse_args()

    search_results = None

    if args.query:
        search_results = search(args.organization_id, args.query)
        raise Exception('Please provide valid search input.')

    for result in search_results:


This application demonstrates how to perform search operations with the
Cloud Data Catalog API.

For more information, see the under /datacatalog and the
documentation at

package com.example.datacatalog;


public class SearchCatalog {

  public static void searchCatalog() {
    // TODO(developer): Replace these variables before running the sample.
    String orgId = "111111000000";
    String query = "type=dataset";
    searchCatalog(orgId, query);

   * Search Data Catalog entries for a given organization.
   * @param orgId The organization ID to which the search will be scoped, e.g. '111111000000'.
   * @param query The query, e.g. 'type:dataset'.
  public static void searchCatalog(String orgId, String query) {
    // Create a scope object setting search boundaries to the given organization.
    Scope scope = Scope.newBuilder().addIncludeOrgIds(orgId).build();

    // Alternatively, search using project scopes.
    // Scope scope = Scope.newBuilder().addAllIncludeProjectIds("my-project").build();

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (DataCatalogClient dataCatalogClient = DataCatalogClient.create()) {

      // Search the catalog.
      SearchCatalogRequest searchCatalogRequest =
      SearchCatalogPagedResponse response = dataCatalogClient.searchCatalog(searchCatalogRequest);

      System.out.println("Search results:");
      for (SearchCatalogResult result : response.iterateAll()) {

    } catch (Exception e) {
      System.out.print("Error during SearchCatalog:\n" + e.toString());


// This application demonstrates how to perform search operations with the
// Cloud Data Catalog API.

async function search() {

  // -------------------------------
  // Import required modules.
  // -------------------------------
  const { DataCatalogClient } = require('@google-cloud/datacatalog').v1;
  const datacatalog = new DataCatalogClient();

  // -------------------------------
  // Set your Google Cloud Organization ID.
  // -------------------------------
  // TODO: Replace your organization ID in the next line.
  const organizationId = 111111000000;

  // -------------------------------
  // Set your custom query.
  // -------------------------------
  // TODO: If applicable, edit the query string in the next line.
  const query = 'type=dataset'

  // Create request.
  const scope = {
    includeOrgIds: [organizationId],
    // Alternatively, search using project scopes.
    // includeProjectIds: ['my-project'],

  const request = {
    scope: scope,
    query: query,

  const [result] = await datacatalog.searchCatalog(request);
  return result;

search().then(response => { console.log(response) });


If you do not have access to Cloud Client libraries for your language or want to test the API using REST requests, see the following examples and refer to the Data Catalog REST API documentation.

1. Search catalog.

Before using any of the request data below, make the following replacements:

HTTP method and URL:


Request JSON body:


To send your request, expand one of these options:

You should receive a JSON response similar to the following: