Search syntax for Knowledge Catalog

This document describes the syntax for Knowledge Catalog search.

Knowledge Catalog lets you discover, centrally catalog, manage, and understand your organization's data. To efficiently find specific data assets within your data catalog, you can use powerful search queries. The syntax for search queries includes:

  • Simple search: How to find data assets using a single search term.
  • Qualified predicates: How to refine your search using specific metadata fields like name, location, or description.
  • Aspect search: How to search for entries based on their attached business and technical metadata.
  • Logical operators: How to combine multiple search criteria using AND and OR to create complex queries. By understanding this syntax, you can quickly locate the data you need.

Before you begin

Understand Knowledge Catalog entry groups, entries, entry links, aspects, entry types, entry link types, and aspect types. See About metadata management in Knowledge Catalog.

Knowledge Catalog offers search that leverages AI to understand natural language queries and semantic meaning. It lets you find resources using everyday language, eliminating the need for complex syntax, while also supporting keyword matching and filters.

Use free-text search

You can find assets by entering a term or phrase without any specific syntax. Knowledge Catalog performs a broad search by matching your query against several metadata fields, including the following:

  • Name, display name, or description of a resource
  • Type of a resource
  • Project ID
  • Overview description
  • Column name (or nested column name) in the schema of a resource
  • Column description
  • Fully qualified name
  • Contacts
  • Aspects

Use query syntax

For more precise searches, you can construct a query using specific syntax, including qualifiers, logical operators, and aspect searches.

Qualified predicates

You can qualify a predicate by prefixing it with a key that restricts the matching to a specific piece of metadata:

  • An equal sign (=) restricts the search to an exact match.
  • A colon (:) after the key matches the predicate to either a substring or a token within the value in the search results.

Tokenization splits the stream of text into a series of tokens, with each token usually corresponding to a single word.

For example:

  • name:foo selects resources with names that contain the foo substring, such as foo1 and barfoo.
  • description:foo selects resources with the foo token in the description, such as bar and foo.
  • location=foo matches resources in a specified location with foo as the location name.

The behavior of these qualifiers can vary slightly between search modes, as detailed in the following sections.

The predicate keys type, system, location, and description, and aspect search (excluding has) support only the exact match (=) qualifier, not the substring qualifier (:). For example, type=foo.

Knowledge Catalog search supports the following qualifiers:

Qualifier Description
name:x Matches x as a substring of the resource ID or resource display name.
displayname:x Match x as a substring of the resource display name.
column:x Matches x as a substring of the column name (or nested column name) in the schema of the resource.
description:x Matches x as a token in the resource description.
labels:bar Matches BigQuery resources that have a label (with some value) and the label key has bar as a substring.
labels=bar Matches BigQuery resources that have a label (with some value) and the label key equals bar as a string.
labels.bar:x Matches x as a substring in the value of a label with key bar attached to a BigQuery resource.
labels.foo=bar Matches BigQuery resources where the key equals foo and the key value equals bar.
type=TYPE Matches resources of a specific entry type or its type alias.
projectid:bar Matches resources within Google Cloud projects that match bar as a substring in the ID.
parent:x Matches x as a substring of the hierarchical path of a resource.
system=SYSTEM Matches resources from a specified system.
location=LOCATION

Matches resources in a specified location with an exact name. For example, location=us-central1 matches assets hosted in Iowa.

BigQuery Omni assets support this qualifier by using the BigQuery Omni location name. For example, location=aws-us-east-1 matches BigQuery Omni assets in Northern Virginia.

createtime

Finds resources that were created within, before, or after a given date or time.

For example:

  • createtime:2019-01-01 matches all resources created on 2019-01-01.
  • createtime<2019-02 matches all resources created before 2019-02-01T00:00:00.
  • createtime>2019-02 matches all resources created after 2019-02-01T00:00:00.
  • createtime>-30d matches all resources created in the last 30 days.
  • createtime<=-30d matches all resources created 30 days ago or earlier.
  • createtime<=-1d matches all resources created on the previous day.

Timestamp format: YYYY-MM-DDThh:mm:ss

All timestamps must be in GMT; time zones are not supported. Partial timestamps, hyphen (-) date separators, and slash (/) date separators are supported.

For example:

  • 2010-10-22T05:36:24