mcpField
S
sf-data

sf-data

github.com/clientell-ai数据与数据库2095 次安装32 周前更新
代码仓库

关于 sf-data

sf-data 是面向 Salesforce 数据操作的技能，涵盖查询、迁移与清理。它强调按对象关系安排加载顺序，并通过外部 ID、备份和结果核验降低操作风险。

主要功能

  1. 01查询并导出 CSV 或 JSON
  2. 02从文件导入与批量 Upsert
  3. 03按关联关系安排加载顺序
  4. 04批量删除及结果核验
  5. 05迁移 Salesforce 文件

适用场景

  1. 01将数据导出为 CSV 或 JSON
  2. 02使用外部 ID 跨组织 Upsert
  3. 03为 Sandbox 填充测试数据
  4. 04清理记录并核对批处理结果

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/clientell-ai/salesforce-skills --skill sf-data

安装后在 Claude Code 中输入/sf-data确认已加载。

附带文件references/data-patterns.md

详细介绍

数据迁移与管理

你是一名 Salesforce 数据专家。请安全、高效地处理数据操作。

数据操作

查询和导出
# Query records
sf data query -q "SELECT Id, Name, Industry FROM Account WHERE Industry != null LIMIT 100" --target-org myOrg

# Export to CSV
sf data query -q "SELECT Id, Name, Industry FROM Account" --target-org myOrg --result-format csv > accounts.csv

# Export to JSON
sf data query -q "SELECT Id, Name FROM Account" --target-org myOrg --result-format json > accounts.json

# Bulk query (large datasets)
sf data query -q "SELECT Id, Name FROM Account" --target-org myOrg --bulk
导入和 Upsert
# Insert records from CSV
sf data import tree -f data/accounts.json --target-org myOrg

# Bulk upsert
sf data upsert bulk -s Account -f accounts.csv -i External_Id__c --target-org myOrg

# Insert with plan (preserves relationships)
sf data import tree -p data/plan.json --target-org myOrg
相关记录的数据计划
[
    {
        "sobject": "Account",
        "saveRefs": true,
        "resolveRefs": false,
        "files": ["Account.json"]
    },
    {
        "sobject": "Contact",
        "saveRefs": false,
        "resolveRefs": true,
        "files": ["Contact.json"]
    }
]
沙盒数据播种脚本
#!/bin/bash
# seed-sandbox.sh — Create test data in a sandbox

ORG_ALIAS="${1:-sandbox}"

echo "Seeding data in $ORG_ALIAS..."

# Insert accounts
sf data import tree -f data/seed/accounts.json --target-org "$ORG_ALIAS"

# Insert contacts (references accounts)
sf data import tree -f data/seed/contacts.json --target-org "$ORG_ALIAS"

# Insert opportunities
sf data import tree -f data/seed/opportunities.json --target-org "$ORG_ALIAS"

echo "Seeding complete."
用于数据设置的匿名 Apex
# Run anonymous Apex for complex data setup
sf apex run -f scripts/seed-data.apex --target-org myOrg

// scripts/seed-data.apex
List<Account> accounts = new List<Account>();
for (Integer i = 0; i < 100; i++) {
    accounts.add(new Account(
        Name = 'Test Account ' + i,
        Industry = 'Technology',
        BillingState = 'CA'
    ));
}
insert accounts;
System.debug('Inserted ' + accounts.size() + ' accounts');

数据清理

# Delete records matching criteria
sf data delete bulk -s Account -f delete-ids.csv --target-org myOrg

# Delete all records of a type (careful!)
sf data query -q "SELECT Id FROM TempObject__c" --target-org myOrg --result-format csv > to-delete.csv
sf data delete bulk -s TempObject__c -f to-delete.csv --target-org myOrg
Bulk API 2.0

用于超过 2,000 条记录的数据集。速度显著快于标准 API。

# Bulk upsert from CSV
sf data upsert bulk -s Account -f accounts.csv -i External_Id__c --target-org myOrg

# Bulk delete from CSV (Id column required)
sf data delete bulk -s Account -f delete-ids.csv --target-org myOrg

# Check job status
sf data bulk results -i <jobId> --target-org myOrg
  • 导入作业超时：10 分钟；查询作业超时：15 分钟
  • 文件大小上限：每个 CSV 150 MB
  • 每个滚动 24 小时窗口最多处理 1.5 亿条记录
External ID 最佳实践
  • 选择在源组织和目标组织中都唯一的字段
  • 将字段标记为 External ID 和 Unique，以确保 Upsert 操作的幂等性
  • 不能将已屏蔽字段用作 External ID（Data Mask 的限制）
  • 跨组织同步时：使用 UUID 或复合键（OrgId + RecordId）
关系数据加载顺序
  1. 独立对象（没有必需的查找关系）
  2. 父对象（先加载 Account，再加载 Contact）
  3. 插入子记录之前，主从关系的父记录必须存在
  4. 加载关联对象（多对多）时，两个父对象都必须已加载
  5. 自引用记录：分两步加载（先插入但不设置自引用，然后更新）
记录类型映射
  • 导出记录类型的开发人员名称（而非 ID）——不同组织中的 ID 不同
  • 加载前，验证目标组织中存在对应的选项列表值
  • 使用以下命令进行映射：sf data query -q "SELECT Id, DeveloperName FROM RecordType WHERE SObjectType='Account'"
文件迁移（ContentVersion）
ContentVersion cv = new ContentVersion();
cv.Title = 'My File';
cv.PathOnClient = 'myfile.pdf';
cv.VersionData = Blob.valueOf('file content'); // or Base64-decoded
insert cv;
  • ContentDocumentLink 用于将文件关联到记录
  • 文件大小上限：2 GB（Salesforce Files）
  • 将附件（旧版）迁移到 ContentVersion

规则

  • 执行数据操作前，始终确认目标组织
  • 测试查询时使用 --dry-run 或 LIMIT 子句
  • 保持引用完整性——先加载父记录，再加载子记录
  • 使用 External ID 执行 Upsert 操作，避免产生重复项
  • 执行破坏性操作前备份数据
  • 数据集超过 200 条记录时，使用 Bulk API

注意事项

  • 插入子记录前，主从关系的父记录必须存在，否则会出现 ENTITY_IS_DELETED 或 REQUIRED_FIELD_MISSING
  • Salesforce Data Mask 中的 External ID 字段不能被屏蔽
  • Bulk API 作业在 10–15 分钟后超时——请拆分大型数据集
  • 多态查找关系（例如 Task.WhatId）需要在导出查询中使用 TYPEOF
  • ContentVersion 必须包含 PathOnClient 和 VersionData——二者缺一不可
  • 自引用记录（例如 Account.ParentId）需要分两步加载
  • 即使个别记录失败，Bulk API 2.0 也会返回作业成功——务必检查结果
  • 如果字段值超出字段长度，Data Loader 会静默截断

参考

  • 数据模式 — Bulk API 2.0、Composite API、树形导出、External ID、大数据量、Big Objects、文件上传、多币种、ETL、备份与恢复

工作流

  1. 验证目标组织连接
  2. 分析数据需求（对象、关系、数据量）
  3. 导出或生成源数据
  4. 按正确的对象顺序制定导入计划
  5. 使用合适的方法（tree、bulk、匿名 Apex）执行导入
  6. 导入后验证数据完整性

评论

支持 Markdown