AI-generated Key Takeaways
-
Field masks enhance API performance by allowing callers to specify the desired fields in a request, reducing unnecessary data retrieval and processing.
-
Field masks can be implemented using either URL query parameters (
$fieldsorfields) or HTTP/gRPC headers (X-Goog-FieldMask). -
They utilize a syntax where nested fields can be selected using dot notation or parentheses, offering flexibility in specifying desired data.
-
Using an asterisk (*) in a field mask will return all fields and nested fields for the given response type.
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
|
