gcloud_topic_filters (1)

NAME

gcloud topic filters - resource filters supplementary help

DESCRIPTION

Most gcloud commands return a list of resources on success. By default they are pretty-printed on the standard output. The --format=NAME[ATTRIBUTES](PROJECTION) and --filter=EXPRESSION flags along with projections can be used to format and change the default output to a more meaningful result.
To change the default output format of a command, use the --format flag. For details run $ gcloud topic formats.
To select resources to be listed, use the --filter flag. Resource filters are described in detail below.
To reach resource items through a unique path of names from the root, use resource-keys. For details run $ gcloud topic resource-keys.
To list a subset of resource keys in a resource, use projections. For details run $ gcloud topic projections.
To work through an interactive tutorial about using the filter and format flags instead, see: console.cloud.google.com/cloudshell/open?git_repo=https://github.com/GoogleCloudPlatform/cloud-shell-tutorials&page=editor&tutorial=cloudsdk/tutorial.md

Filter Expressions

A filter expression is a Boolean function that selects the resources to print from a list of resources. Expressions are composed of terms connected by logic operators.

LogicOperator

Expressions containing both AND and OR must be parenthesized to disambiguate precedence.

NOT term-1

True if term-1 is False, otherwise False.

term-1 AND term-2

True if both term-1 and term-2 are true.

term-1 OR term-2

True if at least one of term-1 or term-2 is true.

term-1 term-2

Term conjunction (implicit AND) is True if both term-1 and term-2 are true. Conjunction has lower precedence than OR.

Terms

A term is a key operator value tuple, where key is a dotted name that evaluates to the value of a resource attribute, and value 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.

Operator Terms

key : simple-pattern

: operator evaluation is changing for consistency across Google APIs. The current default is deprecated and will be dropped shortly. A warning will be displayed when a --filter expression would return different matches using both the deprecated and new implementations.
The current deprecated default is True if key contains simple-pattern. The match is case insensitive. It allows one * that matches any sequence of 0 or more characters. If * is specified then the match is anchored, meaning all characters from the beginning and end of the value must match.
The new implementation is True if simple-pattern matches any word in key. Words are locale specific but typically consist of alpha-numeric characters. Non-word characters that do not appear in simple-pattern are ignored. The matching is anchored and case insensitive. An optional trailing * does a word prefix match.
Use key:* to test if key is defined and -key:* to test if key is undefined.

key :( simple-pattern ... )

True if key matches any simple-pattern in the (space, tab, newline, comma) separated list.

key = value

True if key is equal to value. Equivalent to :, with the exception that the trailing * prefix match is not supported.

key =( value ... )

True if key is equal to any value in the (space, tab, newline, ,) separated list.

key != value

True if key is not value. Equivalent to -key=value and NOT key=value.

key < value

True if key is less than value. If both key and value are numeric then numeric comparison is used, otherwise lexicographic string comparison is used.

key <= value

True if key is less than or equal to value. If both key and value are numeric then numeric comparison is used, otherwise lexicographic string comparison is used.

key >= value

True if key is greater than or equal to value. If both key and value are numeric then numeric comparison is used, otherwise lexicographic string comparison is used.

key > value

True if key is greater than value. If both key and value are numeric then numeric comparison is used, otherwise lexicographic string comparison is used.

key ~ value

True if key matches the RE (regular expression) pattern value.

key !~ value

True if key does not match the RE (regular expression) pattern value.

EXAMPLES

List all Google Compute Engine instance resources:

$ gcloud compute instances list

List Compute Engine instance resources that have machineType f1-micro:

$ gcloud compute instances list --filter="machineType:f1-micro"

List Compute Engine instance resources with zone prefix us and not MachineType f1-micro:

$ gcloud compute instances list \
    --filter="zone ~ ^us AND -machineType:f1-micro"

List Compute Engine instance resources with tag my-tag:

$ gcloud compute instances list --filter="tags.items=my-tag"

List Compute Engine instance resources with tag my-tag or my-other-tag:

$ gcloud compute instances list \
    --filter="tags.items=(my-tag,my-other-tag)"

List Compute Engine instance resources with tag my-tag and my-other-tag:

$ gcloud compute instances list \
    --filter="tags.items=my-tag AND tags.items=my-other-tag"

List Compute Engine instance resources which either have tag my-tag but not my-other-tag or have tag alternative-tag:

$ gcloud compute instances list \
    --filter="(tags.items=my-tag AND -tags.items=my-other-tag) OR\
 tags.items=alternative-tag"

List Compute Engine instance resources with label my-label with any value:

$ gcloud compute instances list --filter="labels.my-label:*"

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

$ gcloud projects list --format="json" \
    --filter="labels.env=test AND labels.version=alpha"

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

$ gcloud projects list \
    --format="table(projectNumber,projectId,createTime)" \
    --filter="createTime>=2018-01-15"

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

$ gcloud projects list \
    --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 ISO8601 durations:

$ gcloud projects list \
    --format="table(projectNumber,projectId,createTime)" \
    --filter="createTime>-P2W"

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

This table shows : operator pattern matching:

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