Field Path Expressions
Overview
Field path expressions represent the location of a field or value within a record. They can be parsed from a string using FieldPath.parse(String) or created programmatically by adding name (FieldPath.name(String)) and index (FieldPath.index(int)) segments to a FieldPath instance.
For example, the field path customer.address[0].city can be created in two ways:
FieldPath.parse("customer.address[0].city")new FieldPath().name("customer").name("address").index(0).name("city")
Examples
| Description | Example |
|---|---|
| Single field names | firstName |
| Nested field names | customer.firstName |
| Array values | customer.address[2].city |
| Positional field access — since city is the first field in the address record, it can be referenced at position zero ([0]) | customer.address[2][0] |
| Positional field access — fields in the root record can also be accessed by their position. For example, the second field would be at position one ([1]) | [1] |
| String array indices can be used to reference fields with spaces and special characters in their names. Both double and single quotes can be used to surround string array indices. | customer.address[2]["zip code"] customer.address[2]['zip code'] |
| Quoted field names (for field names with spaces or symbols) | 'Company Flag (Y/N)' |
| Quoted nested field names (for field names with spaces or symbols) | customer."Company Flag (Y/N)" |
| Quoted array values (for field names with spaces or symbols) | `Company Address`[0] |
Identifiers
Identifiers in field expressions may start with letters, underscores (_), at symbols (@), or dollar signs ($) and contain letters, numbers, underscores, at symbols, and dollar signs. You will need to quote field expressions that contain other symbols and spaces if they should be treated as part of the field name. For example, if your field name contains a period, you will need to quote it ("Package Lbs.").
Quoting
When quoting fields, you can use double quotes ("), single quotes ('), or grave accent (`).
Caution With Array Values
A note of caution: FieldPath can also represent the location of values in array fields. For example, city[2] or customer.address[0].city[2] could match the third city in an array field. Some methods and operations expecting a field will throw an exception (or return false) if the supplied FieldPath matches an array value and not a field.
