GCLOUD_TOPIC_PROJECTIONS(1)

NAME

gcloud topic projections - resource projections 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) flag changes the default output: NAME
    The format name.
ATTRIBUTES
    Format specific attributes. For details run $ gcloud topic formats.
PROJECTION
    A list of resource keys that selects the data listed. Resource projections are described in detail below.
resource keys
    Keys are names for resource resource items. For details run $ gcloud topic resource-keys. Most gcloud list commands have a --filter=EXPRESSION flag that selects resources to be listed. For details run $ gcloud topic filters.

Projections
A projection is a list of keys that selects resource data values. Projections are used in --format flag expressions. For example, the table format requires a projection that describes the table columns:
    table(name, network.ip.internal, network.ip.external, uri())

Transforms
A transform formats resource data values. Each projection key may have zero or more transform calls:
    _key_._transform_([arg...])...
This example applies the foo() and then the bar() transform to the status.time resource value:
    (name, status.time.foo().bar())
In the descriptions below the argument r is the implicit resource data value. r is not specified in transform calls. The builtin transform functions are: always(r)
    Marks a transform sequence to always be applied. In some cases transforms are disabled. Prepending always() to a transform sequence causes the sequence to always be evaluated. The arguments are: r
        A resource.
    For example:
        some_field.always().foo().bar() will always apply foo() and then bar().
basename(r, undefined="")
    Returns the last path component in r. The arguments are: r
        A URI or unix/windows file path.
    undefined
        This value is returned if r or the basename is empty.
color(r, red, yellow, green, blue)
    Colorizes the string value of r. The resource string is searched for an re pattern match in Roy.G.Biv order. The first pattern that matches colorizes the resource string with that color. The arguments are: r
        A JSON-serializable object.
    red
        Color red resource value pattern.
    yellow
        Color yellow resource value pattern.
    green
        Color green resource value pattern.
    blue
        Color blue resource value pattern.
date(r, format="%Y-%m-%dT%H:%M:%S", unit=1, undefined="", tz)
    Formats r to a strftime() format. The arguments are: r
        A timestamp number or an object with 3 or more of these fields: year, month, day, hour, minute, second, millisecond, microsecond, nanosecond.
    format
        The strftime(3) format.
    unit
        Timestamp r divided by unit yields seconds.
    undefined
        Returns this if r does not contain a valid time.
    tz
        Fixed timezone string, local timezone if None. For example, EST5EDT, US/Pacific, UTC, WEST.
duration(r, unit=1, undefined="")
    Formats r to a duration string. The arguments are: r
        A JSON-serializable object.
    unit
        r divided by unit yields seconds.
    undefined
        Returns this if r/unit is not a valid timestamp.
error(r, message)
    Raises an Error exception that does not generate a stack trace. The arguments are: r
        A JSON-serializable object.
    message
        An error message. If None then r is formatted as the error message.
fatal(r, message)
    Raises an InternalError exception that generates a stack trace. The arguments are: r
        A JSON-serializable object.
    message
        An error message. If None then r is formatted as the error message.
firstof(r, args)
    Returns the first non-empty r.name value for name in args. The arguments are: r
        A JSON-serializable object.
    args
        Names to check for values in r.
    For example:
        x.firstof(bar_foo, barFoo, BarFoo, BAR_FOO) will check x.bar_foo, x.barFoo, x.BarFoo, and x.BAR_FOO in order for the first non-empty value.
format(r, fmt, args)
    Formats a sub-projection of r. The arguments are: r
        A JSON-serializable object.
    fmt
        The format string with {0} ... {nargs-1} references to the resource key arg values.
    args
        The resource key args to format. The args values form a projection on r. The projection symbols and aliases are available in the sub-projection.
    For example:
        --format='value(format("{0:f.1}/{0:f.1}", q.CPU.default, q.CPU.limit))'
group(r, args)
    Formats a [...] grouped list. Each group is enclosed in [...]. The first item separator is ':', subsequent separators are ','. [item1] [item1] ... [item1: item2] ... [item1: item2] [item1: item2, item3] ... [item1: item2, item3] The arguments are: r
        A JSON-serializable object.
    args
        Optional attribute names to select from the list. Otherwise the string value of each list item is selected.
iso(r, undefined="T")
    Formats r to the numeric ISO time format. The arguments are: r
        A JSON-serializable object.
    undefined
        Returns this if r does not have an isoformat() attribute.
len(r)
    Returns the length of r if r is non-empty, 0 otherwise. The arguments are: r
        A JSON-serializable object.
list(r, undefined="", separator=",")
    Formats a dict or list into a compact comma separated list. The arguments are: r
        A JSON-serializable object.
    undefined
        Return this if r is empty.
    separator
        The list item separator string.
