gcloud beta topic projections - resource projections 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. For detailsrun $gcloud topic filters.

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. Resourceprojections are described in detail below.

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.md

_key_._transform_([arg…])…

This example applies thefoo() and then thebar()transform to thestatus.time resource value:

(name,status.time.foo().bar())

always()

Marks a transform sequence to always be applied.

In some cases transforms are disabled. Prepending always() to a transformsequence causes the sequence to always be evaluated.

For example:

some_field.always().foo().bar()

Always applies foo() and then bar().

basename(undefined="")

Returns the last path component.

The arguments are:

undefined

Returns this value if the resource or basename is empty.

collection(undefined="")

Returns the current resource collection.

The arguments are:

undefined

This value is returned if r or the collection is empty.

color(red, yellow, green, blue)

Colorizes the resource string value.

Thered,yellow,green andblue args are RE patterns, matched against the resource in order.The first pattern that matches colorizes the matched substring with that color,and the other patterns are skipped.

The arguments are:

red

The substring pattern for the color red.

yellow

The substring pattern for the color yellow.

green

The substring pattern for the color green.

blue

The substring pattern for the color blue.

For example:

color(red=STOP,yellow=CAUTION,green=GO)

For the resource string "CAUTION means GO FASTER" displays the substring"CAUTION" in yellow.

count()

Counts the number of each item in the list.

A string resource is treated as a list of characters.

For example:

"b/a/b/c".split("/").count() returns{a: 1, b: 2, c:1}.

date(format="%Y-%m-%dT%H:%M:%S", unit=1, undefined="", tz, tz_default)

Formats the resource as a strftime() format.

The arguments are:

format

The strftime(3) format.

unit

If the resource is a Timestamp then divide byunit toyield seconds.

undefined

Returns this value if the resource is not a valid time.

tz

Return the time relative to the tz timezone if specified, the explicit timezonein the resource if it has one, otherwise the local timezone. For example:date(tz=EST5EDT, tz_default=UTC).

tz_default

The default timezone if the resource does not have a timezone suffix.

decode(encoding, undefined="")

Returns the decoded value of the resource that was encoded by encoding.

The arguments are:

encoding

The encoding name.base64 andutf-8 are supported.

undefined

Returns this value if the decoding fails.

duration(start="", end="", parts=3, precision=3, calendar=true, unit=1, undefined="")

Formats the resource as an ISO 8601 duration string.

TheISO 8601Duration format is: "[-]P[nY][nM][nD][T[nH][nM][n[.m]S]]". The 0 duration is"P0". Otherwise at least one part will always be displayed. Negative durationsare prefixed by "-". "T" disambiguates months "P2M" to the left of "T" andminutes "PT5M" to the right.

If the resource is a datetime then the duration ofresource -current_time is returned.

The arguments are:

start

The name of a start time attribute in the resource. The duration of theend - start time attributes in resource is returned. Ifend is not specified then the current time is used.

end

The name of an end time attribute in the resource. Defaults to the current timeif omitted. Ignored ifstart is not specified.

parts

Format at most this many duration parts starting with largest non-zero part.

precision

Format the last duration part with precision digits after the decimal point.Trailing "0" and "." are always stripped.

calendar

Allow time units larger than hours in formatted durations if true. Durationsspecifying hours or smaller units are exact across daylight savings timeboundaries. On by default. Use calendar=false to disable. For example, ifcalendar=true then at the daylight savings boundary2016-03-13T01:00:00 + P1D => 2016-03-14T01:00:00 but 2016-03-13T01:00:00 +PT24H => 2016-03-14T03:00:00. Similarly, a +P1Y duration will be inexact but"calendar correct", yielding the same month and day number next year, even inleap years.

unit

Divide the resource numeric value byunit to yieldseconds.

undefined

Returns this value if the resource is not a valid timestamp.

For example:

duration(start=createTime,end=updateTime)

The duration from resource creation to the most recent update.

updateTime.duration()

The duration since the most recent resource update.

encode(encoding, undefined="")

Returns the encoded value of the resource using encoding.

The arguments are:

encoding

The encoding name.base64 andutf-8 are supported.

undefined

Returns this value if the encoding fails.

enum(enums, inverse=false, undefined="")

Returns the enums dictionary description for the resource.

The arguments are:

