@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/handling-sf-data/references/relationship-query-examples.md

@@ -0,0 +1,249 @@
+<!-- Parent: handling-sf-data/SKILL.md -->
+# Relationship Query Examples
+
+Comprehensive SOQL relationship patterns for complex data retrieval.
+
+## Parent-to-Child Queries (Subqueries)
+
+### Basic Subquery
+```sql
+SELECT Id, Name,
+    (SELECT Id, FirstName, LastName, Email FROM Contacts)
+FROM Account
+WHERE Industry = 'Technology'
+```
+
+```bash
+sf data query \
+  --query "SELECT Id, Name, (SELECT Id, FirstName, LastName FROM Contacts) FROM Account WHERE Industry = 'Technology' LIMIT 5" \
+  --target-org dev \
+  --json
+```
+
+### Multiple Subqueries
+```sql
+SELECT Id, Name,
+    (SELECT Id, Name, Title FROM Contacts),
+    (SELECT Id, Name, Amount, StageName FROM Opportunities),
+    (SELECT Id, CaseNumber, Subject FROM Cases)
+FROM Account
+WHERE Id = '001XXXXXXXXXXXX'
+```
+
+### Filtered Subquery
+```sql
+SELECT Id, Name,
+    (SELECT Id, Name, Amount
+     FROM Opportunities
+     WHERE StageName = 'Closed Won'
+     ORDER BY Amount DESC
+     LIMIT 5)
+FROM Account
+WHERE AnnualRevenue > 1000000
+```
+
+## Child-to-Parent Queries (Dot Notation)
+
+### Basic Relationship
+```sql
+SELECT Id, FirstName, LastName,
+       Account.Name, Account.Industry
+FROM Contact
+WHERE Account.Industry = 'Technology'
+```
+
+```bash
+sf data query \
+  --query "SELECT Id, FirstName, LastName, Account.Name, Account.Industry FROM Contact WHERE Account.Industry = 'Technology' LIMIT 10" \
+  --target-org dev
+```
+
+### Multi-Level Traversal
+```sql
+SELECT Id, Name, Amount,
+       Account.Name,
+       Account.Owner.Name,
+       Account.Owner.Profile.Name
+FROM Opportunity
+WHERE Account.Industry = 'Finance'
+```
+
+### Custom Object Relationships
+```sql
+-- __r suffix for custom relationships
+SELECT Id, Name,
+       Custom_Parent__r.Name,
+       Custom_Parent__r.Custom_Field__c
+FROM Custom_Child__c
+```
+
+## Polymorphic Relationships (TYPEOF)
+
+### Task Who/What Fields
+```sql
+SELECT Id, Subject, Status,
+    TYPEOF Who
+        WHEN Contact THEN FirstName, LastName, Email
+        WHEN Lead THEN FirstName, LastName, Company
+    END,
+    TYPEOF What
+        WHEN Account THEN Name, Industry
+        WHEN Opportunity THEN Name, Amount, StageName
+    END
+FROM Task
+WHERE Status = 'Open'
+```
+
+```bash
+sf data query \
+  --query "SELECT Id, Subject, TYPEOF Who WHEN Contact THEN FirstName, LastName WHEN Lead THEN FirstName, LastName END FROM Task WHERE Status = 'Open' LIMIT 5" \
+  --target-org dev \
+  --json
+```
+
+### Event Relationships
+```sql
+SELECT Id, Subject, StartDateTime,
+    TYPEOF Who
+        WHEN Contact THEN FirstName, LastName, Account.Name
+        WHEN Lead THEN Name, Company
+    END
+FROM Event
+WHERE StartDateTime >= TODAY
+```
+
+## Aggregate Queries
+
+### Basic Aggregation
+```sql
+SELECT Industry, COUNT(Id) total, SUM(AnnualRevenue) revenue
+FROM Account
+GROUP BY Industry
+HAVING COUNT(Id) > 10
+ORDER BY SUM(AnnualRevenue) DESC
+```
+
+```bash
+sf data query \
+  --query "SELECT Industry, COUNT(Id) total, SUM(AnnualRevenue) revenue FROM Account GROUP BY Industry HAVING COUNT(Id) > 5" \
+  --target-org dev
+```
+
+### Rollup by Date
+```sql
+SELECT CALENDAR_MONTH(CloseDate) month,
+       SUM(Amount) total,
+       COUNT(Id) deals
+FROM Opportunity
+WHERE CloseDate = THIS_YEAR
+AND StageName = 'Closed Won'
+GROUP BY CALENDAR_MONTH(CloseDate)
+ORDER BY CALENDAR_MONTH(CloseDate)
+```
+
+### Aggregate with Relationships
+```sql
+SELECT Account.Industry,
+       COUNT(Id) opportunities,
+       SUM(Amount) pipeline
+FROM Opportunity
+WHERE StageName NOT IN ('Closed Won', 'Closed Lost')
+GROUP BY Account.Industry
+```
+
+## Semi-Joins and Anti-Joins
+
+### Semi-Join (Records WITH Related)
+```sql
+-- Accounts that HAVE Opportunities
+SELECT Id, Name
+FROM Account
+WHERE Id IN (
+    SELECT AccountId FROM Opportunity WHERE Amount > 100000
+)
+```
+
+### Anti-Join (Records WITHOUT Related)
+```sql
+-- Accounts WITHOUT Contacts
+SELECT Id, Name
+FROM Account
+WHERE Id NOT IN (
+    SELECT AccountId FROM Contact WHERE AccountId != null
+)
+```
+
+### Complex Semi-Join
+```sql
+-- Contacts at Accounts with large deals
+SELECT Id, FirstName, LastName
+FROM Contact
+WHERE AccountId IN (
+    SELECT AccountId
+    FROM Opportunity
+    WHERE Amount > 500000
+    AND StageName = 'Closed Won'
+)
+```
+
+## Date Functions and Filters
+
+### Date Literals
+```sql
+SELECT Id, Name, CreatedDate
+FROM Account
+WHERE CreatedDate = THIS_WEEK
+-- Also: TODAY, YESTERDAY, THIS_MONTH, LAST_MONTH, THIS_YEAR, LAST_N_DAYS:7
+```
+
+### Date Functions in SELECT
+```sql
+SELECT DAY_IN_MONTH(CreatedDate) day,
+       WEEK_IN_YEAR(CreatedDate) week,
+       CALENDAR_YEAR(CreatedDate) year,
+       COUNT(Id) count
+FROM Lead
+GROUP BY DAY_IN_MONTH(CreatedDate),
+         WEEK_IN_YEAR(CreatedDate),
+         CALENDAR_YEAR(CreatedDate)
+```
+
+## Query Optimization Tips
+
+### Use Indexed Fields
+```sql
+-- GOOD: Query on indexed fields (Id, Name, CreatedDate, SystemModstamp)
+SELECT Id, Name FROM Account WHERE Name LIKE 'Acme%'
+
+-- BAD: Query on non-indexed custom field (full table scan)
+SELECT Id, Name FROM Account WHERE Custom_Unindexed__c = 'value'
+```
+
+### Limit Records Retrieved
+```sql
+-- Always use LIMIT for exploration
+SELECT Id, Name FROM Account LIMIT 100
+
+-- Use OFFSET for pagination
+SELECT Id, Name FROM Account LIMIT 100 OFFSET 200
+```
+
+### Select Only Needed Fields
+```sql
+-- GOOD: Only needed fields
+SELECT Id, Name, Industry FROM Account
+
+-- BAD: Selecting all fields
+SELECT Id, Name, Industry, Description, BillingStreet, BillingCity,
+       BillingState, BillingPostalCode, BillingCountry, ...
+```
+
+## Common Errors
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `Invalid relationship` | Wrong relationship name | Check `__r` suffix for custom |
+| `MALFORMED_QUERY` | Syntax error | Validate SOQL syntax |
+| `SELECT too complex` | Too many levels | Max 5 levels of relationships |
+| `Subquery limit` | >20 subqueries | Reduce number of child queries |
+| `Non-selective query` | No indexed filter | Add indexed field to WHERE |

