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/llm-anti-patterns.md
View on GitHub# LLM Anti-Patterns — Compound Field Patterns
Common mistakes AI coding assistants make when working with Name/Address/Geolocation compound fields.
## Anti-Pattern 1: Filtering WHERE clause by compound field
**What the LLM generates:** `SELECT Id FROM Account WHERE BillingAddress = :address`
**Why it happens:** Model treats compound like a regular field.
**Correct pattern:**
```
Filter by components:
SELECT Id FROM Account
WHERE BillingCity = :city AND BillingState = :state AND BillingPostalCode = :zip
Compound fields are not queryable in WHERE (except DISTANCE on Geolocation).
```
**Detection hint:** SOQL `WHERE <Address field name> =` where the field is a known compound (BillingAddress, MailingAddress, ShippingAddress, OtherAddress).
---
## Anti-Pattern 2: Assigning the compound in DML
**What the LLM generates:**
```
c.MailingAddress = new Address(...);
update c;
```
**Why it happens:** Model mirrors the read pattern for writes.
**Correct pattern:**
```
Compound fields are read-only for DML. Assign components:
c.MailingStreet = '1 Main St';
c.MailingCity = 'SF';
c.MailingState = 'CA';
update c;
```
**Detection hint:** Apex assigning `record.<name>Address = ...` or `record.Name = ...` on standard objects.
---
## Anti-Pattern 3: Updating Name on a standard object
**What the LLM generates:** `acc.Name = 'Acme Inc'; update acc;` — fine on Account but `contact.Name = 'Jane Doe';` on Contact fails.
**Why it happens:** Model generalizes from one object to all.
**Correct pattern:**
```
Contact.Name is compound (FirstName + LastName + Salutation) and
cannot be set directly. Assign components:
c.FirstName = 'Jane'; c.LastName = 'Doe';
Account.Name and Custom__c.Name are plain text and can be assigned.
```
**Detection hint:** Apex assigning `Contact.Name`, `Lead.Name`, `Opportunity.Name` (Opportunity.Name IS text — tricky), `User.Name`.
---
## Anti-Pattern 4: Computing haversine distance in Apex
**What the LLM generates:** A 40-line Apex method computing great-circle distance between two geolocations.
**Why it happens:** Model doesn't know about the SOQL DISTANCE function.
**Correct pattern:**
```
SELECT Id, Name, DISTANCE(Location__c, GEOLOCATION(:lat, :lon), 'km') dist
FROM Store__c
ORDER BY DISTANCE(Location__c, GEOLOCATION(:lat, :lon), 'km')
LIMIT 10
DISTANCE works in SELECT, ORDER BY, and WHERE. Platform-optimized.
```
**Detection hint:** Apex class with `Math.cos`, `Math.sin`, `Math.sqrt` and latitude/longitude arguments.
---
## Anti-Pattern 5: Round-tripping address JSON via compound serialization
**What the LLM generates:** `JSON.serialize(c.MailingAddress)` sent to an API; API response deserialized back into `c.MailingAddress`.
**Why it happens:** Model assumes compound serialization is round-trippable.
**Correct pattern:**
```
Map to/from component fields explicitly in integration code:
{
"street": c.MailingStreet,
"city": c.MailingCity,
...
}
The compound's serialized form is not a documented contract and may
drop fields (geocode, stateCode) silently. Explicit mapping is stable.
```
**Detection hint:** Integration code serializing a compound field directly and deserializing back into the compound.
---
## Anti-Pattern 6: Using `=` with DISTANCE or binding the DISTANCE unit
**What the LLM generates:**
```
// Equality on an approximate distance
WHERE DISTANCE(Location__c, GEOLOCATION(:lat, :lon), 'mi') = 5
// Or binding the unit parameter like any other value
String unit = 'mi';
[SELECT Id FROM Store__c
WHERE DISTANCE(Location__c, GEOLOCATION(:lat, :lon), :unit) < 25]
```
**Why it happens:** Model treats DISTANCE like a normal numeric field
(so `=` seems valid) and assumes every SOQL argument is bindable.
**Correct pattern:**
```
DISTANCE in WHERE supports only > and < (within / beyond a radius) — there is
no =, >=, or <= because the value is approximate. The unit must be a literal
'mi' or 'km'; Apex bind variables aren't supported for the units parameter
(coordinate binds like GEOLOCATION(:lat, :lon) are fine). The location field
must come first and GEOLOCATION second.
WHERE DISTANCE(Location__c, GEOLOCATION(:lat, :lon), 'mi') < 5
```
**Detection hint:** `DISTANCE(...)` compared with `=`, `>=`, or `<=`; a bind
variable (`:unit`) in the third DISTANCE argument; or `GEOLOCATION(...)`
appearing before the location field.
---
## Anti-Pattern 7: Building a dynamic query on `isFilterable()`, or reading a component through the parent field
**What the LLM generates:**
```apex
// (a) A "safe" dynamic filter builder
for (Schema.SObjectField f : Account.SObjectType.getDescribe().fields.getMap().values()) {
if (f.getDescribe().isFilterable()) {
filterableFields.add(f.getDescribe().getName()); // BillingAddress sails through
}
}
// (b) Reading a component by chaining off the record
String city = acct.BillingAddress.City;
Address addr = acct.BillingAddress; // ambiguous with Schema.Address
```
**Why it happens:** Both look like the platform is telling the truth.
`isFilterable()` is the documented way to ask whether a field can go in
a `WHERE` clause, and dot-chaining is how every other nested value in
Apex is read. The model has no signal that either is special-cased.
**Correct pattern:**
```apex
// (a) Exclude compounds explicitly; the describe flag is wrong for them.
// "Address fields aren't filterable, but the isFilterable() method of the
// DescribeFieldResult Apex class erroneously returns true for address fields"
// (object_reference.txt L2950-L2951)
Schema.DescribeFieldResult d = f.getDescribe();
if (d.isFilterable() && d.getSOAPType() != Schema.SOAPType.ADDRESS) { ... }
// (b) Assign the parent field to a typed local first, and namespace it.
// "You can't use dot notation to access compound fields' subfields directly
// on the parent field" (apexrefguide.txt L199180-L199182)
System.Address addr = acct.BillingAddress;
String city = addr.city;
```
**Detection hint:** `isFilterable()` used as the only gate in a query
builder; `.BillingAddress.`, `.MailingAddress.`, `.ShippingAddress.` or
`__c.latitude` chained off a record variable; a bare `Address` or
`Location` local declaration in a class that also touches the Address or
Location standard object.
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 |