enums

The name of a message enum dictionary.

inverse

Do inverse lookup if true.

undefined

Returns this value if there is no matching enum description.

error(message)

Raises an Error exception that does not generate a stack trace.

The arguments are:

message

An error message. If not specified then the resource is formatted as the errormessage.

extract(keys)

Extract a list of non-empty values for the specified resource keys.

The arguments are:

keys

The list of keys in the resource whose non-empty values will be included in theresult.

fatal(message)

Raises an InternalError exception that generates a stack trace.

The arguments are:

message

An error message. If not specified then the resource is formatted as the errormessage.

filter(expression)

Selects elements of x that match the filter expression.

The arguments are:

expression

The filter expression to apply to r.

For example:

x.filter("key:val") selects elements of x that have 'key' fieldscontaining 'val'.

firstof(keys)

Returns the first non-empty attribute value for key in keys.

The arguments are:

keys

Keys to check for resource attribute values,

For example:

x.firstof(bar_foo, barFoo, BarFoo, BAR_FOO)

Checks x.bar_foo, x.barFoo, x.BarFoo, and x.BAR_FOO in order for the firstnon-empty value.

flatten(show="", undefined="", separator=",")

Formats nested dicts and/or lists into a compact comma separated list.

The arguments are:

show

If show=keys then list dict keys; if show=values thenlist dict values; otherwise list dict key=value pairs.

undefined

Return this if the resource is empty.

separator

The list item separator string.

For example:

--format="table(field.map(2).list().map().list().list()"

Expression with explicit flattening.

--format="table(field.flatten()"

Equivalent expression using .flatten().

float(precision=6, spec, undefined="")

Returns the string representation of a floating point number.

One of these formats is used (1) ".precisionspec" ifspec is specified (2)".precision" unless 1e-04 <= abs(number) < 1e+09(3) ".1f" otherwise.

The arguments are:

precision

The maximum number of digits before and after the decimal point.

spec

The printf(3) floating point format "e", "f" or "g" spec character.

undefined

Returns this value if the resource is not a float.

format(fmt, args)

Formats resource key values.

The arguments are:

fmt

The format string with {0} … {nargs-1} references to the resourceattribute name arg values.

args

The resource attribute key expression to format. The printer projection symbolsand aliases may be used in key expressions. If no args are specified then theresource is used as the arg list if it is a list, otherwise the resource is usedas the only arg.

For example:

--format='value(format("{0:f.1}/{1:f.1}", q.CPU.default, q.CPU.limit))'

Formats q.CPU.default and q.CPU.limit as floating point numbers.

group(keys)

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:

keys

Optional attribute keys to select from the list. Otherwise the string value ofeach list item is selected.

if(expr)

Disables the projection key if the flag name filter expr is false.

The arguments are:

expr

A command flag filter name expression. Seegcloud topic filters fordetails on filter expressions. The expression variables are flag names withoutthe leading-- prefix and dashes replaced by underscores.

For example:

table(name, value.if(NOT short_format))

Lists a value column if the--short-format command line flag is notspecified.

iso(undefined="T")

Formats the resource to numeric ISO time format.

The arguments are:

undefined

Returns this value if the resource does not have an isoformat() attribute.

join(sep="/", undefined="")

Joins the elements of the resource list by the value of sep.

A string resource is treated as a list of characters.

The arguments are:

sep

The separator value to use when joining.

undefined

Returns this value if the result after joining is empty.

For example:

"a/b/c/d".split("/").join("!") returns"a!b!c!d".

len()

Returns the length of the resource if it is non-empty, 0 otherwise.

list(show="", undefined="", separator=",")

Formats a dict or list into a compact comma separated list.

The arguments are:

show

If show=keys then list dict keys; if show=values thenlist dict values; otherwise list dict key=value pairs.

undefined

Return this if the resource is empty.

separator

The list item separator string.

lower()

Returns r in lowercase.

map(depth=1)

Applies the next transform in the sequence to each resource list item.

The arguments are:

depth

The list nesting depth.

For example:

list_field.map().foo().list()

Applies foo() to each item in list_field and then list() to the resulting valueto return a compact comma-separated list.

list_field.*foo().list()

* is shorthand for map().

list_field.map().foo().map().bar()