package/skills/handling-sf-data/references/sf-cli-data-commands.md

@@ -0,0 +1,158 @@
+<!-- Parent: handling-sf-data/SKILL.md -->
+# sf CLI Data Commands Reference
+
+Complete reference for Salesforce CLI v2 data commands.
+
+## Query Commands
+
+### SOQL Query
+```bash
+sf data query \
+  --query "SELECT Id, Name FROM Account LIMIT 10" \
+  --target-org myorg \
+  --json
+```
+
+### SOSL Search
+```bash
+sf data search \
+  --query "FIND {Acme}" \
+  --target-org myorg
+```
+
+### Bulk Export
+```bash
+sf data export bulk \
+  --query "SELECT Id, Name FROM Account" \
+  --output-file accounts.csv \
+  --target-org myorg \
+  --wait 30
+```
+
+## Record Operations
+
+### Create Record
+```bash
+sf data create record \
+  --sobject Account \
+  --values "Name='Acme' Industry='Technology'" \
+  --target-org myorg
+```
+
+### Update Record
+```bash
+sf data update record \
+  --sobject Account \
+  --record-id 001XXXXXXXXXXXX \
+  --values "Industry='Healthcare'" \
+  --target-org myorg
+```
+
+### Delete Record
+```bash
+sf data delete record \
+  --sobject Account \
+  --record-id 001XXXXXXXXXXXX \
+  --target-org myorg
+```
+
+### Get Record
+```bash
+sf data get record \
+  --sobject Account \
+  --record-id 001XXXXXXXXXXXX \
+  --target-org myorg
+```
+
+## Bulk Operations
+
+### Bulk Import
+```bash
+sf data import bulk \
+  --file data.csv \
+  --sobject Account \
+  --target-org myorg \
+  --wait 30
+```
+
+### Bulk Update
+```bash
+sf data update bulk \
+  --file updates.csv \
+  --sobject Account \
+  --target-org myorg \
+  --wait 30
+```
+
+### Bulk Upsert
+```bash
+sf data upsert bulk \
+  --file data.csv \
+  --sobject Account \
+  --external-id External_Id__c \
+  --target-org myorg \
+  --wait 30
+```
+
+### Bulk Delete
+```bash
+sf data delete bulk \
+  --file ids.csv \
+  --sobject Account \
+  --target-org myorg \
+  --wait 30
+```
+
+## Tree Operations
+
+### Export Tree
+```bash
+sf data export tree \
+  --query "SELECT Id, Name, (SELECT Id, Name FROM Contacts) FROM Account" \
+  --output-dir ./data \
+  --target-org myorg
+```
+
+### Import Tree
+```bash
+sf data import tree \
+  --files data.json \
+  --target-org myorg
+```
+
+## Common Flags
+
+| Flag | Description |
+|------|-------------|
+| `--target-org`, `-o` | Target org alias |
+| `--json` | JSON output format |
+| `--result-format` | human, csv, json |
+| `--wait` | Minutes to wait for bulk jobs |
+| `--use-tooling-api` | Query Tooling API |
+
+## Object Describe (Pre-flight Validation)
+
+```bash
+sf sobject describe --sobject ObjectName --target-org <alias> --json
+```
+
+### Useful jq filters for describe output
+
+```bash
+# Required + createable fields
+jq '.result.fields[] | select(.nillable==false and .createable==true) | {name, type}'
+
+# Valid picklist values for a specific field
+jq '.result.fields[] | select(.name=="StageName") | .picklistValues[].value'
+
+# Fields that cannot be set on create
+jq '.result.fields[] | select(.createable==false) | .name'
+```
+
+---
+
+## Apex Execution
+
+```bash
+sf apex run --file script.apex --target-org myorg
+```

