Salesforce: オブジェクトのクエリ

説明

Salesforce の Bulk API 2.0 を使用して、標準オブジェクトまたはカスタムオブジェクト 1 つを、プロジェクトテーブルに読み込みます。Salesforce接続、オブジェクト、フィールドを選択すると、ステップがクエリを構築し、結果セット全体をページ送りして、各列を Salesforce が宣言する型で格納します。クエリを書く必要はありません。

Salesforce には REST API 経由でクラウドから直接接続するため、このステップに PlaidLink エージェントは不要です。

設定

フィールド	必須	備考
Salesforce接続	はい	読み取りに使用する Salesforce 接続です。接続は Tools > Connections で管理します。
環境	いいえ	読み取る接続の環境です。サンドボックス環境はサンドボックス組織に、本番環境は本番の組織に向けます。デフォルトは、接続の `default` 環境です。
オブジェクト	はい	オブジェクトの API 名です。たとえば `Account`、`Opportunity`、`Invoice__c` です。ピッカーには、接続の Run As ユーザーがクエリできるオブジェクトが一覧表示されます。名前を直接入力することもできるため、検出が利用できない間も、保存済みのステップは動作し続けます。
ターゲットテーブル	はい	行の格納先となるプロジェクトテーブルです。
削除済みおよびアーカイブ済みのレコードを含める	いいえ	Salesforce の `queryAll` と同様に、ごみ箱内のレコードとアーカイブ済みのアクティビティも読み取ります。
フィールド	はい	抽出するフィールドにチェックを付けます。少なくとも 1 つが必須です。Bulk API 2.0 はオブジェクト全体の select を拒否するため、列のリストは常に明示的に列挙されます。
フィルター	いいえ	Salesforce 側で抽出を絞り込みます。Salesforce 側でのフィルターを参照してください。
ウィンドウタグ	いいえ	抽出ウィンドウに名前を付けます。抽出ウィンドウは 1 回だけ実行されるを参照してください。

Id は、チェックを付けたかどうかにかかわらず常に含まれます。再実行のたびにマージする際のキーとなるためです。通貨フィールドでは、オブジェクトに CurrencyIsoCode がある場合は、それも取得されます。

行の格納方法

実行のたびに、フィルターに従ってオブジェクトの全体を読み取り、各ページを Id をキーにしてターゲットテーブルにマージします。テーブルにすでにある行はその場で置き換えられるため、中断された実行を再開しても、同じ行が二重に格納されることはありません。

格納される列は、最初のページのデータから推測した型ではなく、Salesforce 自身のフィールドメタデータで宣言された型を使用します。フィールドピッカーの格納名列がその宣言された型で、フォームで確認した形式がそのままテーブルの形式になります。

格納される型の対応

Salesforce のフィールドタイプ	格納される型
`id`、`reference`、`string`、`textarea`、`phone`、`url`、`email`、`picklist`、`multipicklist`、`combobox`	テキスト
`boolean`	ブール値
`date`	日付
`datetime`	タイムスタンプ
`time`	時刻
`int`	整数。フィールドが 10 桁以上を宣言している場合は 64 ビット整数
`double`、`currency`、`percent`	数値（桁数の大きい小数。38 桁、小数部 10 桁）

この表から、出力をもとに構築する前に知っておくべき 3 つの規則があります。

通貨は、通貨型ではなく数値として格納されます。 実際の組織では、通貨フィールドのスケールが 0、2、3、4 とさまざまなため、すべての数値型は、それらすべてを収められる幅の 1 つの小数型に格納されます。列に通貨記号は付かず、フィールドごとの小数桁数の制約もありません。オブジェクトに CurrencyIsoCode がある場合は、金額が通貨を保持できるように、その列が通貨フィールドと並んで取得されます。単一通貨の組織ではオブジェクトにそのようなフィールドがなく、新たに作られることもありません。
パーセントは、Salesforce が報告する整数のままです。 20 は 0.2 ではなく 20 パーセントを意味します。取り込み時に値のスケールは変更されません。
空の値は NULL として格納されます。 Bulk の結果では、本当の null と明示的な空文字列を区別できないため、どちらもテキストを含むすべての列で NULL として格納されます。空文字列の意味を保持する必要がある列には、Salesforce 側で数式フィールドが必要です。

