Salesforce の SOQL の使用

Salesforce Object Query Language (SOQL) は、Salesforce のデータから特定のレコードを検索するために使用されます。SOQL は、広く利用されている Structured Query Language (SQL) の SELECT 文に似ていますが、Salesforce のデータ専用に設計されています。

SOQL クエリーの基本的な構文は次のとおりです: SELECT (項目のリスト) FROM (オブジェクト) WHERE (フィルター文/並べ替え)。

主な Salesforce オブジェクトの標準項目の一覧については、Salesforce Fields Reference (opens new window) を参照してください。

SOQL の WHERE 条件の入力 (構文):

WHERE 句は、項目式の構文に従います。 fieldExpression (項目式) は次のように定義されています: <fieldName (項目名)> <comparisonOperator (比較演算子)> <value (値)>。

比較演算子: 比較演算子には = や !=、<、<=、>、>=、LIKE、IN、NOT IN、INCLUDES、EXCLUDES があります。以下に挙げるのは、fieldExpression 構文に従った簡単な例です。

それぞれの比較演算子の詳しい使い方については、こちらのドキュメントを参照してください: Comparison Operators (opens new window)。

論理演算子: 論理演算子を使用すると、複数の項目式を結合することができます。論理演算子には AND や OR、NOT があります。基本的な構文は以下のとおりです。

• fieldExpressionX AND fieldExpressionY
• fieldExpressionX OR fieldExpressionY
• NOT fieldExpressionX.

以下は、2つの fieldExpression を論理演算子で結合している例です。

論理演算子の詳細については、こちらのドキュメントを参照してください: Logical Operators (opens new window)。

日付形式と日付リテラル

クエリーにおいて date 項目で絞り込むには、日付のみの形式を使用する必要があります。そのための構文は YYYY-MM-DD です。 クエリーにおいて dateTime 項目で絞り込むには、日付、時間、タイムゾーンのオフセットを含んでいる形式を使用する必要があります。このために使用できる構文形式には、以下の3通りがあります。

• YYYY-MM-DDThh:mm:ss+hh:mm
• YYYY-MM-DDThh:mm:ss-hh:mm
• YYYY-MM-DDThh:mm:ssZ.

date や dateTime といった項目についてのクエリーを実行するには、まだ formula モードを使用していない場合、それを有効にする必要があるかもしれません。これはタイムスタンプを、SOQL で想定されている ISO8601 形式に変換するために必要となります。また、date や dateTime の値を一重引用符で囲む必要はないことに注意してください。 date 項目の場合は、日付の formula の末尾に ‘.to_date’ を追加して、日付やタイムスタンプを正しい形式に変換してください。

dateTime 項目の場合は、3番目の構文形式が最も簡単に使用できます。求めているタイムスタンプを得るための formula (now、2.weeks.ago.beginning_of_day など) を入力したら、その末尾に ‘.strftime("%Y-%m-%dT%H:%M:%S%z")’ を付け加えてください。

日付形式と日付リテラルの詳細については、こちらのドキュメントを参照してください: Date Formats and Date Literals (opens new window)。

SOQL を使用するトリガー/アクション

WHERE 句によるクエリー実行

Workato の UI で利用できるフィールドを使って入力を設定し、SOQL クエリーを速やかにセットアップするには、以下のようなトリガーやアクションのいずれかを使用してください。

トリガー

• スケジュール化されたレコード検索 (SOQL クエリーの WHERE 句を使用)

アクション

• SOQL クエリー (API 1.0) を使用してレコードをバルク検索
• SOQL クエリーの WHERE 句を使用してレコードを検索

単に WHERE 句だけを必要とするトリガーやアクションを使用する場合、クエリーの SELECT FROM 部分はレシピが自動的に処理します。そのようなレシピは、ピックリスト Fields to retrieve で選択したオブジェクトから (FROM) すべての項目を選択 (SELECT) します。

LIMIT フィールドや OFFSET フィールドが利用できる場合は、それらの句を指定することもできます。ただし、これらはバルクアクションではサポートされていないことに注意してください。

完全な SOQL クエリーによるクエリー実行

完全な SOQL クエリーを使用したい場合、または Salesforce や Workbench でクエリーのテストを実行してからコピー＆ペーストする場合は、以下のようなトリガーやアクションのいずれかを使用してください。

トリガー

• スケジュール化されたレコード検索 (SOQL クエリーを使用)

アクション

• SOQL クエリー (API 2.0) を使用してレコードをバルク検索
• SOQL クエリーを使用してレコードを検索

SOQL クエリーのフィールドに、以下の例のように SOQL クエリーを入力してください。

TIP

SQL クエリーでは SELECT * 操作がよく使用されますが、SOQL クエリーではそのパターンがサポートされていません。ユーザーは取得する項目を SELECT 句の中で指定する必要があります。また、SOQL クエリーは最大長が16,000文字であることにも注意してください。

出力スキーマを生成するには、[Use SOQL] ボタンをクリックしてください。ユーザーは、この SOQL クエリーのフィールドにも同じ SOQL を使用する必要があります。クエリーが実行されると、サンプル行が返され、出力が自動的に生成されます。

これにより、以降のレシピステップでは、この SOQL クエリーからの出力にデータツリーでアクセスできるようになりました。

その他の句

検索で返される結果の数を制限するには、LIMIT 句を使用します。また、結果を返す前に一定数の行をスキップする必要がある場合は、OFFSET 句を利用できます。どちらの句についても、最大値は2,000です。2,000件より多くのオフセットをリクエストすると、'NUMBER_OUTSIDE_VALID_RANGE' エラーが発生します。

そのほかのドキュメント

さらにヘルプが必要な場合は、Salesforce の以下のドキュメントを参照してください。

• SOQL (opens new window)
• WHERE Clause Syntax (opens new window)