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.

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
            True if both term-1 and term-2 are true. Implicit 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 = value
            True if key is equal to value.

        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 : simple-pattern
            True if key matches simple-pattern. The match is anchored (all characters must match), case insensitive, and allows one * operator that matches any sequence of 0 or more characters. The pattern abc matches abc, the pattern abc* matches abc and abcxyz, the pattern *xyz matches xyz and abcxyz, and the pattern * matches any non-empty string. 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 matches the RE (regular expression) pattern value.

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

EXAMPLES
List all instances resources:
    $ gcloud compute instances list
List instances resources that have machineType f1-micro:
    $ gcloud compute instances list --filter='machineType:f1-micro'
List resources with zone prefix us and not MachineType f1-micro:
    $ gcloud compute instances list \
        --filter='zone ~ ^us AND -machineType:f1-micro'
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 after a specific date:
    $ gcloud projects list \
        --format="table(projectNumber,projectId,createTime)" \
        --filter="createTime.date('%Y-%m-%d', Z)='2016-05-11'"
Note that in the last example, a projection on the key was used. The filter is applied on the createTime key after the date formatting is set.