ステップが拒否するフィールド

Salesforce のフィールドタイプの中には、正しく格納できないものがあります。そのため、フィールドピッカーはそれらを使用不可としてマークし、実行時に失敗するステップを保存させる代わりに、その理由を示します。拒否の際には、フィールド名とその Salesforce タイプが示されます。

Salesforce のフィールドタイプ	理由	代わりの対応
`address`、`location`（複合フィールド）	複合フィールドには、Bulk クエリで直接読み取れる値がありません。	構成要素のフィールドにチェックを付けます。`BillingStreet`、`BillingCity`、`BillingState`、`BillingPostalCode`、`BillingCountry`、ジオロケーションの緯度と経度です。ピッカーには、表示中のフィールドの構成要素が示されます。
`base64`	ファイルや BLOB の内容はインラインでは返されず、このステップが行わない別のバイナリダウンロードが必要です。	レコードの他のフィールドを読み取り、添付ファイルは別途処理します。
`encryptedstring`	Run As ユーザーに View Encrypted Data 権限がない場合、Salesforce はエラーではなくマスクされた値を返し、マスクされたデータと実データを区別する手段がありません。アスタリスクの行を黙って格納するより、拒否するほうが適切です。	そのデータを Salesforce の外に出すべきかどうかを慎重に判断してください。このステップでそれを抽出するサポート対象の方法はありません。
`anyType`	実際の型は行ごとに異なる場合があり、テーブルの列には型が 1 つしかありません。	型のあるフィールド、または値をテキストとして出力する数式フィールドを抽出します。
ステップが認識しないタイプ	テキストとして格納すると値の意味が気付かないうちに変わってしまうため、格納せずに拒否されます。	サポートに連絡して、そのタイプのマッピングを追加してもらってください。

抽出ウィンドウは 1 回だけ実行される

ウィンドウタグは、実行がロードするデータのウィンドウに付ける名前です。期間や、2026-09 のようなバッチラベルを指定します。ワークフロー変数を使用できます。{period} というタグは、ステップを実行するたびにその変数の値に解決されます。

抽出ウィンドウは 1 回だけ実行されます。すでに完了したウィンドウを再実行しても、Salesforce には再度アクセスしません。ステップは、再読み取りを行わなかったことを明確に報告し、表示される行数は以前の実行のものであることも伝えます。これは黙って何もしないのではなく、明示的に何もしないという動作です。これにより、すでに格納した結果セットの 2 つ目のコピーをページ送りで取得してしまうことを防ぎます。

このステップの使い方は 3 通りあります。

タグを空白のままにして、1 回限りのロードとして使用します。最初の実行では読み取りを行い、同じステップの 2 回目の実行ではリプレイされ、再読み取りを行わなかったことが報告されます。抽出の構築と検証、および 1 回だけロードするテーブルに使用します。
タグを入力し、次のウィンドウをロードするときに変更します。たとえば 2026-09、次に 2026-10 とします。タグを編集すると新しいウィンドウが始まるため、手動で進める月次ロードは、見たとおりに動作します。
ワークフロー変数からタグを構築します。無人で定期的に取得する場合に使用します。たとえば {period} を、ワークフローの前段のステップでロード対象の期間に設定します。スケジュール実行のたびに独自のウィンドウが指定され、同じ期間内での再実行は、別のウィンドウを開始する代わりに、そのウィンドウを再開またはリプレイします。

REST API や MCP の呼び出し元は、extract_tag を直接渡し、ウィンドウごとに異なる値を自分で指定します。

中断された実行は同じウィンドウを再開するため、そのウィンドウが完了する可能性がある間は、タグを一定に保ってください。タグを変更すると、新しいウィンドウと Salesforce への新しいクエリが始まります。フィルターやフィールドを変更するときは、タグも変更してください。すでに実行されたタグのまま設定を編集すると、競合として拒否されます。

