Search for resources

Use universal catalog search to find Google Cloud resources from within BigQuery, such as BigQuery datasets and tables.

Universal catalog search supports natural language search queries (also known as semantic search queries), which let you search for resources using everyday language.

Similar to keyword search, natural language search emphasizes the discovery of resources by analyzing the metadata that's associated with the resources within your organization. Search takes into account a broad range of metadata that describes the resources, including metadata that you create.

Natural language search focuses on enhancing recall rather than precision.

For more information about how to search for table data in BigQuery, see Introduction to search in BigQuery.

Sign up for Preview

To sign up for Preview, your Google account representative must submit a request by filling out the sign-up form. After you submit the form, the BigQuery team will contact you with next steps.

Before you begin

Before you use natural language search in BigQuery to search for Google Cloud resources, complete the tasks in this section.

Required roles

To search for resources, you need at least one of the universal catalog (Dataplex Catalog) IAM roles on the project that is used for search. Permissions on search results are checked independently of the selected project.

The search results in BigQuery are scoped according to your IAM permissions over the underlying resources. To search for a resource in BigQuery, you must have permissions to access the corresponding resource. 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 to access those resources. 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.

The BigQuery Metadata Viewer role (roles/bigquery.metadataViewer) includes both the permissions bigquery.tables.get and bigquery.datasets.get, and it lets you search for any BigQuery resource.

For more information about granting roles, see Manage access.

You might also be able to get the required permissions through custom roles or other predefined roles.

Enable the API

To use search, ensure that you have enabled the Dataplex API. The Dataplex API is automatically enabled for all new Google Cloud projects with BigQuery. If the Dataplex API isn't enabled in your project, see Enable Dataplex.

  1. In the Google Cloud console, go to the BigQuery Search page.

    Go to Search

  2. In the search field, enter your query in natural language and then press Enter. The following are some sample queries:

    • Show me the datasets that contain taxi information
    • Find data on vaccine distribution across different countries
    • Get tables with historical temperature data for major world cities
    • Search for hurricane tracking and storm activity datasets
    • Population data by country

  3. To filter your search, click Filters. The following filters are available:

    • Scope: search across the organization (default), the current project, or only for starred resources. For more information, see the Search scope section of this document.
    • Systems: the Google Cloud service that the resource belongs to, such as BigQuery. The Dataplex system contains universal catalog entry groups.
    • Projects: the projects to search in.
    • Type: the resource type, such as BigQuery connection, Cloud Storage bucket, or database. Depending on the resource type, you can also filter by subtype, such as the connection type or SQL dialect.
    • Select locations: the locations to search in.
    • Select datasets: this limits search results to BigQuery resources that belong to the selected BigQuery datasets. In the Type to filter field, enter the name of the dataset.
    • Annotations: the universal catalog aspect types that are associated with the resource that you're searching for. To filter by aspect values, click Filter on annotation values, and then select the values.

    To remove a filter, click Clear next to the specific filter that you want to remove. Or, to remove all filters, click Clear Filters.

    For more information about how filters are evaluated, see the Filters section of this document.

  4. Optional: To view more information about a resource, in the search results, click the resource name.

    This opens a resource summary in a split pane. Do any of the following:

    • To open the resource in the service that the resource belongs to, click Open in PRODUCT_NAME for the resource. For example, to open a BigQuery dataset in BigQuery Studio, click Open in Studio. The options that are available depend on the resource.
    • To view the universal catalog metadata that's associated with a resource, click Open in Dataplex Catalog for the resource.
    • If you have important search results that you want to bookmark, you can star them. Click Star for the resource. You can view starred resources in BigQuery Studio.
    • To close the resource summary in the split pane, click Close.

Filters

Filters let you narrow down the search results.

When you provide filters in multiple sections, the filters are evaluated using the AND logical operator. The search results contain resources that match at least one condition from every selected section. For example, if you select the BigQuery system and the dataset resource type, the search results include BigQuery datasets but not Vertex AI datasets.

If you select multiple filters within a single section, the filters are evaluated using the OR logical operator. For example, if you select the dataset resource type and the table resource type, the search results include both datasets and tables.

Search scope

For projects that belong to a Google Cloud organization, search operates within the scope of that organization.

The search results respect permissions that you have over the resources. For example, if you have BigQuery metadata read access to a resource, that resource appears in your search results. If you have access to a BigQuery table but not to the dataset containing that table, the table still shows up as expected in the search results.

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.

What's next