Field masks

AI-generated Key Takeaways

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