Page Summary
-
Field masks allow API callers to specify which fields a request should return, improving performance by avoiding unnecessary work.
-
Field masks can be specified as a URL query parameter (
$fieldsorfields) or as an HTTP or gRPC header (X-Goog-FieldMask). -
Nested fields in a field mask can be selected using dot syntax or by enclosing them in parentheses.
-
The asterisk (
*) in a field mask returns all fields and nested fields.
Field masks are a way for API callers to list the fields that a request should return. Using a field mask allows the API to avoid unnecessary work and improves performance.
A field mask can be specified either as a URL query parameter or as an HTTP or gRPC header:
| URL Query Parameter | HTTP or gRPC Header |
|---|---|
$fields
or fields
|
X-Goog-FieldMask
|
Field mask syntax
The following field mask examples are based on this example response type.
message
ExampleResponse
{
message
Foo
{
string
foo1
=
1
;
string
foo2
=
2
;
Bar
foo3
=
3
;
}
message
Bar
{
string
bar1
=
1
;
string
bar2
=
2
;
string
bar3
=
3
;
}
string
field1
=
1
;
repeated
Foo
field2
=
2
;
}
Nested fields can be selected using the dot syntax or by enclosing them in parentheses.
| Expression | Output |
|---|---|
*
|
Returns all fields and nested fields. |
field1,field2
|
Returns field1
and all nested fields of field2
. |
field1,field2.foo1
|
Returns field1
and field2.foo1
. |
field1,field2(foo1)
|
Returns field1
and field2.foo1
. |
field1,field2(foo1,foo2)
|
Returns:field1
field2.foo1
field2.foo2
|
field1,field2(foo1,foo3(bar1,bar2))
|
Returns:field1
field2.foo1
field2.foo3.bar1
field2.foo3.bar2
|
