As of April 10, 2026, Dataplex Universal Catalog is now called Knowledge Catalog. The API, client library, CLI, and IAM names remain unchanged. For more information, see Introducing the Google Cloud Knowledge Catalog.

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` `2010-10-22T05:36` `2010-10-22T05` `2010-10-22` `2010-10` `2010` `2010/10/22`
`updatetime`	Finds resources that were updated within, before, or after a given date or time. For example: `updatetime:2019-01-01` matches all resources updated on 2019-01-01. `updatetime<2019-02` matches all resources updated before 2019-02-01T00:00:00. `updatetime>2019-02` matches all resources updated after 2019-02-01T00:00:00. `updatetime>-30d` matches all resources updated in the last 30 days. `updatetime<-30d` matches all resources updated 30 days ago or earlier. `updatetime=-1d` matches all resources updated on the previous day. `updatetime>=-30d` matches all resources updated in the last 30 days. `updatetime<=-30d` matches all resources updated 30 days ago or earlier. 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` `2010-10-22T05:36` `2010-10-22T05` `2010-10-22` `2010-10` `2010` `2010/10/22`

Aspect search

You can use query syntax to search for entries based on their attached aspects.

The substring match tries to match against a limited number of aspects. If you can't find the entry by using a fragment of the path, then use the full path to narrow the search and increase recall.

Qualifier Description

aspect:x
or
has:x Matches x as a substring of the full path to the aspect type of an aspect that is attached to the entry, in the format projectid.location.ASPECT_TYPE_ID

aspect=x
or
has=x Matches x as the full path to the aspect type of an aspect that is attached to the entry, in the format projectid.location.ASPECT_TYPE_ID

Qualifier	Description
`aspect:x` or `has:x`	Matches `x` as a substring of the full path to the aspect type of an aspect that is attached to the entry, in the format `projectid.location.ASPECT_TYPE_ID`
`aspect=x` or `has=x`	Matches `x` as the full path to the aspect type of an aspect that is attached to the entry, in the format `projectid.location.ASPECT_TYPE_ID`
`x OPERATOR value`	Searches for aspect field values. Matches `x` as a substring of the full path to the aspect type and field name of an aspect that is attached to the entry, in the following formats: Syntax for system aspect types: `ASPECT_TYPE_ID.FIELD_NAME` `dataplex-types.ASPECT_TYPE_ID.FIELD_NAME` `dataplex-types.LOCATION.ASPECT_TYPE_ID.FIELD_NAME` For example, the following queries match entries where the value of the `type` field in the `bigquery-dataset` aspect is `default`: `bigquery-dataset.type=default` `dataplex-types.bigquery-dataset.type=default` `dataplex-types.global.bigquery-dataset.type=default` Syntax for custom aspect types: If the aspect is created in the global region: `PROJECT_ID.ASPECT_TYPE_ID.FIELD_NAME` If the aspect is created in a specific region: `PROJECT_ID.REGION.ASPECT_TYPE_ID.FIELD_NAME` For example, the following queries match entries where the value of the `is-enrolled` field in the `employee-info` aspect is `true`. `example-project.us-central1.employee-info.is-enrolled=true` `example-project.employee-info.is-enrolled=true` The list of supported operators depends on the type of field in the aspect, as follows: String: `=` (exact match) All number types: `=`, `:`, `<`, `>`, `<=`, `>=`, `=>`, `=<` Enum: `=` Datetime: same as for numbers, but the values to compare are treated as datetimes instead of numbers Boolean: `=` Only top-level fields of the aspect are searchable.

x
OPERATOR
value

Searches for aspect field values. Matches x as a substring of the full path to the aspect type and field name of an aspect that is attached to the entry, in the following formats:

