sf-data

データ移行と管理

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

インポートとアップサート

# 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 1 ファイルあたり 150 MB
• 24 時間のローリング期間あたり最大 150M 件

外部 ID のベストプラクティス

• ソース組織とターゲット組織の両方で一意となるフィールドを選択します
• アップサートの冪等性を確保するため、「外部 ID」と「一意」の両方を設定します
• マスクされたフィールドは外部 ID として使用できません（Data Mask の制限）
• 組織間の同期では、UUID または複合キー（OrgId + RecordId）を使用します

リレーションシップの読み込み順序

1. 独立したオブジェクト（必須の参照関係がないもの）
2. 親オブジェクト（Contact より先に Account）
3. 子レコードを挿入する前に、主従関係の親レコードが必ず存在している必要があります
4. 中間オブジェクト（M2M）は両方の親オブジェクトの後に読み込みます
5. 自己参照レコード：2 パスで読み込みます（自己参照を含めずに挿入し、その後更新します）

レコードタイプのマッピング

• レコードタイプの開発者名（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 句を使用します
• 参照整合性を維持し、子レコードより先に親レコードを読み込みます
• 重複を避けるため、アップサート操作には外部 ID を使用します
• 破壊的な操作の前にデータをバックアップします
• 200 件を超えるデータセットには Bulk API を使用します

注意点

• 子レコードを挿入する前に主従関係の親レコードが必ず存在している必要があります。存在しない場合は ENTITY_IS_DELETED または REQUIRED_FIELD_MISSING が発生します
• Salesforce Data Mask では、外部 ID フィールドをマスクできません
• Bulk API ジョブは 10～15 分後にタイムアウトするため、大規模なデータセットは分割します
• ポリモーフィック参照（例：Task.WhatId）には、エクスポートクエリで TYPEOF が必要です
• ContentVersion では PathOnClient と VersionData の両方が必須です
• 自己参照レコード（例：Account.ParentId）には、2 パスでの読み込みが必要です
• Bulk API 2.0 は個々のレコードの読み込みに失敗してもジョブを成功として返すため、必ず結果を確認します
• Data Loader は、フィールド長を超える値を通知なしに切り詰めます

参考資料

• データパターン — Bulk API 2.0、Composite API、ツリーエクスポート、外部 ID、大容量データ、Big Objects、ファイルアップロード、複数通貨、ETL、バックアップと復旧

ワークフロー

1. ターゲット組織への接続を確認します
2. データ要件（オブジェクト、リレーションシップ、件数）を分析します
3. ソースデータをエクスポートまたは生成します
4. 正しいオブジェクト順序でインポート計画を作成します
5. 適切な方法（ツリー、Bulk、匿名 Apex）でインポートを実行します
6. インポート後にデータの整合性を確認します