Applies foo() to each item in list_field and then bar() to each item in theresulting list.

abc.xyz.map(2).foo()

Applies foo() to each item in xyz[] for all items in abc[].

abc.xyz.**foo()

** is shorthand for map(2).

notnull()

Remove null values from the resource list.

regex(expression, does_match, nomatch="")

Returns does_match or r itself if r matches expression, nomatch otherwise.

The arguments are:

expression

expression to apply to r.

does_match

If the string matches expression then returndoes_matchotherwise return the string itself ifdoes_match is notdefined.

nomatch

Returns this value if the string does not match expression.

resolution(undefined="", transpose=false)

Formats a human readable XY resolution.

The arguments are:

undefined

Returns this value if a recognizable resolution was not found.

transpose

Returns the y/x resolution if true.

scope(args)

Gets the /args/ suffix from a URI.

The arguments are:

args

Optional URI segment names. If not specified then 'regions', 'zones' is assumed.

For example:

"http://abc/foo/projects/bar/xyz".scope("projects") returns"bar/xyz".

"http://xyz/foo/regions/abc".scope() returns"abc".

segment(index=-1, undefined="")

Returns the index-th URI path segment.

The arguments are:

index

The path segment index to return counting from 0.

undefined

Returns this value if the resource or segment index is empty.

size(zero="0", precision=1, units_in, units_out, min=0)

Formats a human readable size in bytes.

The arguments are:

zero

Returns this if size==0. Ignored if None.

precision

The number of digits displayed after the decimal point.

units_in

A unit suffix (only the first character is checked) or unit size. The size ismultiplied by this. The default is 1.0.

units_out

A unit suffix (only the first character is checked) or unit size. The size isdivided by this. The default is 1.0.

min

Sizes <min will be listed as "<min".

slice(op=":", undefined="")

Returns a list slice specified by op.

The op parameter consists of up to three colon-delimeted integers: start, end,and step. The parameter supports half-open ranges: start and end values can beomitted, representing the first and last positions of the resource respectively.

The step value represents the increment between items in the resource includedin the slice. A step of 2 results in a slice that contains every other item inthe resource.

Negative values for start and end indicate that the positons should start fromthe last position of the resource. A negative value for step indicates that theslice should contain items in reverse order.

If op contains no colons, the slice consists of the single item at the specifiedposition in the resource.

The arguments are:

op

The slice operation.

undefined

Returns this value if the slice cannot be created, or the resulting slice isempty.

For example:

[1,2,3].slice(1:) returns[2,3].

[1,2,3].slice(:2) returns[1,2].

[1,2,3].slice(-1:) returns[3].

[1,2,3].slice(: :-1) returns[3,2,1].

[1,2,3].slice(1) returns[2].

sort(attr="")

Sorts the elements of the resource list by a given attribute (or itself).

A string resource is treated as a list of characters.

The arguments are:

attr

The optional field of an object or dict by which to sort.

For example:

"b/a/d/c".split("/").sort() returns[a, b, c, d].

split(sep="/", undefined="")

Splits a string by the value of sep.

The arguments are:

sep

The separator value to use when splitting.

undefined

Returns this value if the result after splitting is empty.

For example:

"a/b/c/d".split() returns["a", "b", "c", "d"].

sub(pattern, replacement, count=0, ignorecase=true)

Replaces a pattern matched in a string with the given replacement.

Return the string obtained by replacing the leftmost non-overlapping occurrencesof pattern in the string by replacement. If the pattern isn't found, then theoriginal string is returned unchanged.

The arguments are:

pattern

The regular expression pattern to match in r that we want to replace withsomething.

replacement

The value to substitute into whatever pattern is matched.

count

The max number of pattern occurrences to be replaced. Must be non-negative. Ifomitted or zero, all occurrences will be replaces.

ignorecase

Whether to perform case-insensitive matching.

For example:

table(field.sub(" there", ""))

If the field string is "hey there" it will be displayed as "hey".

synthesize(args)

Synthesizes a new resource from the schema arguments.

A list of tuple arguments controls the resource synthesis. Each tuple is aschema that defines the synthesis of one resource list item. Each schema itemdefines the synthesis of one synthesized_resource attribute from anoriginal_resource attribute.

There are three kinds of schema items:

name:literal

The value for the name attribute in the synthesized resource is the literalvalue.

name=key

The value for the name attribute in the synthesized_resource is the value of keyin the original_resource.

key

All the attributes of the value of key in the original_resource are added to theattributes in the synthesized_resource.

The arguments are:

args

The list of schema tuples.

For example:

This returns a list of two resource items

synthesize((name:up, upInfo), (name:down, downInfo))

If upInfo and downInfo serialize to

{"foo": 1, "bar": "yes"}

and

{"foo": 0, "bar": "no"}

then the synthesized resource list is

[{"name": "up", "foo": 1, "bar": "yes"}, {"name": "down", "foo": 0, "bar":"no"}]

This could then be displayed by a nested table using

synthesize(…):format="table(name, foo, bar)"

trailoff(character_limit, undefined="")

Returns r if less than limit, else abbreviated r followed by ellipsis.

The arguments are:

character_limit

An int. Max length of return string. Must be greater than 3 because ellipsis (3chars) is appended to abridged strings.

undefined

A string. Return if r or character_limit is invalid.

upper()

Returns r in uppercase.

uri(undefined=".")

Gets the resource URI.

The arguments are:

undefined

Returns this if a the URI for r cannot be determined.

yesno(yes, no="No")

Returns no if the resource is empty, yes or the resource itself otherwise.

The arguments are:

yes

If the resource is not empty then returnsyes or theresource itself ifyes is not defined.

no

Returns this value if the resource is empty.

build_images(undefined="")

Returns the formatted build results images.

The arguments are:

undefined

Returns this value if the resource cannot be formatted.

build_source(undefined="")

Returns the formatted build source.

The arguments are:

undefined

Returns this value if the resource cannot be formatted.

result_duration(resource, undefined="")

Returns the formatted result duration.

The arguments are:

resource

JSON-serializable object.

undefined

Returns this value if the resource cannot be formatted.

result_status(resource, undefined="")

Returns the formatted result status.

The arguments are:

resource

JSON-serializable object.

undefined

Returns this value if the resource cannot be formatted.

firewall_rule(undefined="")

Returns a compact string describing a firewall rule.

The compact string is a comma-separated list of PROTOCOL:PORT_RANGE items. If aparticular protocol has no port ranges then only the protocol is listed.

The arguments are:

undefined

Returns this value if the resource cannot be formatted.

image_alias(undefined="")

Returns a comma-separated list of alias names for an image.

The arguments are:

undefined

Returns this value if the resource cannot be formatted.

location(undefined="")

Return the region or zone name.

The arguments are:

undefined

Returns this value if the resource cannot be formatted.

location_scope(undefined="")

Return the location scope name, either region or zone.

The arguments are:

undefined

Returns this value if the resource cannot be formatted.

machine_type(undefined="")

Return the formatted name for a machine type.

The arguments are:

undefined

Returns this value if the resource cannot be formatted.

name(undefined="")

Returns a resource name from an URI.

The arguments are:

undefined

Returns this value if the resource cannot be formatted.

next_maintenance(undefined="")

Returns the timestamps of the next scheduled maintenance.

All timestamps are assumed to be ISO strings in the same timezone.

The arguments are:

undefined

Returns this value if the resource cannot be formatted.

operation_http_status(undefined="")

Returns the HTTP response code of an operation.

The arguments are:

undefined

Returns this value if there is no response code.

org_firewall_rule(rule, undefined="")

Returns a compact string describing an organization firewall rule.

The compact string is a comma-separated list of PROTOCOL:PORT_RANGE items. If aparticular protocol has no port ranges then only the protocol is listed.

The arguments are:

rule

JSON-serializable object.

undefined

Returns this value if the resource cannot be formatted.

project(undefined="")

Returns a project name from a selfLink.

The arguments are:

undefined

Returns this value if the resource cannot be formatted.

quota(undefined="")

Formats a quota as usage/limit.

The arguments are:

undefined

Returns this value if the resource cannot be formatted.

scoped_suffixes(uris, undefined="")

Get just the scoped part of the object the uri refers to.

status(undefined="")

Returns the machine status with deprecation information if applicable.

The arguments are:

undefined

Returns this value if the resource cannot be formatted.

type_suffix(uri, undefined="")

Get the type and the name of the object the uri refers to.

