Query Syntax

To search for assets, you can filter the search results by specifying a FIELD, an operator, and a QUERY.

Text Exact Match: equals (=) operator

FIELD=QUERY

An example query is: owner=[e-mail].

The equals (=) operator checks that QUERY exactly matches the value of the asset metadata FIELD. It is case sensitive. For a repeated field, if QUERY matches one of the field's values, the asset is considered a match. The supported FIELD names depend on whether the query is a resource search or an Identity and Access Management (IAM) policy search. The QUERY is a phrase, but cannot contain wildcards.

Text Partial Match: has (:) operator

FIELD:QUERY

An example query is: owner:amy.2020@gmail.

When performing a search, the QUERY is compared to the value of the specified assets metadata FIELD. The query and the asset metadata fields are converted to a sequence of words (i.e. tokens) for comparison. This is done by:

• Removing leading/trailing special characters and tokenizing the search value by treating the special characters as delimiters. The tokenization special characters are the characters that are not one of alphanumeric [a-zA-Z0-9], underscore [_] or ampersand [&]
• Performing Unicode case folding so that character casing is ignored

Here are some tokenization examples:

• "[e-mail]" is tokenized to: [amy,2020,gmail,com]
• "google.com/cloud" is tokenized to: [google,com,cloud]
• "Compute %Instance%" is tokenized to: [compute,instance]
• "$%^*-!" is tokenized to: []
• "" is tokenized to: []
• "compute*storage" is tokenized to: [compute,storage]
• "compute&storage" is tokenized to: [compute&storage]
• "[e-mail]" is tokenized to: [bob_test,gmail,com]
• "instance/_my_vm_" is tokenized to: [instance,_my_vm_]

The has (:) operator checks that each word of QUERY exists within the value of the asset metadata field. It also checks the words' order and consecutiveness. The supported FIELD can be different, depending on whether it's a resource search or an IAM policy search. The QUERY can be a phrase or a combination of phrases.

Note: A query can contain multiple comparisons using the format above. See Combination for more information. They're limited to 10 comparisons and 2048 characters. If you have a use case for longer queries, please contact us at [e-mail].

Examples

For example, an asset whose owner field has value "[e-mail]" matches the following queries:

• Matches because the phrase is exactly the same as the field's value.

    owner=[e-mail]
  

• Matches because punctuations are treated as delimiters and case is insensitive.

    owner:[e-mail]
  

• Matches because words in a phrase are matched in order. Note that "amy 2020 gmail" is a phrase; words should be matched in order and consecutively.

    owner:"amy 2020 gmail"
  

• Matches because a combination of words can appear in any order. Note that (gmail 2020 amy) is a combination; words are matched and not necessarily in order.

    owner:(gmail 2020 amy)
  

• Matches because words in the phrase are matched in order and words in the combination appear in any order. Note that "amy 2020" is a phrase and words should be matched in order and consecutively. (gmail "amy 2020") is combination; gmail and "amy 2020" are matched and not necessarily in order.

    owner:(gmail "amy 2020")
  

• Matches because * can be used in a phrase to indicate a prefix match.

    owner:amy-20*
  

An asset whose owner field has value "[e-mail]" does NOT match the following queries:

• Does not match because the phrase is case sensitive. Use the has (:) operator instead for case insensitive match.

    owner=[e-mail]
  

• Does not match because the phrase partially matches the field's value. Use the has (:) operator instead for partial match.

    owner=amy.2020@gmail
  

Numerical Match: comparison (=, >, >=, <, <=) operators

FIELD=QUERY

FIELD>QUERY

FIELD>=QUERY

FIELD<QUERY

FIELD<=QUERY

The comparison operators check that the comparison result between QUERY and the value of the asset metadata FIELD is true.

The supported FIELD names include createTime and updateTime.

For timestamp fields (createTime and updateTime), the QUERY could be a 64-bit signed integer, which represents epoch timestamp in seconds; or a date-time string in one of below formats (timezone is UTC):

• YYYY-MM-DD: 2021-01-01 (quotes are optional)
• "YYYY-MM-DDThh:mm:ss": "2021-01-01T00:00:00" (quotes are required)

Examples

For example, an asset whose createTime field has value 1609459200 (epoch timestamp of 2021-01-01T00:00:00) matches the following queries:

• Equals.

    createTime=1609459200
    createTime=2021-01-01
    createTime="2021-01-01T00:00:00"
  

• Greater than.

    createTime>1500000000
    createTime>2020-01-01
    createTime>"2020-01-01T00:00:00"
  

• Greater than or equals.

    createTime>=1609459200
    createTime>=2021-01-01
    createTime>="2021-01-01T00:00:00"
  

• Less than.

    createTime<1700000000
    createTime<2022-01-01
    createTime<"2022-01-01T00:00:00"
  

