@salesforce/afv-skills 1.22.0 → 1.24.0

package/skills/querying-soql/references/anti-patterns.md

@@ -1,348 +0,0 @@
-<!-- Parent: querying-soql/SKILL.md -->
-# SOQL Anti-Patterns: What to Avoid
-
-A catalog of common SOQL mistakes and their solutions. Avoiding these patterns will help you stay within governor limits, improve query performance, and write more maintainable code.
-
----
-
-## Anti-Pattern #1: SOQL Inside Loops
-
-**The Problem**: Executing queries inside a loop quickly exhausts the 100 SOQL query limit.
-
-```apex
-// ❌ ANTI-PATTERN: Query per record
-for (Contact c : Trigger.new) {
-    Account a = [SELECT Name FROM Account WHERE Id = :c.AccountId];
-    c.Account_Name__c = a.Name;
-}
-// 200 contacts = 200 queries = LIMIT EXCEEDED
-```
-
-**The Solution**: Query once, use a Map for lookups.
-
-```apex
-// ✅ CORRECT: Single query with Map lookup
-Set<Id> accountIds = new Set<Id>();
-for (Contact c : Trigger.new) {
-    accountIds.add(c.AccountId);
-}
-
-Map<Id, Account> accountMap = new Map<Id, Account>(
-    [SELECT Id, Name FROM Account WHERE Id IN :accountIds]
-);
-
-for (Contact c : Trigger.new) {
-    Account a = accountMap.get(c.AccountId);
-    if (a != null) {
-        c.Account_Name__c = a.Name;
-    }
-}
-// 200 contacts = 1 query = SAFE
-```
-
-**Key Insight**: Collect IDs first, query once with `IN` clause, then use Map for O(1) lookups.
-
----
-
-## Anti-Pattern #2: Non-Selective WHERE Clauses
-
-**The Problem**: Queries on non-indexed fields cause full table scans, which fail on large objects (100k+ records).
-
-```apex
-// ❌ ANTI-PATTERN: Non-selective filter
-SELECT Id FROM Lead WHERE Status = 'Open'
-// Status is not indexed - scans ALL Lead records
-```
-
-**The Solution**: Add an indexed field to make the query selective.
-
-```apex
-// ✅ CORRECT: Add indexed field filter
-SELECT Id FROM Lead
-WHERE Status = 'Open'
-AND CreatedDate = LAST_N_DAYS:30
-// CreatedDate is indexed - uses index
-
-// ✅ ALTERNATIVE: Use OwnerId (indexed)
-SELECT Id FROM Lead
-WHERE Status = 'Open'
-AND OwnerId = :UserInfo.getUserId()
-```
-
-**Indexed Fields** (Always use these in WHERE):
-- `Id`, `Name`, `OwnerId`, `CreatedDate`, `LastModifiedDate`
-- `RecordTypeId`, External ID fields, Master-Detail fields
-- Standard indexed fields: `Account.AccountNumber`, `Contact.Email`, `Case.CaseNumber`
-
----
-
-## Anti-Pattern #3: Leading Wildcards
-
-**The Problem**: `LIKE '%value'` cannot use indexes and scans all records.
-
-```apex
-// ❌ ANTI-PATTERN: Leading wildcard
-SELECT Id FROM Account WHERE Name LIKE '%Corporation'
-// Cannot use index - full table scan
-```
-
-**The Solution**: Use trailing wildcards or exact matches.
-
-```apex
-// ✅ CORRECT: Trailing wildcard (uses index)
-SELECT Id FROM Account WHERE Name LIKE 'Acme%'
-
-// ✅ CORRECT: Exact match
-SELECT Id FROM Account WHERE Name = 'Acme Corporation'
-
-// ✅ CORRECT: Contains check (if absolutely necessary)
-// Do the filtering in Apex after a selective query
-List<Account> allAccounts = [
-    SELECT Id, Name FROM Account
-    WHERE CreatedDate = THIS_YEAR
-];
-List<Account> filtered = new List<Account>();
-for (Account a : allAccounts) {
-    if (a.Name.contains('Corporation')) {
-        filtered.add(a);
-    }
-}
-```
-
----
-
-## Anti-Pattern #4: Negative Operators
-
-**The Problem**: `!=`, `NOT IN`, `NOT LIKE` often prevent index usage.
-
-```apex
-// ❌ ANTI-PATTERN: Negative operators
-SELECT Id FROM Opportunity WHERE StageName != 'Closed Lost'
-SELECT Id FROM Contact WHERE AccountId NOT IN :excludedIds
-```
-
-**The Solution**: Query for what you want, not what you don't want.
-
-```apex
-// ✅ CORRECT: Positive filter with specific values
-SELECT Id FROM Opportunity
-WHERE StageName IN ('Prospecting', 'Qualification', 'Proposal', 'Negotiation')
-
-// ✅ CORRECT: Use a formula field for complex exclusions
-// Create IsExcluded__c formula, then:
-SELECT Id FROM Contact WHERE IsExcluded__c = false
-```
-
----
-
-## Anti-Pattern #5: Querying for NULL
-
-**The Problem**: `WHERE Field = null` is non-selective and scans all records.
-
-```apex
-// ❌ ANTI-PATTERN: Null check in WHERE
-SELECT Id FROM Contact WHERE Email = null
-// Non-selective - scans all contacts
-```
-
-**The Solution**: Combine with selective filters or redesign data model.
-
-```apex
-// ✅ CORRECT: Add selective filter
-SELECT Id FROM Contact
-WHERE Email = null
-AND CreatedDate = LAST_N_DAYS:30
-
-// ✅ BETTER: Use a checkbox field
-// Create HasEmail__c formula checkbox
-SELECT Id FROM Contact WHERE HasEmail__c = false
-```
-
----
-
-## Anti-Pattern #6: SELECT * (All Fields)
-
-**The Problem**: Querying all fields wastes resources and can hit heap limits.
-
-```apex
-// ❌ ANTI-PATTERN: Selecting everything
-SELECT FIELDS(ALL) FROM Account LIMIT 200
-// Loads ALL fields into memory
-
-// ❌ ANTI-PATTERN: Listing every field manually
-SELECT Id, Name, Description, BillingStreet, BillingCity,
-       BillingState, BillingPostalCode, BillingCountry, ...
-FROM Account
-```
-
-**The Solution**: Query only the fields you need.
-
-```apex
-// ✅ CORRECT: Minimal field selection
-SELECT Id, Name, Industry FROM Account
-
-// ✅ FOR DISPLAY: Just display fields
-SELECT Id, Name FROM Account
-
-// ✅ FOR PROCESSING: Just processing fields
-SELECT Id, Status__c, ProcessedDate__c FROM Account
-```
-
----
-
-## Anti-Pattern #7: No LIMIT on Queries
-
-**The Problem**: Unbounded queries can return 50,000 records and consume heap memory.
-
-```apex
-// ❌ ANTI-PATTERN: No limit
-SELECT Id, Name FROM Account
-// Could return 50,000 records!
-
-// ❌ ANTI-PATTERN: Excessive limit
-SELECT Id, Name FROM Account LIMIT 50000
-```
-
-**The Solution**: Use appropriate limits for your use case.
-
-```apex
-// ✅ CORRECT: Reasonable limit for UI display
-SELECT Id, Name FROM Account LIMIT 200
-
-// ✅ CORRECT: Pagination
-SELECT Id, Name FROM Account
-ORDER BY Name
-LIMIT 50 OFFSET 0
-
-// ✅ CORRECT: Single record lookup
-SELECT Id, Name FROM Account WHERE Name = 'Acme' LIMIT 1
-
-// ✅ CORRECT: Existence check
-SELECT Id FROM Account WHERE Name = 'Acme' LIMIT 1
-// In Apex: if (!results.isEmpty()) { /* exists */ }
-```
-
----
-
-## Anti-Pattern #8: Deep Relationship Traversal
-
-**The Problem**: Deep nesting (>3 levels) hurts performance and readability.
-
-```apex
-// ❌ ANTI-PATTERN: Deep traversal
-SELECT Id,
-       Account.Owner.Manager.Department.Name
-FROM Contact
-// 4 levels deep - hard to maintain, performance hit
-```
-
-**The Solution**: Flatten queries or use multiple queries.
-
-```apex
-// ✅ CORRECT: Flatten to 1-2 levels
-SELECT Id, Account.Name, Account.OwnerId FROM Contact
-
-// Then query Owner separately if needed
-Map<Id, User> owners = new Map<Id, User>(
-    [SELECT Id, ManagerId FROM User WHERE Id IN :ownerIds]
-);
-```
-
----
-
-## Anti-Pattern #9: Unfiltered Subqueries
-
-**The Problem**: Child subqueries without filters can return massive datasets.
-
-```apex
-// ❌ ANTI-PATTERN: Unfiltered subquery
-SELECT Id,
-       (SELECT Id FROM Contacts),
-       (SELECT Id FROM Opportunities)
-FROM Account
-// Could return thousands of child records per account
-```
-
-**The Solution**: Always filter and limit subqueries.
-
-```apex
-// ✅ CORRECT: Filtered and limited subqueries
-SELECT Id,
-       (SELECT Id, Name FROM Contacts
-        WHERE IsActive__c = true
-        LIMIT 5),
-       (SELECT Id, Name FROM Opportunities
-        WHERE StageName != 'Closed Lost'
-        LIMIT 5)
-FROM Account
-WHERE Industry = 'Technology'
-```
-
----
-
-## Anti-Pattern #10: Formula Fields in WHERE
-
-**The Problem**: Formula fields are not indexed and require full table scans.
-
-```apex
-// ❌ ANTI-PATTERN: Filter on formula field
-SELECT Id FROM Opportunity
-WHERE Days_Since_Created__c > 30
-// Formula field - cannot use index
-```
-
-**The Solution**: Use the underlying indexed field.
-
-```apex
-// ✅ CORRECT: Use base field
-SELECT Id FROM Opportunity
-WHERE CreatedDate < LAST_N_DAYS:30
-
-// ✅ ALTERNATIVE: Store computed value in regular field
-// Use workflow/flow to update a Number field
-SELECT Id FROM Opportunity
-WHERE Days_Open__c > 30
-```
-
----
-
-## Quick Reference: Selectivity Rules
-
-```
-A filter is SELECTIVE when:
-├── Uses an indexed field, AND
-├── Returns < 10% of first million records, OR
-├── Returns < 5% of records beyond first million
-└── Absolute max: 333,333 records (1M / 3)
-```
-
-**Always Indexed Fields**:
-- `Id`, `Name`, `OwnerId`, `CreatedDate`, `LastModifiedDate`
-- `RecordTypeId`, External ID fields, Master-Detail relationship fields
-
-**Request Custom Index**: Contact Salesforce Support with:
-- Object name and field API name
-- Sample SOQL query
-- Cardinality (unique values count)
-- Business justification
-
----
-
-## Testing Checklist
-
-Before deploying SOQL to production:
-
-1. [ ] Run Query Plan tool (Developer Console or CLI)
-2. [ ] Verify `LeadingOperationType` is "Index" not "TableScan"
-3. [ ] Test with 200+ records in trigger context
-4. [ ] Verify query count stays under 100 per transaction
-5. [ ] Check heap usage for large result sets
-
-```bash
-# CLI Query Plan
-sf data query \
-  --query "SELECT Id FROM Account WHERE Name = 'Test'" \
-  --target-org my-org \
-  --use-tooling-api \
-  --plan
-```

