Query Syntax

To search for assets, you can filter the search results by using the following syntax:

FIELD:QUERY

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 Identity and Access Management (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 field has value "[e-mail]" matches the following queries:

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

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

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

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

    field:(gmail "amy 2020")
  

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

    field:*my-20*
  

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

    field:amy-20*
  

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:

field:amy
field:"amy"

field:[e-mail]
field:"[e-mail]"

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

The following phrases must be enclosed in quotation marks:

field:"my instance"

field:"domain:gmail.com"

field:"[e-mail]"

field:"hello \"world\""

field:"hello\\world"

Examples: phrase

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

  field:"amy 2020"
  

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

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

• If you have an asset whose field value is "[e-mail]", the above query will 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 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").

  field:(amy john)
  

  Note: If an asset contains a field with a list of values, e.g. field=["[e-mail]", "[e-mail]", "[e-mail]"]. Searching with field:(amy john), it will match 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 field has either word amy or word john.

  field:(amy OR john)
  

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

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

• Return assets whose field1 has word amy and word john or field2 has word bob.

  field1:(amy john) OR field2:bob
  

Wildcard

The query value of a comparison can include words that end in *. A word that ends with a * indicates that you want to query all the assets whose field has a certain prefix.

Words can also be enclosed between a pair of asterisks (*). This indicates that you want to query all the assets whose field contain that substring.

The query value can also be a single asterisk (*). This is a special case for queries on label keys only. It uses a single asterisk (*) to match any value (or no value); or in another word, to check existence of a label key in assets. Note that existence check on other fields is NOT supported.

Note: If asterisks (*) are used in the middle of a phrase (e.g. "compute*storage"), it's treated as a tokenization delimiter (equivalent to querying "compute storage"), instead of as a wildcard.

Examples: prefix wildcard

Note: The prefix search syntax is not supported when Searching IAM policies.

• Return assets whose field starts with am:

  field:am*
  

• Return assets whose field starts with "amy 20" after tokenizing:

  field:"amy 20*"
  

• If you have an asset whose field value is "[e-mail]", the above query will match. After tokenizing, "amy 20*" is the prefix. 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.

• If you have an asset whose field value is "user [e-mail]", the above query will not match. "amy 20*" isn't the prefix from the first phrase.

Examples: substring wildcard

• Return assets whose field contains substring my:

  field:*my*
  

• Return assets whose field contains a word that ends with my followed by a word that starts with 20:

  fields:*my.20*
  

• If you have an asset whose field value is "[e-mail]", the above query will match. After tokenizing, "*my.20*" is a substring. Note that query string "*my.20*" is different from "my.20". The latter one requires both my and 20 to be words, other than a subfix/prefix.

• If you have an asset whose field value is "[e-mail]", the above query will match, because a substring match can start from the very first matching character.

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