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: policy=[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: colon (:) operator

FIELD:QUERY

An example query is: policy: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 (that is, 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 in 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 policy field has the value [e-mail] matches the following queries:

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

policy=[e-mail]

• Matches because punctuation characters are treated as delimiters, and the query is case-insensitive.

policy:[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.

policy:"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.

policy:(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.

policy:(gmail "amy 2020")

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

policy:amy-20*

An asset whose policy 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.

policy=[e-mail]

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

policy=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 (for example, 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 \ with a single space, as non-alphanumeric characters are treated as delimiters when performing the search.

The following expressions are the same:

policy:amy
policy:"amy"

policy:[e-mail]
policy:"[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"

policy:"[e-mail]"

description:"domain:gmail.com"

description:"hello \"world\""

description:"hello\\world"

Examples: phrase

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

  policy:"amy 2020"
  

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

• If you have an asset whose policy 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 policy 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 policy 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 (for example, field:"word1 word2 word3").

  owner:(amy john)
  

  Note: If an asset contains a field with a list of values, for example policy=["[e-mail]", "[e-mail]", "[e-mail]"]. Searching with policy:(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 (for example [e-mail]) containing both word amy and word john.

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

  policy:(amy OR john)
  

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

  policy:((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: policy:(amy john OR bob).

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

  policy:(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 policy field has neither word amy nor word john.

  NOT policy:(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, for example, "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", for example, "amy", and a token starting with "20", for example, "2021". The order of prefixes doesn't matter.

• If the whole phrase only contains one *, for example, "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, for example, "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, for example, "*compute storage*", it is treated as a tokenization delimiter. The query is equivalent to "compute storage".

Examples: token prefix match

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

  policy:am*
  

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

  policy:"amy 20*"
  
  policy:"20 amy*"
  

• If you have an asset whose policy 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.

Example: 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:*