package/skills/handling-sf-data/references/soql-relationship-guide.md

@@ -0,0 +1,84 @@
+<!-- Parent: handling-sf-data/SKILL.md -->
+# SOQL Relationship Query Guide
+
+Complete reference for querying related records in Salesforce.
+
+## Relationship Types
+
+### 1. Parent-to-Child (Subquery)
+Returns parent records with nested child records.
+
+```sql
+SELECT Id, Name,
+    (SELECT Id, FirstName, LastName FROM Contacts)
+FROM Account
+WHERE Industry = 'Technology'
+```
+
+**Key Points:**
+- Maximum 20 subqueries per query
+- Use relationship name (plural): `Contacts`, `Opportunities`, `Cases`
+- For custom objects: `Child_Object__r`
+
+### 2. Child-to-Parent (Dot Notation)
+Access parent fields from child record.
+
+```sql
+SELECT Id, Name,
+    Account.Name,
+    Account.Industry,
+    Account.Owner.Name
+FROM Contact
+WHERE Account.Type = 'Customer'
+```
+
+**Key Points:**
+- Maximum 5 levels deep
+- Standard: `Account.Name`
+- Custom: `Parent__r.Name`
+
+### 3. Polymorphic (TYPEOF)
+Handle fields that reference multiple object types.
+
+```sql
+SELECT Id, Subject,
+    TYPEOF Who
+        WHEN Contact THEN FirstName, LastName
+        WHEN Lead THEN Company
+    END,
+    TYPEOF What
+        WHEN Account THEN Name, Industry
+        WHEN Opportunity THEN Amount
+    END
+FROM Task
+```
+
+**Common Polymorphic Fields:**
+- `WhoId` → Contact, Lead
+- `WhatId` → Account, Opportunity, Case, etc.
+- `OwnerId` → User, Queue
+
+## Relationship Names
+
+| Child Object | Parent Field | Relationship Name |
+|--------------|--------------|-------------------|
+| Contact | AccountId | Account.Contacts |
+| Opportunity | AccountId | Account.Opportunities |
+| Case | AccountId | Account.Cases |
+| Task | WhatId | Account.Tasks |
+| Contact | ReportsToId | Contact.ReportsTo |
+
+## Limits
+
+| Limit | Value |
+|-------|-------|
+| Child-to-Parent depth | 5 levels |
+| Subqueries per query | 20 |
+| Rows per subquery | 200 (without LIMIT) |
+
+## Best Practices
+
+1. **Use indexed fields** in WHERE clauses
+2. **Add LIMIT** to subqueries
+3. **Filter early** - push conditions into subqueries
+4. **Avoid N+1** - use relationship queries instead of loops

