gcloud beta topic filters - resource filters supplementary help

Use the--format flag to change the default output format of acommand. For details run $gcloudtopic formats.

Use the--filter flag to select resources to be listed. Resourcefilters are described in detail below.

Use resource-keys to reach resource items through a unique path of names fromthe root. For details run $gcloud topic resource-keys.

Use projections to list a subset of resource keys in a resource. For details run$gcloud topicprojections.

Note: To refer to a list of fields you can sort, filter, and format by for eachresource, you can run a list command with the format set totext orjson. For example, $gcloud compute instanceslist --limit=1 --format=text.

To work through an interactive tutorial about using the filter and format flagsinstead, see:https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/GoogleCloudPlatform/cloud-shell-tutorials&page=editor&tutorial=cloudsdk/tutorial.mdNote: Depending on the specific server API, filtering may be done entirely bythe client, entirely by the server, or by a combination of both.

LogicOperator

Logic operators must be in uppercase:AND,OR,NOT. Additionally, expressions containing bothAND andOR must be parenthesized to disambiguate precedence.

NOTterm-1

True ifterm-1 is False, otherwise False.

term-1ANDterm-2

True if bothterm-1 andterm-2are true.

term-1ORterm-2

True if at least one ofterm-1 orterm-2 is true.

term-1term-2

Term conjunction (implicitAND) is True if bothterm-1 andterm-2 are true.Conjunction has lower precedence thanOR.

Terms

A term is akeyoperatorvalue tuple, wherekey is adotted name that evaluates to the value of a resource attribute, andvalue may be:

number

integer or floating point numeric constant

unquoted literal

character sequence terminated by space, ( or )

quoted literal

"…" or'…'

Most filter expressions need to be quoted in shell commands. If you use'…' shell quotes then use"…" filter string literal quotes and vice versa.

Quoted literals will be interpreted as string values, even when the value couldalso be a valid number. For example, 'key:1e9' will be interpreted as a keynamed 'key' with the string value '1e9', rather than with the float value of onebillion expressed in scientific notation.

Operator Terms

key:simple-pattern

: operator evaluation is changing for consistency across GoogleAPIs. The current default is deprecated and will be dropped shortly. A warningwill be displayed when a --filter expression would return different matchesusing both the deprecated and new implementations.

The current deprecated default is True ifkey containssimple-pattern. The match is case insensitive. It allowsone* that matches any sequence of 0 or more characters. If* is specified then the match is anchored, meaning all charactersfrom the beginning and end of the value must match.

The new implementation is True ifsimple-pattern matchesanyword inkey. Words arelocale specific but typically consist of alpha-numeric characters. Non-wordcharacters that do not appear insimple-pattern areignored. The matching is anchored and case insensitive. An optional trailing* does a word prefix match.

Usekey:* to test ifkey is defined and-key:* to test ifkey is undefined.

key:(simple-pattern …)

True ifkey matches anysimple-pattern in the (space, tab, newline, comma)separated list.

key=value

True ifkey is equal tovalue,or [deprecated] equivalent to: with the exception that thetrailing* prefix match is not supported.

For historical reasons, this operation currently behaves differently fordifferent Google APIs. For many APIs, this is True if key is equal to value. Fora few APIs, this is currently equivalent to:, with the exceptionthat the trailing* prefix match is not supported. However, thisbehaviour is being phased out, and use of= for those APIs isdeprecated; for those APIs, if you want matching, you should use:instead of=, and if you want to test for equality, you can usekey <=value ANDkey >=value.

key=(value …)

True ifkey is equal to anyvalue in the (space, tab, newline,,)separated list.

key!=value

True ifkey is notvalue.Equivalent to -key=value and NOTkey=value.

key<value

True ifkey is less thanvalue.If bothkey andvalue arenumeric then numeric comparison is used, otherwise lexicographic stringcomparison is used.

key<=value

True ifkey is less than or equal tovalue. If bothkey andvalue are numeric then numeric comparison is used,otherwise lexicographic string comparison is used.

key>=value

True ifkey is greater than or equal tovalue. If bothkey andvalue are numeric then numeric comparison is used,otherwise lexicographic string comparison is used.

key>value

True ifkey is greater thanvalue. If bothkey andvalue are numeric then numeric comparison is used,otherwise lexicographic string comparison is used.