package/skills/querying-soql/references/cli-commands.md

@@ -1,358 +0,0 @@
-<!-- Parent: querying-soql/SKILL.md -->
-# Salesforce CLI SOQL Commands
-
-## Quick Reference
-
-| Task | Command |
-|------|---------|
-| Run query | `sf data query --query "SELECT..."` |
-| JSON output | `sf data query --query "..." --json` |
-| CSV output | `sf data query --query "..." --result-format csv` |
-| Bulk export | `sf data export bulk --query "SELECT..." --target-org alias` |
-| Query plan | `sf api request rest '/query/?explain=<SOQL>' --target-org alias` |
-
----
-
-## Basic Queries
-
-### Run a Query
-
-```bash
-sf data query \
-  --query "SELECT Id, Name, Industry FROM Account LIMIT 10" \
-  --target-org my-sandbox
-```
-
-### Query with Filters
-
-```bash
-sf data query \
-  --query "SELECT Id, Name FROM Account WHERE Industry = 'Technology'" \
-  --target-org my-sandbox
-```
-
-### Query Relationships
-
-```bash
-# Child-to-parent
-sf data query \
-  --query "SELECT Id, Name, Account.Name FROM Contact LIMIT 10" \
-  --target-org my-sandbox
-
-# Parent-to-child
-sf data query \
-  --query "SELECT Id, Name, (SELECT Id, Name FROM Contacts) FROM Account LIMIT 5" \
-  --target-org my-sandbox
-```
-
----
-
-## Output Formats
-
-### Human-Readable (Default)
-
-```bash
-sf data query \
-  --query "SELECT Id, Name FROM Account LIMIT 5" \
-  --target-org my-sandbox
-```
-
-### JSON
-
-```bash
-sf data query \
-  --query "SELECT Id, Name FROM Account LIMIT 5" \
-  --target-org my-sandbox \
-  --json
-```
-
-### CSV
-
-```bash
-sf data query \
-  --query "SELECT Id, Name, Industry FROM Account" \
-  --target-org my-sandbox \
-  --result-format csv > accounts.csv
-```
-
-### Direct to File
-
-```bash
-sf data query \
-  --query "SELECT Id, Name, Industry FROM Account" \
-  --target-org my-sandbox \
-  --result-format csv \
-  --output-file accounts.csv
-```
-
----
-
-## Bulk Data Export
-
-For large result sets (> 2,000 records), use the dedicated bulk export command:
-
-```bash
-# Export to CSV (default)
-sf data export bulk \
-  --query "SELECT Id, Name FROM Account" \
-  --target-org my-sandbox \
-  --output-file accounts.csv
-
-# Export as JSON
-sf data export bulk \
-  --query "SELECT Id, Name FROM Account" \
-  --target-org my-sandbox \
-  --output-file accounts.json \
-  --result-format json
-```
-
-> **Note**: `--bulk` and `--wait` flags on `sf data query` were removed in v2.87.7. Use `sf data export bulk` instead.
-
----
-
-## Query Plan Analysis
-
-Analyze query performance before running:
-
-```bash
-sf data query \
-  --query "SELECT Id FROM Account WHERE Name = 'Acme'" \
-  --target-org my-sandbox \
-  --use-tooling-api \
-  --plan
-```
-
-### Understanding Query Plan Output
-
-```json
-{
-  "plans": [{
-    "cardinality": 50,           // Estimated rows returned
-    "fields": ["Name"],          // Fields used for filtering
-    "leadingOperationType": "Index",  // Index = good, TableScan = bad
-    "relativeCost": 0.1,         // Lower is better
-    "sobjectCardinality": 10000, // Total records in object
-    "sobjectType": "Account"
-  }]
-}
-```
-
-**Key Indicators:**
-- `leadingOperationType: "Index"` = Query uses index (good)
-- `leadingOperationType: "TableScan"` = Full table scan (bad for large tables)
-- `relativeCost < 1` = Efficient query
-- `cardinality` = Expected number of results
-
----
-
-## Tooling API Queries
-
-Query metadata objects:
-
-```bash
-# Query ApexClass
-sf data query \
-  --query "SELECT Id, Name, Body FROM ApexClass WHERE Name = 'MyController'" \
-  --target-org my-sandbox \
-  --use-tooling-api
-
-# Query CustomField
-sf data query \
-  --query "SELECT Id, DeveloperName, TableEnumOrId FROM CustomField WHERE TableEnumOrId = 'Account'" \
-  --target-org my-sandbox \
-  --use-tooling-api
-```
-
----
-
-## Query from File
-
-Store query in file and execute:
-
-```bash
-# Create query file
-echo "SELECT Id, Name FROM Account WHERE Industry = 'Technology'" > query.soql
-
-# Execute from file
-sf data query \
-  --file query.soql \
-  --target-org my-sandbox
-```
-
----
-
-## Useful Patterns
-
-### Get Record Count
-
-```bash
-sf data query \
-  --query "SELECT COUNT() FROM Account" \
-  --target-org my-sandbox
-```
-
-### Export to File
-
-```bash
-# CSV export
-sf data query \
-  --query "SELECT Id, Name, Industry, Phone FROM Account" \
-  --target-org my-sandbox \
-  --result-format csv > accounts.csv
-
-# JSON export
-sf data query \
-  --query "SELECT Id, Name, Industry FROM Account" \
-  --target-org my-sandbox \
-  --json > accounts.json
-```
-
-### Query with jq Processing
-
-```bash
-# Get just the names
-sf data query \
-  --query "SELECT Name FROM Account LIMIT 10" \
-  --target-org my-sandbox \
-  --json | jq -r '.result.records[].Name'
-
-# Count records
-sf data query \
-  --query "SELECT Id FROM Account" \
-  --target-org my-sandbox \
-  --json | jq '.result.totalSize'
-
-# Filter in shell
-sf data query \
-  --query "SELECT Id, Name, Industry FROM Account" \
-  --target-org my-sandbox \
-  --json | jq '.result.records[] | select(.Industry == "Technology")'
-```
-
-### Query with Dates
-
-```bash
-# Records created today
-sf data query \
-  --query "SELECT Id, Name FROM Account WHERE CreatedDate = TODAY" \
-  --target-org my-sandbox
-
-# Records from last 30 days
-sf data query \
-  --query "SELECT Id, Name FROM Account WHERE CreatedDate = LAST_N_DAYS:30" \
-  --target-org my-sandbox
-```
-
-### Aggregate Queries
-
-```bash
-# Count by industry
-sf data query \
-  --query "SELECT Industry, COUNT(Id) FROM Account GROUP BY Industry" \
-  --target-org my-sandbox
-
-# Sum of amounts
-sf data query \
-  --query "SELECT SUM(Amount) FROM Opportunity WHERE StageName = 'Closed Won'" \
-  --target-org my-sandbox
-```
-
----
-
-## Troubleshooting
-
-### Query Timeout
-
-For long-running queries, export via bulk API:
-
-```bash
-sf data export bulk \
-  --query "SELECT Id, Name FROM Account" \
-  --target-org my-sandbox \
-  --output-file results.csv
-```
-
-### Too Many Results
-
-Add LIMIT or filter:
-
-```bash
-# With limit
-sf data query \
-  --query "SELECT Id, Name FROM Account LIMIT 1000" \
-  --target-org my-sandbox
-
-# With filter
-sf data query \
-  --query "SELECT Id, Name FROM Account WHERE CreatedDate = THIS_YEAR" \
-  --target-org my-sandbox
-```
-
-### Non-Selective Query Error
-
-Add indexed field to WHERE:
-
-```bash
-# Add CreatedDate filter (indexed)
-sf data query \
-  --query "SELECT Id FROM Lead WHERE Status = 'Open' AND CreatedDate = LAST_N_DAYS:90" \
-  --target-org my-sandbox
-```
-
-### Permission Errors
-
-Check field-level security:
-
-```bash
-# Query accessible fields only
-sf data query \
-  --query "SELECT Id, Name FROM Account" \
-  --target-org my-sandbox
-```
-
----
-
-## Integration with Other Tools
-
-### Pipe to File
-
-```bash
-sf data query \
-  --query "SELECT Id, Name FROM Account" \
-  --target-org my-sandbox \
-  --result-format csv | tee accounts.csv
-```
-
-### Use in Scripts
-
-```bash
-#!/bin/bash
-
-ORG=${1:-"my-sandbox"}
-
-# Get count
-COUNT=$(sf data query \
-  --query "SELECT COUNT() FROM Account" \
-  --target-org $ORG \
-  --json | jq -r '.result.totalSize')
-
-echo "Total accounts: $COUNT"
-
-# Get top accounts
-sf data query \
-  --query "SELECT Name, AnnualRevenue FROM Account ORDER BY AnnualRevenue DESC LIMIT 10" \
-  --target-org $ORG
-```
-
-### Compare Orgs
-
-```bash
-#!/bin/bash
-
-PROD_COUNT=$(sf data query --query "SELECT COUNT() FROM Account" --target-org prod --json | jq '.result.totalSize')
-SANDBOX_COUNT=$(sf data query --query "SELECT COUNT() FROM Account" --target-org sandbox --json | jq '.result.totalSize')
-
-echo "Production accounts: $PROD_COUNT"
-echo "Sandbox accounts: $SANDBOX_COUNT"
-echo "Difference: $((PROD_COUNT - SANDBOX_COUNT))"
-```