map(r)
    Applies the next transform in the sequence to each item in list resource r. The arguments are: r
        A resource.
    For example:
        list_field.map().foo().bar() applies foo() to each item in list_field and then bar() to the resulting value. list_field.map().foo().map().bar() applies foo() to each item in list_field and then bar() to each item in the resulting list.
resolution(r, undefined="", transpose=False)
    Formats a human readable XY resolution. The arguments are: r
        object, A JSON-serializable object containing an x/y resolution.
    undefined
        Returns this if a recognizable resolution was not found.
    transpose
        Returns the y/x resolution if True.
scope(r, args)
    Gets the /args/ suffix from URI r. The arguments are: r
        A URI.
    args
        Optional URI segment names. If not specified then 'regions', 'zones' is assumed.
    For example:
        scope('https://abc/foo/projects/bar/zyx', 'projects') returns 'bar/xyz'. scope("https://abc/foo/rergions/abc") returns 'abc'.
segment(r, index=-1, undefined="")
    Returns the index-th URI path segment in r. The arguments are: r
        A URI path.
    index
        The path segment index to return counting from 0.
    undefined
        This value is returned if r or segment index is empty.
size(r, zero="0", units_in, units_out, min=0)
    Formats a human readable size in bytes. The arguments are: r
        A size in bytes.
    zero
        Returns this if size==0. Ignored if None.
    units_in
        A unit suffix (only the first character is checked) or unit size. The size of r is multiplied by this size. The defaults is 1.0.
    units_out
        A unit suffix (only the first character is checked) or unit size. The size of r is divided by this size. The defaults is 1.0.
    min
        Sizes < min will be listed as "< MIN".
uri(r, undefined=".")
    Gets the URI for r. The arguments are: r
        A JSON-serializable object.
    undefined
        Returns this if a the URI for r cannot be determined.
yesno(r, yes, no="No")
    Returns no if r is empty, yes or r otherwise. The arguments are: r
        A JSON-serializable object.
    yes
        If r is not empty then returns yes or r.
    no
        Returns this string if r is empty.
The compute transform functions are: firewall_rule(r)
    Returns a compact string describing the firewall rule in r. The compact string is a comma-separated list of PROTOCOL:PORT_RANGE items. If a particular protocol has no port ranges then only the protocol is listed. The arguments are: r
        JSON-serializable object.
image_alias(r)
    Returns a comma-separated list of alias names for the image in r. The arguments are: ``r``
        JSON-serializable object.
next_maintenance(r)
    Returns the timestamps of the next scheduled maintenance or . All timestamps are assumed to be ISO strings in the same timezone. The arguments are: r
        JSON-serializable object.
operation_http_status(r)
    Returns the HTTP response code of the operation in r. The arguments are: r
        JSON-serializable object.
quota(r)
    Formats the quota in r as usage/limit. The arguments are: r
        JSON-serializable object.
status(r)
    Returns the machine status in r with deprecation information if applicable. The arguments are: ``r``
        JSON-serializable object.

Key Attributes
Key attributes control formatted output. Each projection key may have zero or more attributes:
    _key_:_attribute_=_value_...
where =value is omitted for Boolean attributes and no-attribute sets the attribute to false. Attribute values may appear in any order, but must be specified after any transform calls. The attributes are: alias=ALIAS-NAME
    Sets ALIAS-NAME as an alias for the projection key.
align=ALIGNMENT
    Specifies the output column data alignment. Used by the table format. The alignment values are: left
        Left (default).
    center
        Center.
    right
        Right.
label=LABEL
    A string value used to label output. Use :label="" or :label= for no label. The table format uses LABEL values as column headings. Also sets LABEL as an alias for the projection key. The default label is the the disambiguated right hand parts of the column key name in ANGRY_SNAKE_CASE.
[no-]reverse
    Sets the key sort order to descending. no-reverse resets to the default ascending order.
sort=SORT-ORDER
    An integer counting from 1. Keys with lower sort-order are sorted first. Keys with same sort order are sorted left to right.

EXAMPLES
List a table of instance zone (sorted in descending order) and name (sorted by name and centered with column heading INSTANCE) and creationTimestamp (listed using the strftime(3) year-month-day format with column heading START):
    $ gcloud compute instances list \
        --format='table(name:sort=2:align=center:label=INSTANCE, zone:\ sort=1:reverse, creationTimestamp.date("%Y-%m-%d"):label=START\ )'
List only the name, status and zone instance resource keys in YAML format:
    $ gcloud compute instances list --format='yaml(name, status, zone)'
List only the config.account key value(s) in the info resource:
    $ gcloud info --format='value(config.account)'