key~value

True ifkey contains a match for the RE (regularexpression) patternvalue. Depending on your shell, youmight have to escape or quote~ to ensure it isn'tconsumed as HOME.

key!~value

True ifkey does not contain a match for the RE (regularexpression) patternvalue. Depending on your shell, youmight have to escape or quote~ to ensure it isn'tconsumed as HOME.

Regular expressions are evaluated using Python's standard library:https://docs.python.org/3/library/re.html#re-syntax.

gcloudprojectslist--format=yaml--limit=1

This might display the following data:

createTime:'2021-02-10T19:19:49.242Z'lifecycleState:ACTIVEname:MyProjectparent:id:'123'type:folderprojectId:my-projectprojectNumber:'456'

Using this data, one way of filtering projects is by their parent's ID byspecifyingparent.id as thekey.

gcloudcomputeinstanceslist

List Compute Engine instance resources that have machineTypef1-micro:

gcloudcomputeinstanceslist--filter="machineType:f1-micro"

List Compute Engine instance resources using a regular expression for zoneus and not MachineTypef1-micro:

gcloudcomputeinstanceslist--filter="zone ~ us AND -machineType:f1-micro"

List Compute Engine instance resources with tagmy-tag:

gcloudcomputeinstanceslist--filter="tags.items=my-tag"

List Compute Engine instance resources with tagmy-tag ormy-other-tag:

gcloudcomputeinstanceslist--filter="tags.items=(my-tag,my-other-tag)"

List Compute Engine instance resources with tagmy-tag andmy-other-tag:

gcloudcomputeinstanceslist--filter="tags.items=my-tag AND tags.items=my-other-tag"

List Compute Engine instance resources which either have tagmy-tagbut notmy-other-tag or have tagalternative-tag:

gcloudcomputeinstanceslist--filter="(tags.items=my-tag AND -tags.items=my-other-tag) OR tags.items=alternative-tag"

List Compute Engine instance resources which contain the keyfingerprint in themetadata object:

gcloudcomputeinstanceslist--limit=1--filter="metadata.list(show="keys"):fingerprint"

List Compute Engine instance resources with labelmy-label with anyvalue:

gcloudcomputeinstanceslist--filter="labels.my-label:*"

List Container Registry images that have a tag with the value '30e5504145':

gcloudcontainerimageslist-tags--filter="'tags:30e5504145'"

The last example encloses the filter expression in single quotes because thevalue '30e5504145' could be interpreted as a number in scientific notation.

List in JSON format those projects where the labels match specific values (e.g.label.env is 'test' and label.version is alpha):

gcloudprojectslist--format="json"--filter="labels.env=test AND labels.version=alpha"

List projects that were created on and after a specific date:

gcloudprojectslist--format="table(projectNumber,projectId,createTime)"--filter="createTime>=2018-01-15"

List projects that were created on and after a specific date and time and sortfrom oldest to newest (with dates and times listed according to the localtimezone):

gcloudprojectslist--format="table(projectNumber,projectId,createTime.date(tz=LOCAL))"--filter="createTime>=2018-01-15T12:00:00"--sort-by=createTime

List projects that were created within the last two weeks, using ISO8601durations:

gcloudprojectslist--format="table(projectNumber,projectId,createTime)"--filter="createTime>-P2W"

For more about ISO8601 durations, see:https://en.wikipedia.org/wiki/ISO_8601

The table below shows examples of pattern matching if used with the: operator:

PATTERN	VALUE	MATCHES	DEPRECATED_MATCHES
abc*	abcpdqxyz	True	True
abc	abcpdqxyz	False	True
pdq*	abcpdqxyz	False	False
pdq	abcpdqxyz	False	True
xyz*	abcpdqxyz	False	False
xyz	abcpdqxyz	False	True
*	abcpdqxyz	True	True
*	(None)	False	False
*	('')	False	False
*	(otherwise)	True	True
abc*	abc.pdq.xyz	True	True
abc	abc.pdq.xyz	True	True
abc.pdq	abc.pdq.xyz	True	True
pdq*	abc.pdq.xyz	True	False
pdq	abc.pdq.xyz	True	True
pdq.xyz	abc.pdq.xyz	True	True
xyz*	abc.pdq.xyz	True	False
xyz	abc.pdq.xyz	True	True