package/skills/handling-sf-data/references/test-data-best-practices.md

@@ -0,0 +1,104 @@
+<!-- Parent: handling-sf-data/SKILL.md -->
+# Test Data Best Practices
+
+Use this guide when creating or troubleshooting org data for demos, automation validation, integration checks, or post-deploy smoke testing.
+
+## Describe-first rule
+
+Before creating or updating records, validate the object shape with:
+
+```bash
+sf sobject describe --sobject ObjectName --target-org <alias> --json
+```
+
+Use describe output to confirm:
+- required fields
+- createable and updateable fields
+- valid picklist values
+- parent relationships
+- fields that should be excluded from the payload
+
+### Handy filters
+
+```bash
+# Required + createable fields
+jq '.result.fields[] | select(.nillable==false and .createable==true) | {name, type}'
+
+# Picklist values for one field
+jq '.result.fields[] | select(.name=="Status__c") | .picklistValues[].value'
+
+# Fields that are not createable
+jq '.result.fields[] | select(.createable==false) | .name'
+```
+
+## CLI-first for straightforward CRUD
+
+Prefer `sf data` commands when the workflow is simple and direct.
+
+```bash
+sf data create record \
+  --sobject Account \
+  --values "Name='Bulk Test 001' Industry='Technology'" \
+  --target-org <alias> \
+  --json
+```
+
+Use anonymous Apex when you need:
+- multi-object orchestration in one transaction
+- reusable factory logic
+- rollback via savepoint
+- complex branching that would be awkward in shell commands
+
+## Pre-flight checklist
+
+Before data creation:
+- [ ] target object exists in the org
+- [ ] required parent records exist
+- [ ] required fields are known
+- [ ] picklist values are validated from describe output
+- [ ] non-createable fields are excluded
+- [ ] cleanup plan is ready
+
+## Common failure patterns
+
+| Failure | Likely cause | Fix |
+|---|---|---|
+| `REQUIRED_FIELD_MISSING` | Required field omitted | add describe-backed required values |
+| invalid picklist value | guessed value | inspect real picklist values first |
+| non-writeable field error | field is not createable/updateable | remove it from the payload |
+| `INVALID_CROSS_REFERENCE_KEY` | missing or wrong parent Id | create/query parent first |
+| `FIELD_CUSTOM_VALIDATION_EXCEPTION` | validation rule blocked test data | use a valid scenario or adjust setup |
+
+## Bounded retry strategy
+
+Use a small, explicit retry loop:
+
+1. **Attempt 1** — run the primary CLI command
+2. **Attempt 2** — retry once with corrected parameters
+3. **Attempt 3** — re-run describe, verify assumptions, and pivot if needed
+4. **Stop** — provide a manual workaround or alternate loading strategy
+
+Do not keep repeating the same failing shape.
+
+## Manual fallback options
+
+If direct record creation keeps failing:
+- switch to tree import for parent-child data
+- switch to anonymous Apex for transactional setup
+- split the operation into parent-first then child records
+- provide the user with an exact manual setup checklist
+
+## Cleanup expectations
+
+Whenever test data is created, provide one of:
+- delete-by-ID commands
+- delete-by-pattern guidance
+- delete-by-created-date guidance
+- rollback script or savepoint flow
+
+## Related references
+
+- [sf-cli-data-commands.md](sf-cli-data-commands.md)
+- [test-data-patterns.md](test-data-patterns.md)
+- [cleanup-rollback-guide.md](cleanup-rollback-guide.md)
+- [orchestration.md](orchestration.md)