vpn_tunnel_gateway(vpn_tunnel, undefined="")

Returns the gateway for the specified VPN tunnel resource if applicable.

The arguments are:

vpn_tunnel

JSON-serializable object of a VPN tunnel.

undefined

Returns this value if the resource cannot be formatted.

zone(undefined="")

Returns a zone name from a selfLink.

The arguments are:

undefined

Returns this value if the resource cannot be formatted.

master_version(undefined="")

Returns the formatted master version.

The arguments are:

undefined

Returns this value if the resource cannot be formatted.

full_status(undefined="UNKNOWN_ERROR")

Returns a full description of the status of a logpoint or snapshot.

Status will be one of ACTIVE, COMPLETED, or a verbose error description. If thestatus is an error, there will be additional information available in the statusfield of the object.

The arguments are:

undefined

Returns this value if the resource is not a valid status.

For example:

--format="table(id, location, full_status())"

Displays the full status in the third table problem.

short_status(undefined="UNKNOWN_ERROR")

Returns a short description of the status of a logpoint or snapshot.

Status will be one of ACTIVE, COMPLETED, or a short error description. If thestatus is an error, there will be additional information available in the statusfield of the object.

The arguments are:

undefined

Returns this value if the resource is not a valid status.

For example:

--format="table(id, location, short_status())"

Displays the short status in the third table problem.

environments(data)

Returns the supported environments for a runtime.

The arguments are:

data

JSON-serializable Runtimes object.

generation(data, undefined="-")

Returns Cloud Functions product version.

The arguments are:

data

JSON-serializable 1st and 2nd gen Functions objects.

undefined

Returns this value if the resource cannot be formatted.

state(data, undefined="")

Returns textual information about functions state.

The arguments are:

data

JSON-serializable object.

undefined

Returns this value if the resource cannot be formatted.

trigger(data, undefined="")

Returns textual information about functions trigger.

The arguments are:

data

JSON-serializable 1st and 2nd gen Functions objects.

undefined

Returns this value if the resource cannot be formatted.

waiter_status(undefined="")

Returns a short description of the status of a waiter or waiter operation.

Status will be one of WAITING, SUCCESS, FAILURE, or TIMEOUT.

The arguments are:

undefined

Returns this value if the resource status cannot be determined.

For example:

--format="table(name, status())"

Displays the status in table column two.

_key_:_attribute_=_value_…

where =value is omitted for Boolean attributes andno-attribute sets the attribute to false. Attributevalues may appear in any order, but must be specified after any transform calls.The attributes are:

alias=ALIAS-NAME

SetsALIAS-NAME as an alias for the projection key.

align=ALIGNMENT

Specifies the output column data alignment. Used by thetableformat. 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.Thetable format usesLABEL values ascolumn headings. Also setsLABEL as an alias for theprojection key. The default label is the disambiguated right hand parts of thecolumn key name in ANGRY_SNAKE_CASE.

[no-]reverse

Sets the key sort order to descending.no-reverse resets to thedefault ascending order.

sort=SORT-ORDER

An integer counting from 1. Keys with lower sort-order are sorted first. Keyswith same sort order are sorted left to right. Columns are sorted based ondisplayed value alone, irrespective of the type of value(date, time, etc.).

wrap[=MIN-WIDTH]

Enables the column text to be wrapped if the table would otherwise be too widefor the display. The column will be wrapped in the available space with aminimum width of either the default or ofMIN-WIDTH ifspecified. The default is 10 characters.

width=COLUMN-WIDTH

An integer denoting the width for the column. The default fits the table to theterminal width or 80 if the output is not a terminal.

gcloudcomputeinstanceslist--format="table(name:sort=2:align=center:label=INSTANCE, zone:sort=1:reverse, creationTimestamp.date("%Y-%m-%d"):label=START)"

List only thename,status andzoneinstance resource keys in YAML format:

gcloudcomputeinstanceslist--format="yaml(name, status, zone)"

List only theconfig.account key value(s) in theinforesource:

gcloudinfo--format="value(config.account)"

List thename,id, anddescription of animaginaryfoo resource, fixing thename column widthto 16 characters, wrapping theid column with the default minimumwidth and thedescription column with a minimum width of 20characters:

gcloudexamplefoolist--format="table(name:width=16, id:wrap, description:wrap=20)"