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] |
| Quoted field names with grave accents (escaping by doubling) | `Company ``Flag`` (Y/N)` |
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 (`). If the field name itself contains the same character used for quoting, you must escape it by doubling the character. For example:
- If a field name contains a double quote (") and is quoted with double quotes, double the double quote in the field name. For instance, a field named
Company "Flag"should be written as"Company ""Flag""". - If a field name contains a single quote (') and is quoted with single quotes, double the single quote in the field name. For instance, a field named
Company 'Flag'should be written as'Company ''Flag'''. - If a field name contains a grave accent (`) and is quoted with grave accents, double the grave accent in the field name. For instance, a field named
Company `Flag`should be written as`Company ``Flag```.
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.