• Less than or equals.

    createTime<=1609459200
    createTime<=2021-01-01
    createTime<="2021-01-01T00:00:00"
  

Phrase

A phrase is one or multiple words enclosed in double quotation marks ("). With phrases, the order of the words is important. Words in the phrase must be matching in order and consecutively. Note that to match multiple words without respecting order, you have to use the combination (e.g., field:(word1 word2 word3)).

Note: If the phrase only contains English characters [a-zA-Z], numbers [0-9], basic email/URL connectors [_-+.@/&], and wildcards [*], you don't have to enclose it in double quotation marks. If a quoted phrase contains " or \, you need to escape them as \" or \\. You can also replace " or \ as a single space, since non-alphanumeric characters are treated as delimiters when performing the search.

The following expressions are the same:

owner:amy
owner:"amy"

owner:[e-mail]
owner:"[e-mail]"

name://cloudresourcemanager.googleapis.com/projects/projects/foo-bar
name:"//cloudresourcemanager.googleapis.com/projects/projects/foo-bar"

The following phrases must be enclosed in quotation marks:

name:"my instance"

owner:"[e-mail]"

description:"domain:gmail.com"

description:"hello \"world\""

description:"hello\\world"

Examples: phrase

• Return assets whose owner field has word amy and word 2020 in order and consecutively:

  owner:"amy 2020"
  

• If you have an asset whose owner field value is "[e-mail]", the above query matches.

• If you have an asset whose owner field value is "[e-mail]", the above query does not match, as the words are not matched in order.

• If you have an asset whose owner field value is "[e-mail]", the above query does not match, as the words are not matched consecutively.

Combination

Search phrases can be combined using AND or OR. Parentheses are used to group combinations.

Note: Operators AND and OR must be uppercased. When AND and OR are both used in the query, parentheses must be appropriately used to group the combinations.

Examples: combination

• Return assets whose owner field has both word amy and word john, without respecting the order. AND is optional in a combination. Note that to match multiple words in order, you have to use the phrase (e.g., field:"word1 word2 word3").

  owner:(amy john)
  

  Note: If an asset contains a field with a list of values, e.g. owner=["[e-mail]", "[e-mail]", "[e-mail]"]. Searching with owner:(amy john) matches the asset, as [e-mail] contains word amy, and [e-mail] contains word john. It doesn't guarantee that this field must have a single element (e.g. [e-mail]) containing both word amy and word john.

• Return assets whose owner field has either word amy or word john.

  owner:(amy OR john)
  

• Return assets whose owner field has both word amy and word john or has word bob.

  owner:((amy john) OR bob)
  

  Note: Parentheses must be appropriately used to group the combinations. For the above queries, you can't omit the parentheses. The following query is illegal: owner:(amy john OR bob).

• Return assets whose owner field has word amy and word john or name field has word bob.

  owner:(amy john) OR name:bob
  

Negate search filters

Search filters can be negated using the NOT operator. Parentheses are supported but not required.

Note: The NOT operator must be uppercased. Negation is only supported when searching resources.

Examples: Negate search filters

• Return assets whose state field doesn't contain the word ACTIVE.

  NOT state:ACTIVE
  

• Return assets whose owner field has neither word amy nor word john.

  NOT owner:(amy OR john)
  

• Return assets whose networkTags field doesn't contain the word internal or private.

  NOT (networkTags:internal OR networkTags:private)
  

Wildcard

Asterisks (*) can be used in a phrase as a wildcard character. Depending on its position, it can have different meanings.

• If it is at the end of a phrase, e.g., "am 20*", it is a token prefix match indicator. The query is equivalent to (am* 20*). It matches the field containing a token starting with "am", e.g., "amy", and a token starting with "20", e.g., "2021". The order of prefixes doesn't matter.

• If the whole phrase only contains one *, e.g., "labels.env:*", it performs an existence check. It checks whether the given label key "env" exist. Other fields are not supported.

• If it is in the middle of a phrase, e.g., "compute*storage", it is treated as a tokenization delimiter. The query is equivalent to "compute storage".

• If it is at both the beginning and the end of a phrase, e.g., "*compute storage*", it is treated as a tokenization delimiter. The query is equivalent to "compute storage".

Examples: token prefix match

• Return assets whose owner field contains a word that starts with am:

  owner:am*
  

• Return assets whose owner field has two words with "amy" and "20" as prefixes:

  owner:"amy 20*"
  
  owner:"20 amy*"
  

• If you have an asset whose owner field value is "[e-mail]", the above queries both match. After tokenizing, both "amy" and "20" are prefixes. Note that the query string "amy 20*" is different from "amy 20". The latter one requires 20 to be an entire word other than a prefix.

Examples: label key existence

• Return assets that one of whose labels has "env" as key and has any value (including empty value or no value):

  labels.env:*