Salesforce 側でのフィルター

オブジェクト全体を取得してから絞り込むのではなく、Salesforce 側で抽出を絞り込みます。各フィルター条件は、フィールド、演算子、値で構成され、条件は AND で結合されます。値には、{region} のようなワークフロー変数を使用できます。

演算子	備考
`=`、`!=`、`<`、`<=`、`>`、`>=`	入力した値と比較されます。
`LIKE`	ワイルドカードには `%` を使用します。たとえば `Acme%` です。
`IN`、`NOT IN`	値のカンマ区切りリストを指定します。

フィールドと演算子は、クエリが構築される前に、選択したフィールドに対してチェックされます。また、自由記述の WHERE 句を書くことはできないため、フィルターが抽出の範囲外に及ぶことはありません。フィルターには、チェックを付けたフィールドを使用してください。抽出で選択されていないフィールドを指定したフィルターは拒否されます。

ステップには、行数の上限もソートも用意されていません。Bulk API 2.0 は、クエリにそのどちらかが含まれると内部のチャンク分割を無効にするため、大規模な抽出が遅くなり、タイムアウトしやすくなります。クエリが大きすぎる、または遅すぎる場合の Salesforce 自身の対処法は、絞り込み条件を厳しくすることです。

取得量と更新頻度の適合性

オブジェクト全体をスケジュールで読み取るこの方式は、取得量も更新頻度も中程度のオブジェクト（取引先、商談、リード、キャンペーン、同程度の規模のカスタムオブジェクト）に適しています。

Task、EmailMessage、毎日数百万行が変更される大規模なカスタムオブジェクトなど、取得量が多く更新頻度も高いオブジェクトには適していません。毎晩の全件取得では、増分同期であれば不要な実行時間と API の処理能力を消費します。オブジェクトは大きいものの、必要なのが一部だけの場合は、日付範囲、レコードタイプ、所有者などで抽出を絞り込むフィルターを使うと、中程度の取得量に戻せます。

実行が完了しない場合

状況	原因	対応
15 分後もジョブが実行中であるという警告	ステップはフォアグラウンドで Salesforce のクエリ完了を待機しますが、その待機時間には上限があります。バックグラウンドでジョブを進める処理はありません。	ステップを再実行します。同じ Salesforce ジョブの待機が再開され、2 つ目のジョブが送信されることはありません。上限を繰り返し超える場合は、絞り込み条件で抽出を絞ってください。
ウィンドウがすでに完了しており、再読み取りされなかったという警告	このウィンドウは以前に実行されています。表示されている行数は、以前の実行のものです。	別のウィンドウタグで抽出を実行するか、タグの元になっている変数を進めてください。抽出ウィンドウは 1 回だけ実行されるを参照してください。
失敗または中止されたジョブを示すエラー	失敗した Bulk クエリジョブは、部分的な結果を返さず、再開することもできません。そのウィンドウはすでに使用済みです。	別のウィンドウタグで再実行します。同じウィンドウを再実行すると失敗がリプレイされ、何も送信されません。また、同じタグのままステップの設定を編集すると、競合として拒否されます。
Salesforce のリクエスト上限を示す拒否	組織の 24 時間ローリングの API リクエスト許容量を使い切っています。Salesforce には、これに対するリトライ待機時間のドキュメントがありません。	ウィンドウが解消されるまで待ってから再実行します。抽出は引き続き再開可能で、失われたものはありません。
1 つのフィールドとその Salesforce タイプを示す拒否	そのフィールドタイプは格納できないか、Run As ユーザーがそのフィールドを読み取れません。	ステップが拒否するフィールドと、Run As ユーザーのフィールドレベルセキュリティを参照してください。

Salesforce は、完了したクエリジョブの結果を 7 日間取得可能な状態で保持します。これにより、中断された抽出を再開できますが、同時に、結果が失われるまで再開を待てる期間の上限にもなります。ジョブは、Salesforce の Setup > Environments > Jobs > Bulk Data Load Jobs で確認できます。