Home / admin / compound-field-patterns

compound-field-patterns

Compound fields (Name, Address, Geolocation): SOQL access rules, DML semantics, component access in Apex/LWC, reporting column behavior, formula field restrictions.

• v1.3.0
• Salesforce Spring '25+
• Updated 2026-09-04
• Reliability
• Performance

• compound-fields
• address
• geolocation
• name
• soql

Open the skill folder on GitHub

Compound Field Patterns

Activate when working with Salesforce compound fields — Name, Address, and Geolocation — in SOQL, Apex DML, LWC, or reports. Compound fields expose a single logical field (the compound) and N component fields (the parts). SOQL rules, DML behavior, and reporting differ in ways that trip up both humans and LLMs.

Before Starting

• Know the three compound field types. Name (FirstName/LastName/Salutation), Address (Street/City/State/PostalCode/Country/Latitude/Longitude), Geolocation (Latitude/Longitude).
• Compound in SELECT works; compound in WHERE does not. You can SELECT MailingAddress FROM Contact but not WHERE MailingAddress = ....
• DML uses component fields. update new Contact(Id=x, MailingCity='SF') — never assign the compound.
• The compound value exists on three surfaces only. "Compound fields are accessible only through SOAP API, REST API, and Apex. The compound versions of fields aren't accessible anywhere in the Salesforce user interface" (object_reference.txt L2913–L2914). Reports, Visualforce, formulas, Data Loader export and lookup filters all need components.
• Confirm three org flags before writing anything: State and Country/Territory Picklists (adds -Code components), Custom Address Fields (CustomAddressFieldSettings.enableCustomAddressField, irreversible once true — api_meta.txt L113903–L113909), and Person Accounts (changes what Account.Name accepts).

Questions to Ask Before Configuring

Ask these before opening Object Manager or writing the first query; each answer changes the field names your code targets, and an assistant that skips them writes code that compiles and saves the wrong column.

What a proper configuration adds over just reading and writing the field: every write lands on the column the org's flags actually make authoritative, proximity stays possible without a migration, and the rules and reports that need the address are expressed against components that exist on their surface.

Core Concepts

Name compound

Standard objects: Name is read-only compound; update FirstName, LastName, Salutation. Custom objects: Name is plain text unless defined as Person Name type.

Address compound

On Account (BillingAddress, ShippingAddress), Contact (MailingAddress, OtherAddress), Lead, User. The Address type extends Location. Components, verbatim from the Object Reference field table (object_reference.txt L2684–L2726):

Address compound fields are available in the SOAP and REST APIs in API version 30.0 and later.

Geolocation compound

CustomField of type Location (not "Geolocation" — that spelling is not in the FieldType enum, api_meta.txt L45760). Components are addressed by appending __Latitude__s / __Longitude__s to the field name "instead of the usual '__c'" (object_reference.txt L2915–L2917). Geolocation compound fields are available in the SOAP and REST APIs in API version 26.0 and later; Location is not an available custom field type on external objects (api_meta.txt L43233–L43245).

SOQL rules

-- Works: the compound in SELECT, through SOAP API, REST API, or Apex
SELECT Name, BillingAddress FROM Account

-- Fails: "Address fields can't be used in WHERE statements in SOQL"
SELECT Id FROM Account WHERE BillingAddress = :addr

-- Works: components
SELECT Id FROM Account WHERE BillingCity = 'SF' AND BillingStateCode = 'CA'

-- Works: the address compound used as a *location*, not as a filter value
SELECT Id, Name, BillingAddress FROM Account
WHERE DISTANCE(BillingAddress, GEOLOCATION(37.775,-122.418), 'mi') < 20
ORDER BY DISTANCE(BillingAddress, GEOLOCATION(37.775,-122.418), 'mi')
LIMIT 10

The last query is the guide's own sample (object_reference.txt L2836–L2841) and is the reason "no compound in WHERE" needs the qualifier: the compound is not filterable, but it is usable as a location operand inside DISTANCE. DescribeFieldResult.isFilterable() "erroneously returns true for address fields" (object_reference.txt L2950–L2951), so do not gate code on it.

Apex DML

// Works — components
update new Contact(Id = cid, MailingCity = 'SF');

// Fails — "Compound fields are read-only. To update field values, modify the individual field components."
update new Contact(Id = cid, MailingAddress = new Address(...));

// Reading: assign the parent to a typed variable first. Dot notation
// straight through the parent field does not compile.
Address addr = acct.BillingAddress;   // System.Address
String city  = addr.city;             // == addr.getCity()
Location loc = acct.MyLocation__c;    // System.Location
Double lat   = loc.latitude;

// Writing a geolocation: the __Latitude__s / __Longitude__s components
w.Warehouse_Location__Latitude__s  = 37.775;
w.Warehouse_Location__Longitude__s = -122.418;

Address and Location are also standard object names. In Apex, "always use Schema.Address instead of Address" for the object and System.Address for the compound field type; the same disambiguation applies to System.Location vs Schema.Location (apexrefguide.txt L199187–L199190, L221921–L221924).

LWC UI API

@wire(getRecord) returns compound and components; display via {v.fields.MailingAddress.displayValue} or each component individually.

Common Patterns

Pattern: Address update from form

