@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/querying-soql/assets/bulkified-query-pattern.cls

@@ -0,0 +1,280 @@
+/**
+ * Bulkified Query Patterns
+ *
+ * This file demonstrates the correct patterns for querying related data
+ * in bulk operations (triggers, batches, etc.) without hitting governor limits.
+ *
+ * Key Pattern: Collect IDs first, query once, use Map for O(1) lookups.
+ *
+ * @see https://www.apexhours.com/bulkification-of-apex-triggers/
+ * @see https://medium.com/@saurabh.samirs/salesforce-apex-triggers-5-bulkification-patterns-to-avoid-soql-dml-limits-f4e9c8bbfb3a
+ */
+
+// ═══════════════════════════════════════════════════════════════════════════
+// PATTERN 1: Simple Map Lookup (Parent Record Access)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * ❌ ANTI-PATTERN: Query inside loop
+ * This code will fail with "Too many SOQL queries: 101" for 101+ records
+ */
+public class AntiPatternExample {
+    public void processContacts_WRONG(List<Contact> contacts) {
+        for (Contact c : contacts) {
+            // ❌ QUERY IN LOOP - will hit governor limit!
+            Account a = [SELECT Name FROM Account WHERE Id = :c.AccountId];
+            c.Description = 'Account: ' + a.Name;
+        }
+    }
+}
+
+/**
+ * ✅ CORRECT PATTERN: Bulk query with Map lookup
+ * Uses 1 query regardless of record count
+ */
+public class BulkPatternExample {
+    public void processContacts_CORRECT(List<Contact> contacts) {
+        // Step 1: Collect all parent IDs
+        Set<Id> accountIds = new Set<Id>();
+        for (Contact c : contacts) {
+            if (c.AccountId != null) {
+                accountIds.add(c.AccountId);
+            }
+        }
+
+        // Step 2: Single bulk query
+        Map<Id, Account> accountMap = new Map<Id, Account>([
+            SELECT Id, Name
+            FROM Account
+            WHERE Id IN :accountIds
+            WITH SECURITY_ENFORCED
+        ]);
+
+        // Step 3: O(1) Map lookups
+        for (Contact c : contacts) {
+            Account a = accountMap.get(c.AccountId);
+            if (a != null) {
+                c.Description = 'Account: ' + a.Name;
+            }
+        }
+    }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// PATTERN 2: Grouped Child Records (One-to-Many)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Get child records grouped by parent ID
+ * Useful when you need all children for each parent
+ */
+public class GroupedChildPattern {
+
+    /**
+     * Returns Contacts grouped by their AccountId
+     */
+    public static Map<Id, List<Contact>> getContactsByAccountId(Set<Id> accountIds) {
+        Map<Id, List<Contact>> contactsByAccount = new Map<Id, List<Contact>>();
+
+        // Initialize empty lists for each account
+        for (Id accountId : accountIds) {
+            contactsByAccount.put(accountId, new List<Contact>());
+        }
+
+        // Single query for all contacts
+        for (Contact c : [
+            SELECT Id, FirstName, LastName, Email, AccountId
+            FROM Contact
+            WHERE AccountId IN :accountIds
+            WITH SECURITY_ENFORCED
+        ]) {
+            contactsByAccount.get(c.AccountId).add(c);
+        }
+
+        return contactsByAccount;
+    }
+
+    /**
+     * Usage example in a trigger
+     */
+    public void onAccountUpdate(List<Account> accounts) {
+        Set<Id> accountIds = new Set<Id>();
+        for (Account a : accounts) {
+            accountIds.add(a.Id);
+        }
+
+        // Get all contacts for all accounts in ONE query
+        Map<Id, List<Contact>> contactsByAccount = getContactsByAccountId(accountIds);
+
+        for (Account a : accounts) {
+            List<Contact> accountContacts = contactsByAccount.get(a.Id);
+            System.debug('Account ' + a.Name + ' has ' + accountContacts.size() + ' contacts');
+        }
+    }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// PATTERN 3: Multi-Level Relationship Lookup
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * When you need to traverse multiple relationship levels
+ * Example: Contact -> Account -> Owner
+ */
+public class MultiLevelLookupPattern {
+
+    public void enrichContactsWithOwnerInfo(List<Contact> contacts) {
+        // Step 1: Get Account IDs
+        Set<Id> accountIds = new Set<Id>();
+        for (Contact c : contacts) {
+            if (c.AccountId != null) {
+                accountIds.add(c.AccountId);
+            }
+        }
+
+        // Step 2: Query Accounts with Owner info (single query)
+        Map<Id, Account> accountMap = new Map<Id, Account>([
+            SELECT Id, Name, OwnerId, Owner.Name, Owner.Email
+            FROM Account
+            WHERE Id IN :accountIds
+            WITH SECURITY_ENFORCED
+        ]);
+
+        // Step 3: Use the data
+        for (Contact c : contacts) {
+            Account a = accountMap.get(c.AccountId);
+            if (a != null && a.Owner != null) {
+                c.Description = 'Account Owner: ' + a.Owner.Name;
+            }
+        }
+    }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// PATTERN 4: Conditional Query Based on Field Values
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * When you only need to query for certain records based on field values
+ */
+public class ConditionalQueryPattern {
+
+    public void updateHighValueOpportunities(List<Opportunity> opportunities) {
+        // Step 1: Filter to high-value opportunities only
+        Set<Id> highValueAccountIds = new Set<Id>();
+        for (Opportunity opp : opportunities) {
+            if (opp.Amount != null && opp.Amount > 100000 && opp.AccountId != null) {
+                highValueAccountIds.add(opp.AccountId);
+            }
+        }
+
+        // Step 2: Only query if we have high-value records
+        if (highValueAccountIds.isEmpty()) {
+            return; // No query needed!
+        }
+
+        Map<Id, Account> accountMap = new Map<Id, Account>([
+            SELECT Id, Name, AnnualRevenue, Industry
+            FROM Account
+            WHERE Id IN :highValueAccountIds
+            WITH SECURITY_ENFORCED
+        ]);
+
+        // Step 3: Process only the high-value opportunities
+        for (Opportunity opp : opportunities) {
+            if (opp.Amount != null && opp.Amount > 100000) {
+                Account a = accountMap.get(opp.AccountId);
+                if (a != null) {
+                    opp.Description = 'High-value opp for ' + a.Industry + ' account';
+                }
+            }
+        }
+    }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// PATTERN 5: Avoiding Duplicate Queries in Complex Logic
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * When the same data is needed in multiple methods,
+ * query once and pass the Map around
+ */
+public class SharedQueryPattern {
+
+    private Map<Id, Account> accountCache;
+
+    /**
+     * Initialize the cache once at the start of processing
+     */
+    public void initializeCache(Set<Id> accountIds) {
+        this.accountCache = new Map<Id, Account>([
+            SELECT Id, Name, Industry, AnnualRevenue, OwnerId
+            FROM Account
+            WHERE Id IN :accountIds
+            WITH SECURITY_ENFORCED
+        ]);
+    }
+
+    /**
+     * Multiple methods can use the cached data
+     */
+    public String getAccountName(Id accountId) {
+        Account a = accountCache.get(accountId);
+        return a != null ? a.Name : null;
+    }
+
+    public String getAccountIndustry(Id accountId) {
+        Account a = accountCache.get(accountId);
+        return a != null ? a.Industry : null;
+    }
+
+    public Decimal getAccountRevenue(Id accountId) {
+        Account a = accountCache.get(accountId);
+        return a != null ? a.AnnualRevenue : 0;
+    }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// PATTERN 6: SOQL For Loop (Large Dataset Processing)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * For processing very large datasets without hitting heap limits
+ * The SOQL for loop fetches 200 records at a time
+ */
+public class LargeDatasetPattern {
+
+    public void processAllAccounts() {
+        // This fetches 200 records at a time, not all 50,000
+        for (Account a : [
+            SELECT Id, Name, Industry
+            FROM Account
+            WHERE CreatedDate = THIS_YEAR
+        ]) {
+            // Process one record at a time
+            // Heap stays small because only 200 records in memory
+            processAccount(a);
+        }
+    }
+
+    public void processAllAccountsInBatches() {
+        // Alternative: explicit batch processing (200 at a time)
+        for (List<Account> accountBatch : [
+            SELECT Id, Name, Industry
+            FROM Account
+            WHERE CreatedDate = THIS_YEAR
+        ]) {
+            // Process 200 records at a time
+            processBatch(accountBatch);
+        }
+    }
+
+    private void processAccount(Account a) {
+        // Individual record processing
+    }
+
+    private void processBatch(List<Account> accounts) {
+        // Batch processing
+    }
+}

package/skills/querying-soql/assets/optimization-patterns.soql

@@ -0,0 +1,259 @@
+/**
+ * SOQL OPTIMIZATION PATTERNS
+ *
+ * These patterns demonstrate how to write efficient, selective queries
+ * that perform well within Salesforce governor limits.
+ */
+
+// ═══════════════════════════════════════════════════════════════════════════
+// SELECTIVE vs NON-SELECTIVE QUERIES
+// ═══════════════════════════════════════════════════════════════════════════
+
+-- ❌ NON-SELECTIVE: Status alone is not indexed
+SELECT Id, Name FROM Lead
+WHERE Status = 'Open'
+-- Scans ALL Lead records
+
+-- ✅ SELECTIVE: Add indexed field filter
+SELECT Id, Name FROM Lead
+WHERE Status = 'Open'
+AND CreatedDate = LAST_N_DAYS:30
+-- CreatedDate is indexed, reduces scan
+
+-- ❌ NON-SELECTIVE: Leading wildcard prevents index use
+SELECT Id, Name FROM Account
+WHERE Name LIKE '%corporation'
+
+-- ✅ SELECTIVE: Trailing wildcard uses index
+SELECT Id, Name FROM Account
+WHERE Name LIKE 'Acme%'
+
+-- ❌ NON-SELECTIVE: OR can prevent index optimization
+SELECT Id FROM Contact
+WHERE Email = 'test@test.com'
+OR Phone = '555-1234'
+
+-- ✅ SELECTIVE: Use UNION-style in Apex or multiple queries
+-- Query 1: SELECT Id FROM Contact WHERE Email = 'test@test.com'
+-- Query 2: SELECT Id FROM Contact WHERE Phone = '555-1234'
+-- Combine results in Apex
+
+// ═══════════════════════════════════════════════════════════════════════════
+// INDEXED FIELDS
+// ═══════════════════════════════════════════════════════════════════════════
+
+-- Always indexed fields (use these in WHERE)
+-- • Id (primary key)
+-- • Name (standard Name field)
+-- • OwnerId
+-- • CreatedDate
+-- • LastModifiedDate
+-- • RecordTypeId
+-- • External ID fields (custom)
+-- • Master-Detail relationship fields
+-- • Lookup fields (selective when <100k parent records)
+
+-- ✅ GOOD: Uses indexed OwnerId
+SELECT Id, Name FROM Account
+WHERE OwnerId = '005xx000000XXXX'
+
+-- ✅ GOOD: Uses indexed CreatedDate
+SELECT Id, Name FROM Contact
+WHERE CreatedDate >= 2024-01-01T00:00:00Z
+
+-- ✅ GOOD: Uses indexed External ID
+SELECT Id, Name FROM Account
+WHERE External_Id__c = 'EXT-12345'
+
+// ═══════════════════════════════════════════════════════════════════════════
+// FIELD SELECTION OPTIMIZATION
+// ═══════════════════════════════════════════════════════════════════════════
+
+-- ❌ BAD: Selecting unnecessary fields
+SELECT Id, Name, Description, BillingStreet, BillingCity, BillingState,
+       BillingPostalCode, BillingCountry, ShippingStreet, ShippingCity,
+       ShippingState, ShippingPostalCode, ShippingCountry, Phone, Fax,
+       AccountNumber, Website, Industry, AnnualRevenue, NumberOfEmployees,
+       Ownership, TickerSymbol, Description, Rating, Site, AccountSource
+FROM Account
+
+-- ✅ GOOD: Select only needed fields
+SELECT Id, Name, Industry, AnnualRevenue
+FROM Account
+
+-- For display only: Use specific fields
+SELECT Id, Name FROM Account
+
+-- For processing: Query fields you'll update
+SELECT Id, Status__c, Last_Processed__c FROM Account
+
+// ═══════════════════════════════════════════════════════════════════════════
+// LIMIT USAGE
+// ═══════════════════════════════════════════════════════════════════════════
+
+-- ❌ BAD: No limit (could return 50,000 rows)
+SELECT Id, Name FROM Account
+
+-- ✅ GOOD: Appropriate limit
+SELECT Id, Name FROM Account LIMIT 200
+
+-- For pagination
+SELECT Id, Name FROM Account ORDER BY Name LIMIT 100 OFFSET 0
+
+-- For single record lookup
+SELECT Id, Name FROM Account WHERE Name = 'Acme Corp' LIMIT 1
+
+-- For existence check
+SELECT Id FROM Account WHERE Name = 'Acme Corp' LIMIT 1
+-- In Apex: if (!results.isEmpty()) { /* exists */ }
+
+// ═══════════════════════════════════════════════════════════════════════════
+// RELATIONSHIP QUERY OPTIMIZATION
+// ═══════════════════════════════════════════════════════════════════════════
+
+-- ❌ BAD: Deep nesting (5 levels is max, avoid if possible)
+SELECT Id, Account.Owner.Manager.Department.Name FROM Contact
+
+-- ✅ GOOD: Flatten when possible
+SELECT Id, Account.Name, Account.OwnerId FROM Contact
+-- Then query Owner separately if needed
+
+-- ❌ BAD: Too many child subqueries
+SELECT Id, Name,
+       (SELECT Id FROM Contacts),
+       (SELECT Id FROM Opportunities),
+       (SELECT Id FROM Cases),
+       (SELECT Id FROM Tasks),
+       (SELECT Id FROM Events),
+       (SELECT Id FROM Notes)
+FROM Account
+
+-- ✅ GOOD: Query what you need
+SELECT Id, Name,
+       (SELECT Id, Name FROM Contacts LIMIT 5)
+FROM Account
+
+-- ❌ BAD: Unfiltered subquery
+SELECT Id, (SELECT Id FROM Opportunities) FROM Account
+
+-- ✅ GOOD: Filtered subquery
+SELECT Id, (SELECT Id FROM Opportunities WHERE StageName != 'Closed Lost' LIMIT 10)
+FROM Account
+
+// ═══════════════════════════════════════════════════════════════════════════
+// BULK QUERY PATTERNS
+// ═══════════════════════════════════════════════════════════════════════════
+
+-- ❌ BAD: Query in loop
+/*
+for (Contact c : contacts) {
+    Account a = [SELECT Name FROM Account WHERE Id = :c.AccountId];
+}
+*/
+
+-- ✅ GOOD: Bulk query with Map
+/*
+Set<Id> accountIds = new Set<Id>();
+for (Contact c : contacts) {
+    accountIds.add(c.AccountId);
+}
+
+Map<Id, Account> accountMap = new Map<Id, Account>(
+    [SELECT Id, Name FROM Account WHERE Id IN :accountIds]
+);
+
+for (Contact c : contacts) {
+    Account a = accountMap.get(c.AccountId);
+}
+*/
+
+-- Use IN clause for bulk operations
+SELECT Id, Name FROM Account WHERE Id IN :accountIdSet
+
+-- Bind variable with Set (most efficient)
+SELECT Id, Name FROM Contact WHERE AccountId IN :accountIds
+
+// ═══════════════════════════════════════════════════════════════════════════
+// FOR UPDATE (Record Locking)
+// ═══════════════════════════════════════════════════════════════════════════
+
+-- Lock records for update (prevents concurrent modification)
+SELECT Id, Status__c FROM Account WHERE Id = :accountId FOR UPDATE
+
+-- Note: Only use FOR UPDATE when you need to prevent race conditions
+-- Adds overhead and can cause lock contention
+
+// ═══════════════════════════════════════════════════════════════════════════
+// SECURITY ENFORCEMENT
+// ═══════════════════════════════════════════════════════════════════════════
+
+-- ✅ Recommended: WITH SECURITY_ENFORCED
+SELECT Id, Name, Phone FROM Account
+WITH SECURITY_ENFORCED
+-- Throws exception if user lacks field access
+
+-- Alternative: USER_MODE (API 54.0+)
+SELECT Id, Name FROM Account
+WITH USER_MODE
+-- Respects sharing rules and FLS
+
+-- For admin operations: SYSTEM_MODE
+SELECT Id, Name FROM Account
+WITH SYSTEM_MODE
+-- Bypasses sharing (use with caution)
+
+// ═══════════════════════════════════════════════════════════════════════════
+// QUERY PLAN ANALYSIS
+// ═══════════════════════════════════════════════════════════════════════════
+
+/*
+Use Developer Console or CLI to analyze query plans:
+
+1. Developer Console:
+   - Query Editor > Check "Use Tooling API"
+   - Click "Query Plan" button
+
+2. CLI (uses REST API explain endpoint):
+   sf api request rest '/query/?explain=SELECT+Id+FROM+Account+WHERE+Name='\''Test'\''' --target-org my-org --json
+
+Plan Output:
+- Cardinality: Estimated rows returned
+- Fields: Index fields used
+- LeadingOperationType:
+  - "Index" = Good (using index)
+  - "TableScan" = Bad (scanning all records)
+- Cost: Relative cost (lower is better)
+- sObjectCardinality: Total records in object
+*/
+
+// ═══════════════════════════════════════════════════════════════════════════
+// LARGE DATA VOLUME PATTERNS
+// ═══════════════════════════════════════════════════════════════════════════
+
+-- For tables with millions of records:
+
+-- 1. Always use indexed fields
+SELECT Id FROM Account
+WHERE External_Id__c = 'EXT-123'
+
+-- 2. Use date range with limit
+SELECT Id, Name FROM Contact
+WHERE CreatedDate >= 2024-01-01T00:00:00Z
+AND CreatedDate < 2024-02-01T00:00:00Z
+LIMIT 10000
+
+-- 3. Use skinny tables (configured by Salesforce Support)
+-- Query fields included in skinny table for best performance
+
+-- 4. Consider archiving old records
+SELECT Id FROM Account
+WHERE LastActivityDate < LAST_N_YEARS:2
+AND CreatedDate < LAST_N_YEARS:3
+
+-- 5. Use Database.query() with query locator for batch
+/*
+Database.QueryLocator ql = Database.getQueryLocator(
+    'SELECT Id, Name FROM Account WHERE CreatedDate = THIS_YEAR'
+);
+// Can process up to 50 million records in batch
+*/