PranavNagrecha/AwesomeSalesforceSkills / skills/admin/compound-field-patterns
compound-field-patterns
VerifiedCompound fields (Name, Address, Geolocation): SOQL access rules, DML semantics, component access in Apex/LWC, reporting column behavior, formula field restrictions. NOT for creating a new custom field — use admin/custom-field-creation. NOT for formula syntax and functions — use admin/formula-fields. Trigger keywords: BillingAddress, MailingAddress, ShippingAddress, StateCode, CountryCode, GeocodeAccuracy, Location field type, displayLocationInDecimal, __Latitude__s, __Longitude__s, DISTANCE, GEOLOCATION, Custom Address Fields, AddressSettings, System.Address, System.Location, Person Account name.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 19.1 KB |
| references/examples.md | markdown | 12.9 KB |
| references/gotchas.md | markdown | 23.2 KB |
| references/llm-anti-patterns.md | markdown | 6.1 KB |
| references/metadata-examples.md | markdown | 19.1 KB |
| references/well-architected.md | markdown | 14.8 KB |
| scripts/check_compound_field_patterns.pyexecutable | script | 16.9 KB |
| templates/compound-field-patterns-template.md | markdown | 3.5 KB |
references/metadata-examples.md
View on GitHub# Metadata Examples — Compound Field Patterns
Deployable metadata and queries for the three compound shapes. `admin/custom-field-creation` owns
the general `CustomField` element set (`label`, `required`, `description`, `trackHistory`, the
`FieldType` enum, the DX-vs-zip file forms); nothing below repeats it. What is here is only what
changes because the field is *compound*: the `Location` type and its two display elements, the two
org-level settings that create or reshape address components, and the query and load patterns that
have to address components instead of the compound.
## How to read it
- **A compound field is never created directly.** You create a `Location` custom field, or you
enable a feature that adds components to an existing standard address. There is no
`<type>Geolocation</type>` and no metadata element that names a compound.
- **`Location` is the type name.** The `FieldType` enum lists `Location (use for geolocation
fields)` (api_meta.txt L45760). `Geolocation` is not a valid value; neither is `GeoLocation`.
- **`scale` and `displayLocationInDecimal` are the two elements that matter here.** `scale` is
"the number of digits to the right of the decimal point in a number" (api_meta.txt
L43608–L43612). `displayLocationInDecimal` "indicates how the geolocation values of a custom
Location field appear in the user interface. If `true`, the geolocation values appear in decimal
notation. If `false`, the geolocation values appear as degrees, minutes, and seconds"
(api_meta.txt L43364–L43368).
- **`fullName` is object-qualified in a package-format file, bare in a DX-decomposed file.** The
guide's examples of the qualified form: `MyCustomObject__c.MyCustomField__c`,
`Account.MyAcctCustomField__c` (api_meta.txt L43222–L43226).
- **The two `.settings` files are org-wide and singular.** `AddressSettings` lives in
`Address.settings`, `CustomAddressFieldSettings` in `CustomAddressField.settings`; both are
retrieved and deployed under the manifest name `Settings`, and "there's only one settings file
for each settings component" (api_meta.txt L109609–L109611, L113894–L113897).
- **Every XML block below is a complete, well-formed document** — copy whole, do not splice.
---
## 1. Custom geolocation field — `Location`
`force-app/main/default/objects/Store__c/fields/Store_Location__c.field-meta.xml`
```xml
<?xml version="1.0" encoding="UTF-8"?>
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
<fullName>Store_Location__c</fullName>
<description>Geocoded position of the storefront. Written by the nightly geocoding job from the mailing address; never edited by hand. Consumed by the store-locator LWC via SOQL DISTANCE.</description>
<displayLocationInDecimal>true</displayLocationInDecimal>
<inlineHelpText>Latitude and longitude in decimal degrees. Blank means the address has not been geocoded yet.</inlineHelpText>
<label>Store Location</label>
<required>false</required>
<scale>5</scale>
<trackHistory>false</trackHistory>
<type>Location</type>
</CustomField>
```
The same field inside a package-format `objects/Store__c.object`, for a Metadata API zip deploy:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
<fields>
<fullName>Store_Location__c</fullName>
<displayLocationInDecimal>true</displayLocationInDecimal>
<label>Store Location</label>
<required>false</required>
<scale>5</scale>
<type>Location</type>
</fields>
</CustomObject>
```
What this one field costs and exposes:
| Consequence | Source |
|---|---|
| Three custom fields against the org limit — latitude, longitude, and one for internal use | object_reference.txt L2874–L2876 |
| Two queryable component fields: `Store_Location__Latitude__s`, `Store_Location__Longitude__s` | object_reference.txt L2915–L2917 |
| One read-only compound value, reachable from SOAP API, REST API, and Apex only | object_reference.txt L2651, L2913–L2914 |
| Not available in dashboards or Schema Builder; not supported in custom settings | object_reference.txt L2954–L2955 |
| Not an available custom field type on external objects | api_meta.txt L43233–L43245 |
`scale` is what decides precision on disk. Five decimal places of latitude is roughly a metre;
choose it deliberately, because widening `scale` later rewrites stored values.
---
## 2. Enabling custom address fields — `CustomAddressFieldSettings`
`force-app/main/default/settings/CustomAddressField.settings-meta.xml`
```xml
<?xml version="1.0" encoding="UTF-8"?>
<CustomAddressFieldSettings xmlns="http://soap.sforce.com/2006/04/metadata">
<enableCustomAddressField>true</enableCustomAddressField>
</CustomAddressFieldSettings>
```
This is the guide's own sample definition (api_meta.txt L113917–L113922), available in API version
55.0 and later. Read the field description before you deploy it: "Indicates whether the Address
Field Type is available for custom fields (`true`) or not (`false`). The default value is `false`.
Custom Address Fields can't be disabled. When `enableCustomAddressField` is set to `true`, you
can't change the value to `false`" (api_meta.txt L113903–L113909). Treat this as a one-way door in
every org it reaches, including sandboxes you refresh from.
Once it is on, `Address` is a valid `CustomField` `type` (api_meta.txt L45719) and the field
appears in Object Manager: "If you enabled Custom Address Fields, the Address field type is
available in Object Manager when you add a custom field" (object_reference.txt L2745–L2747). A
custom address field's `CountryCode` component "is always available, whether or not state and
country/territory picklists are enabled in your organization" — unlike a standard address, where
`CountryCode` and `StateCode` are picklist-gated (object_reference.txt L2705–L2722).
```xml
<?xml version="1.0" encoding="UTF-8"?>
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
<fullName>Site_Address__c</fullName>
<description>Physical address of the serviced site, distinct from the account's billing address.</description>
<label>Site Address</label>
<required>false</required>
<type>Address</type>
</CustomField>
```
<!-- UNVERIFIED (2026-09-04): the Metadata API guide names `Address` in the FieldType enum and the
Object Reference confirms the type appears in Object Manager once Custom Address Fields is enabled,
but neither file carries a sample CustomField definition of type Address. The four elements above
are the generic CustomField elements; any address-specific element (component labels, per-component
required flags) is documented only in the separate Custom Address Fields Developer Guide, which is
not in the extracted set. -->
The two guarantees custom address fields do **not** carry: `GeocodeAccuracy` — "like its parent,
the compound Address field, the `GeocodeAccuracy` field is only available for standard address
fields on standard objects" (object_reference.txt L2740–L2743) — and automatic geocoding, which
Salesforce provides only "for Account, Contact, Lead, and WorkOrder records" via the geo data
integration rule (object_reference.txt L2943–L2948).
---
## 3. State and country/territory picklists — `AddressSettings`
`force-app/main/default/settings/Address.settings-meta.xml`, trimmed from the guide's sample
(api_meta.txt L109751–L109826):
```xml
<?xml version="1.0" encoding="UTF-8"?>
<AddressSettings xmlns="http://soap.sforce.com/2006/04/metadata">
<countriesAndStates>
<countries>
<country>
<active>true</active>
<integrationValue>United States</integrationValue>
<isoCode>US</isoCode>
<label>United States</label>
<orgDefault>true</orgDefault>
<standard>true</standard>
<states>
<state>
<active>true</active>
<integrationValue>California</integrationValue>
<isoCode>CA</isoCode>
<label>California</label>
<standard>true</standard>
<visible>true</visible>
</state>
</states>
<visible>true</visible>
</country>
<country>
<active>true</active>
<integrationValue>Greenland</integrationValue>
<isoCode>GL</isoCode>
<label>Greenland</label>
<standard>true</standard>
<visible>false</visible>
</country>
</countries>
</countriesAndStates>
</AddressSettings>
```
`integrationValue` is the value integrations send and receive; `isoCode` is what
`MailingStateCode` stores; `visible` `false` with `active` `true` — the Greenland row — makes a
country available to the API but not to users in the UI. Available in API version 27.0 and later.
The guide is explicit about the ceiling: "You can use the Metadata API to edit existing states,
countries, and territories in state and country/territory picklists. You can't use the Metadata
API to create or delete new states, countries, or territories" (api_meta.txt L109630–L109633).
With Salesforce CLI the type name is `Settings:Address` (api_meta.txt L109624–L109626).
---
## 4. SOQL
```soql
-- (a) The compound value. SOAP API, REST API, and Apex only.
SELECT Name, BillingAddress FROM Account
-- (b) The components. Portable to API versions earlier than 30.0.
SELECT Name, BillingStreet, BillingCity, BillingState, BillingPostalCode,
BillingCountry, BillingLatitude, BillingLongitude
FROM Account
-- (c) A custom geolocation, compound then components.
SELECT Store_Location__c FROM Store__c
SELECT Store_Location__Latitude__s, Store_Location__Longitude__s FROM Store__c
-- (d) Proximity: DISTANCE in SELECT, WHERE, and ORDER BY, with a literal unit.
-- The location operand comes first; GEOLOCATION second.
SELECT Id, Name, DISTANCE(Store_Location__c, GEOLOCATION(37.775,-122.418), 'mi') dist
FROM Store__c
WHERE DISTANCE(Store_Location__c, GEOLOCATION(37.775,-122.418), 'mi') < 25
ORDER BY DISTANCE(Store_Location__c, GEOLOCATION(37.775,-122.418), 'mi')
LIMIT 10
-- (e) A standard address compound used as the location operand.
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
```
Queries (b), (d) and (e) are the guide's own samples (object_reference.txt L2764–L2768,
L2836–L2841, L2981–L2983). What the guide forbids, in the same words:
| Rejected | Rule | Source |
|---|---|---|
| `WHERE BillingAddress = :addr` | "Address fields can't be used in WHERE statements in SOQL. Address fields aren't filterable" | object_reference.txt L2950–L2951 |
| `WHERE DISTANCE(...) = 5`, `>= 5`, `<= 5` | "DISTANCE supports only the logical operators > and <, returning values within (<) or beyond (>) a specified radius" | object_reference.txt L2979 |
| `DISTANCE(GEOLOCATION(37.775,-122.418), Store_Location__c, 'km')` | "the geolocation field must precede the latitude and longitude coordinates" | object_reference.txt L2980–L2983 |
| `DISTANCE(Store_Location__c, GEOLOCATION(10,10), :units)` | "Apex bind variables aren't supported for the units parameter in the DISTANCE function" | object_reference.txt L2984–L2990 |
| `GROUP BY DISTANCE(...)` | "DISTANCE and GEOLOCATION are supported in WHERE and ORDER BY clauses in SOQL, but not in GROUP BY. DISTANCE is supported in SELECT clauses" | object_reference.txt L2969–L2970 |
---
## 5. Apex — reading and writing components
```apex
public with sharing class SiteAddressService {
// READ: assign the parent field to a typed variable, then read components.
// Dot notation straight through the parent field does not compile.
public static Map<String, Object> describe(Id accountId) {
Account acct = [
SELECT Id, BillingAddress, Store_Location__c
FROM Account WHERE Id = :accountId WITH USER_MODE LIMIT 1
];
System.Address addr = acct.BillingAddress;
System.Location loc = acct.Store_Location__c;
return new Map<String, Object>{
'city' => addr == null ? null : addr.city, // == addr.getCity()
'state' => addr == null ? null : addr.state,
// getStateCode() returns null unless state/country picklists are enabled
'stateCode' => addr == null ? null : addr.stateCode,
'accuracy' => addr == null ? null : addr.getGeocodeAccuracy(),
'lat' => loc == null ? null : loc.latitude,
'lon' => loc == null ? null : loc.longitude
};
}
// WRITE: components only. Assigning acct.BillingAddress does not save.
public static void relocate(Id accountId, Decimal lat, Decimal lon, String stateIso) {
Account acct = new Account(Id = accountId);
acct.BillingStateCode = stateIso; // 'CA', not 'California'
acct.Store_Location__Latitude__s = lat;
acct.Store_Location__Longitude__s = lon;
update acct;
}
// In-memory distance, when both points are already loaded and a query
// would be a second round trip. Same approximation the platform uses.
public static Double milesBetween(Account a, Decimal lat, Decimal lon) {
System.Location here = System.Location.newInstance(lat, lon);
System.Location there = a.Store_Location__c;
return there == null ? null : there.getDistance(here, 'mi');
}
}
```
`System.Address` and `System.Location` are spelled out on purpose: "'Address' in Salesforce can
also refer to the Address standard object… always use `Schema.Address` instead of `Address`… you
can differentiate between the two by using `System.Address` for the field and `Schema.Address` for
the object" (apexrefguide.txt L199187–L199190); the identical warning covers `Location`
(apexrefguide.txt L221921–L221924). `getDistance` is documented as using "an approximation of the
haversine formula and the specified unit", with `mi` or `km` as the unit (apexrefguide.txt
L221955–L221962, L221983–L221996).
---
## 6. Data Loader and reports
**Data Loader export.** Map component fields, one column each. The compound is not exportable:
"If you select compound fields for export in the Data Loader, they cause error messages. To export
values, use individual field components" (salesforce_data_loader.txt L918–L919, repeating
object_reference.txt L2931–L2932).
A CSV header for a Contact mailing-address load, State and Country/Territory Picklists **enabled**:
```csv
Id,MailingStreet,MailingCity,MailingStateCode,MailingPostalCode,MailingCountryCode
003xx0000012ABCAA2,"1 Market St",San Francisco,CA,94105,US
```
The same load with picklists **disabled** — the code columns do not exist:
```csv
Id,MailingStreet,MailingCity,MailingState,MailingPostalCode,MailingCountry
003xx0000012ABCAA2,"1 Market St",San Francisco,California,94105,United States
```
There is no `MailingAddress` column in either file, and no `MailingGeocodeAccuracy` column in a
load file — the accuracy subfield "is populated only when an address is geocoded", by the geocoding
service, not by your CSV (object_reference.txt L2948).
**Reports.** Add component columns, not the compound. The compound value is unreachable from every
UI surface — "the compound versions of fields aren't accessible anywhere in the Salesforce user
interface" (object_reference.txt L2913–L2914) — so a report shows Billing City, Billing
State/Province, Billing Zip/Postal Code as separate columns, each independently sortable and
filterable. Geolocation fields specifically "aren't available in dashboards or Schema Builder"
(object_reference.txt L2954–L2955).
**Limits.** The Salesforce App Limits Cheat Sheet carries no compound-field or geolocation entry;
the only numeric limit that applies is the org custom-field cap, against which one geolocation
field counts three (object_reference.txt L2874–L2876).
---
## 7. package.xml
```xml
<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
<types>
<members>Store__c.Store_Location__c</members>
<members>Account.BillingStateCode</members>
<name>CustomField</name>
</types>
<types>
<members>Address</members>
<members>CustomAddressField</members>
<name>Settings</name>
</types>
<version>62.0</version>
</Package>
```
The `CustomField` members use the object-qualified form the guide documents for retrieving named
fields (api_meta.txt L43258–L43266). Both settings go under the single `Settings` name
(api_meta.txt L109605–L109607). The wildcard `*` does not work for feature settings — "the
wildcard applies only when retrieving all settings, not for an individual setting" (api_meta.txt
L113946–L113949) — so list them.
---
## 8. Retrieve and deploy
```bash
# Pull the field and both settings before changing anything.
sf project retrieve start \
--metadata "CustomField:Store__c.Store_Location__c" \
--metadata "Settings:Address" \
--metadata "Settings:CustomAddressField" \
--target-org my-sandbox
# Validate. Never skip this for AddressSettings or CustomAddressFieldSettings —
# enableCustomAddressField cannot be set back to false once deployed.
sf project deploy start \
--source-dir force-app/main/default/objects/Store__c \
--source-dir force-app/main/default/settings \
--dry-run \
--target-org production
sf project deploy start \
--source-dir force-app/main/default/objects/Store__c \
--source-dir force-app/main/default/settings \
--target-org production
```
---
## 9. Verification
Confirm the shape the org actually has, not the shape you deployed.
```bash
# The Location field: type, scale, and the two component fields it created.
sf sobject describe --sobject Store__c --target-org my-sandbox --json \
| jq '.result.fields[]
| select(.name | test("Store_Location"))
| {name, type, scale, filterable, createable, updateable}'
# The address components: does StateCode exist, i.e. are picklists on?
sf sobject describe --sobject Account --target-org my-sandbox --json \
| jq '.result.fields[] | select(.name | startswith("Billing")) | {name, type, updateable}'
```
Expect exactly one row of `type: "location"` (the compound, `updateable: false`) plus
`Store_Location__Latitude__s` and `Store_Location__Longitude__s` as `double` and updateable. A
`BillingStateCode` row present means picklists are enabled and your writes must target it; absent
means write `BillingState`.
Then confirm the data landed on the authoritative column, not just the text one:
```soql
SELECT Id, BillingState, BillingStateCode, BillingCountry, BillingCountryCode,
BillingLatitude, BillingLongitude
FROM Account
WHERE BillingStateCode = NULL AND BillingState != NULL
LIMIT 50
```
Rows returned means something wrote the text component directly while picklists were enabled —
the failure mode in gotcha 1. Zero rows is the pass condition.
`sf` flag spellings above follow the same CLI surface used in `admin/custom-field-creation`
§11–§12; re-check with `sf project deploy start --help` if your CLI is older.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |