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=amy.2020@gmail.com
.
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:
"amy-2020@GMAIL.com"
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]
"BOB_test@gmail.com"
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.
Examples
For example, an asset whose owner
field has value "amy.2020@gmail.com"
matches the following queries:
Matches because the phrase is exactly the same as the field's value.
owner=amy.2020@gmail.com
Matches because punctuations are treated as delimiters and case is insensitive.
owner:amy-2020@GMAIL.com
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 "amy.2020@gmail.com"
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=amy.2020@GMAIL.com
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)
).
The following expressions are the same:
owner:amy
owner:"amy"
owner:amy.2020@gmail.com
owner:"amy.2020@gmail.com"
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:"amy%2020@gmail.com"
description:"domain:gmail.com"
description:"hello \"world\""
description:"hello\\world"
Examples: phrase
Return assets whose
owner
field has wordamy
and word2020
in order and consecutively:owner:"amy 2020"
If you have an asset whose
owner
field value is"amy.2020@gmail.com"
, the above query matches.If you have an asset whose
owner
field value is"2020.amy@gmail.com"
, the above query does not match, as the words are not matched in order.If you have an asset whose
owner
field value is"amy.us.2020@gmail.com"
, 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.
Examples: combination
Return assets whose
owner
field has both wordamy
and wordjohn
, 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)
Return assets whose
owner
field has either wordamy
or wordjohn
.owner:(amy OR john)
Return assets whose
owner
field has both wordamy
and wordjohn
or has wordbob
.owner:((amy john) OR bob)
Return assets whose
owner
field has wordamy
and wordjohn
orname
field has wordbob
.owner:(amy john) OR name:bob
Negate search filters
Search filters can be negated using the NOT
operator. Parentheses are
supported but not required.
Examples: Negate search filters
Return assets whose
state
field doesn't contain the wordACTIVE
.NOT state:ACTIVE
Return assets whose
owner
field has neither wordamy
nor wordjohn
.NOT owner:(amy OR john)
Return assets whose
networkTags
field doesn't contain the wordinternal
orprivate
.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 witham
: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"amy.2020@gmail.com"
, 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 requires20
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:*