Field masks

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 ($fields or fields) 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