Syntax for system aspect types:
- ASPECT_TYPE_ID.FIELD_NAME
- dataplex-types.ASPECT_TYPE_ID.FIELD_NAME
- dataplex-types.LOCATION.ASPECT_TYPE_ID.FIELD_NAME
For example, the following queries match entries where the value of the type field in the bigquery-dataset aspect is default:
- bigquery-dataset.type=default
- dataplex-types.bigquery-dataset.type=default
- dataplex-types.global.bigquery-dataset.type=default
Syntax for custom aspect types:
- If the aspect is created in the global region: PROJECT_ID.ASPECT_TYPE_ID.FIELD_NAME
- If the aspect is created in a specific region: PROJECT_ID.REGION.ASPECT_TYPE_ID.FIELD_NAME
For example, the following queries match entries where the value of the is-enrolled field in the employee-info aspect is true.
- example-project.us-central1.employee-info.is-enrolled=true
- example-project.employee-info.is-enrolled=true
The list of supported operators depends on the type of field in the aspect, as follows:
- String: = (exact match)
- All number types: =, :, <, >, <=, >=, =>, =<
- Enum: =
- Datetime: same as for numbers, but the values to compare are treated as datetimes instead of numbers
- Boolean: =

Only top-level fields of the aspect are searchable.

Logical operators

A query can consist of several predicates with logical operators.

If you don't specify an operator, logical AND is implied. For example, foo bar returns resources that match both predicate foo and predicate bar.
Logical AND and logical OR are supported. For example, foo OR bar.
You can negate a predicate with a - (hyphen) or NOT prefix. For example, -name:foo returns resources with names that don't match the predicate foo.

Abbreviated syntax

An abbreviated search syntax is also available, using | (vertical bar) for OR operators and , (comma) for AND operators.

For example, to search for entries inside one of many projects using the OR operator, you can use the following abbreviated syntax:

projectid:(id1|id2|id3|id4)

The same search without using abbreviated syntax looks like the following:

projectid:id1 OR projectid:id2 OR projectid:id3 OR projectid:id4

To search for entries with matching column names, use the following:

AND: column:(name1,name2,name3)
OR: column:(name1|name2|name3)

This abbreviated syntax works for the qualified predicates except for label in keyword search.

Keyword-only search

Knowledge Catalog provides keyword-only search mode for backward compatibility, with the standard search mode supporting both semantic and keyword matching. We recommend using the standard search mode, unless keyword-only search is required for backward compatibility.

The following table summarizes the key differences in qualifiers that you must consider when using keyword-only search.

Qualifier	Key differences
`name:x`	Matches `x` as a substring of the resource ID only.
`label` qualifiers	Uses the `label` prefix instead of `labels`. Supported syntax formats include: `label:bar` `label=bar` `label:bar:x` `label=foo:bar` `label.foo=bar` `label.foo`
`orgid=number`	Matches resources within a Google Cloud organization with the exact ID value of `number`, supported only in keyword-only search.
`fully_qualified_name`	Supports `fully_qualified_name:x` (substring match) and `fully_qualified_name=x` (exact match) (supported only in keyword-only search).
`createtime` and `updatetime`	Supports only exact date (`:`) and basic comparison (`<`, `>`) operators. Doesn't support relative time filters (such as `-30d` or `-1d`) or comparison operators such as `<=`, `>=`, `=`, `=>`, `=<`.
Exact match restriction	The predicate keys `type`, `system`, `location`, and `orgid` support only exact match (`=`), not substring match (`:`).

Aspect search for keyword-only search

The following table summarizes the key differences in aspect search that you must consider when using keyword-only search.

Aspect search element	Key differences
Qualifier prefix	Supports `aspect:` and `aspect=`. Doesn't support `has:` or `has=`.
Aspect field value search syntax	Requires the `aspect:` prefix when searching for aspect field values (format: `aspect:x OPERATOR value`, such as `aspect:employee-info.is-enrolled=true` or `aspect:employee=true`).
String field operators	String fields support both exact match (`=`) and substring match (`:`).
System aspect type shorthands	Doesn't support system aspect type shorthands, such as `ASPECT_TYPE_ID.FIELD_NAME` or `dataplex-types...`).

What's next

Learn how to search for resources in Knowledge Catalog
Learn more about metadata management in Knowledge Catalog.
Learn how to enrich entries and entry links with metadata by using aspects.
Learn how to manage entries and ingest custom sources.