Collect form fields, assign to component fields on a new SObject, DML. When State and Country/Territory Picklists are on, write the -Code component; see references/metadata-examples.md §5 for the load-file column list and references/examples.md Example 1 for the batch shape.

Pattern: Geolocation proximity search

DISTANCE(location1, location2, 'unit') calculates the distance between two location values; GEOLOCATION(latitude, longitude) builds a location from coordinates and must be paired with DISTANCE. DISTANCE() is supported in SELECT, WHERE, and ORDER BY clauses; GEOLOCATION() is supported in WHERE and ORDER BY only. Neither is supported in GROUP BY. Use for store locators — see gotchas.md (Gotcha 6) for the four non-obvious query constraints and examples.md Example 2 for the working Apex pattern.

Pattern: Compute distance in Apex when SOQL cannot

DISTANCE/GEOLOCATION need a query. When both points are already in memory — a user's browser coordinates against a record you already hold — System.Location exposes the same maths without a second query: Location.newInstance(lat, lon), loc1.getDistance(loc2, 'mi'), and the static Location.getDistance(a, b, unit), all documented as "an approximation of the haversine formula" (apexrefguide.txt L221955–L221962). Use these instead of hand-rolling trigonometry; use SOQL DISTANCE whenever the filtering or sorting can happen in the database.

Pattern: Serialize compound to JSON

JSON.serialize(contact.MailingAddress) returns the compound object. Consuming code should use components, not the serialized blob as a key.

Decision Guidance

Recommended Workflow

1. Fill templates/compound-field-patterns-template.md: the compound fields in scope, the three org flags (State and Country/Territory Picklists, Custom Address Fields, Person Accounts), and every surface that reads or writes the field. Answer the Questions table above into it.
2. Resolve compound-vs-component per surface against the matrix in references/well-architected.md → Architectural Tradeoffs. Anything outside SOAP API, REST API, and Apex resolves to components.
3. If a new field is needed, take the XML from references/metadata-examples.md §1 (Location field), §2 (CustomAddressFieldSettings) or §3 (AddressSettings) — not from admin/custom-field-creation, which covers the non-compound CustomField elements.
4. Write the SOQL, the Apex reads and writes, and the Data Loader column mapping from §4–§6 of the same file. Keep the location field first in every DISTANCE call and the unit a literal.
5. Run python3 scripts/check_compound_field_patterns.py --manifest-dir force-app/main/default. ERROR findings (compound in WHERE, compound DML assignment, DISTANCE without a unit) block the deploy; WARN and INFO findings need a written reason.
6. Deploy with sf project deploy start --dry-run first, then verify with the describe call and the SOQL in §8–§9 — confirm MailingStateCode is populated, not just MailingState.
7. Walk references/gotchas.md against the change before sign-off; each gotcha names the surface it breaks and the org flag that triggers it.

Review Checklist

• [ ] No WHERE-clause filters on compound fields
• [ ] DML uses component fields only
• [ ] LWC rendering via UI API displayValue or explicit components
• [ ] Reports using compound columns where appropriate
• [ ] State & Country Picklists considered (adds -Code components)
• [ ] Person Account name semantics documented if Person Accounts enabled
• [ ] Proximity queries use DISTANCE in SOQL, or System.Location.getDistance when both points are already in memory — never hand-rolled trigonometry
• [ ] Validation rules and formulas reference components, not the compound (only ISBLANK, ISCHANGED, ISNULL accept a compound)
• [ ] Data Loader export mappings list components; no compound field is selected
• [ ] Location field XML carries scale and displayLocationInDecimal, and the object's field budget accounts for three fields per geolocation
• [ ] No Address / Location identifier ambiguity in Apex (System. vs Schema.)
• [ ] DISTANCE uses only > / < operators and a literal 'mi'/'km' unit (location field before GEOLOCATION)

Salesforce-Specific Gotchas

1. State & Country Picklists change components. Adds BillingStateCode / BillingCountryCode alongside text versions; DML requires the code if picklist is enabled.
2. Name on standard objects cannot be DML-assigned. Only on custom objects (where it's a plain text field anyway).
3. Serialized compound in JSON integrations is not round-trippable. Always map to components explicitly.
4. isFilterable() lies about address fields. The describe result reports true; SOQL rejects the filter. Do not build dynamic query builders on that flag.
5. A custom geolocation field is three fields against the org limit, one in the UI, and absent from Schema Builder and dashboards.

The full set with reproduction and avoidance steps is in references/gotchas.md.

Output Artifacts

Reference Files

Related Skills

• admin/custom-field-creation — the non-compound CustomField elements, the FieldType enum, and general field design; it owns the CustomField XML this skill only extends
• admin/data-model-documentation — how to document a compound field that counts as three against the limit (its gotcha 7)
• admin/validation-rules — why ISBLANK(BillingAddress) will not save, and the component-level rules to write instead (its "Compound Fields Cannot Be Used in a Validation Rule at All")
• admin/formula-fields — formula syntax and which field types are addressable
• data/soql-query-optimization — selectivity and index behaviour for the component filters this skill sends you to
• apex/soql-fundamentals — SOQL query patterns

Package files

• references/examples.md
• references/gotchas.md
• references/llm-anti-patterns.md
• references/metadata-examples.md
• references/well-architected.md
• templates/compound-field-patterns-template.md
• scripts/check_compound_field_patterns.py