SOQL および SOSL リファレンス
jSELECT
fieldList で FIELDS() キーワードを使用すれば、事前に名前を把握していなくても項目のグループを選択できます。このキーワードによって SELECT ステートメントが簡単になり、複数の API コールも不要となります。このため、少ないコードで組織のデータを調査できます。このキーワードは、API バージョン 51.0 以降で使用できます。
取得すべき項目が多数ある場合は、SOQL SELECT ステートメントの項目リスト (SELECT Id, Name FROM Account など) の使用が複雑になる場合があります。オブジェクトの項目がわからない場合は、最初にオブジェクトの説明を取得する必要があります。通常は、最初にコールを使用してオブジェクトの説明を取得し、その説明を解析して項目を確認します。次に、項目を指定した SOQL クエリを作成して、別のコールで送信します。
この手順を簡略化できるように、FIELDS() キーワードでは、事前に名前を把握していなくても項目を簡単に選択できます。FIELDS() キーワードにより、SOQL ステートメントを準備するためのサーバへのアクセスが不要になります。これにより、クエリステートメントを簡略化でき、オブジェクトの概要を簡単に把握できるようになります。また、SOQL クエリの文字制限を超えたり、REST コールの URI 長制限を超えたりすることも避けることができます。
項目リストに次の関数を含めることができます。
- FIELDS(ALL) — オブジェクトのすべての項目を選択します。
- FIELDS(CUSTOM) — オブジェクトのすべてのカスタム項目を選択します。
- FIELDS(STANDARD) — オブジェクトのすべての標準項目を選択します。
それぞれのケースにおいて、FIELDS() では、項目レベルのセキュリティが考慮されるため、自分にアクセス権がある項目しか表示されません。
使用方法
FIELDS() は、完全な項目リストとして使用できます。次に例を示します。
- SELECT FIELDS(ALL) FROM Account LIMIT 200
- SELECT FIELDS(CUSTOM) FROM Account LIMIT 200
- SELECT FIELDS(STANDARD) FROM Account
FIELDS() は、項目リストの他の項目名と共に使用することもできます。次に例を示します。
- SELECT Name, Id, FIELDS(CUSTOM) FROM Account LIMIT 200
- SELECT someCustomField__c, FIELDS(STANDARD) FROM Account
FIELDS() キーワードは、サブクエリでも使用できます。次に例を示します。
FIELDS() のサポート
FIELDS() キーワードは、次のプラットフォーム機能でサポートされます。サポート内容の制限については、「制限クエリおよび無制限クエリ」を参照してください。
- Apex
- SOQL 言語 (query または queryAll 操作を実行できる場所であればどこでも)。
- Bulk API 2.0 のクエリジョブ。
- Salesforce CLI。
- Lightning Platform REST API の /query および /queryAll リソース。
- Lightning Platform SOAP API の query() および queryAll() 操作。
SOAP API インテグレーションを構築するときは、グループオプションが STANDARD、CUSTOM、ALL の FIELDS() を採用する場合に注意してください。組織のオブジェクトモデルに対する変更 (システム管理者による変更、機能の有効化、メジャーリリースによる更新など) は Enterprise WSDL ですぐに反映する必要があります。反映しなかった場合、クエリ操作でクライアントとの契約に一致しない結果が返されるため、エラーが発生します。
制限クエリおよび無制限クエリ
API では、制限クエリと無制限クエリが区別されます。制限クエリの一連の項目は明確に定義されていますが、無制限クエリの一連の項目は API が事前に判断できません。たとえば、オブジェクトのカスタム項目の数は事前に決定されていないため、FIELDS(CUSTOM) と FIELDS(ALL) は無制限とみなされます。次の表は、制限クエリと無制限クエリの FIELDS() のサポート状況を示しています。
結果行の制限
結果行を制限するには、クエリに次のいずれかの制限を追加します。
-
LIMIT n (n は 200 以下です)。次に例を示します。
-
WHERE Id IN idList (idList は ID のリストで最大 200 個指定できます)。次に例を示します。
-
WHERE Id IS idList (idList は Boolean 演算子と結合された ID テストのリストで最大 200 個指定できます)。次に例を示します。
Salesforce CLI の例
次の例では、Salesforce CLI で FIELDS() が使用されています。
この例では、API のバージョン 51.0 以降で機能するように CLI が更新されているものと想定しています。
REST API の例
この要求では、REST API の /query で FIELDS() が使用されています。
SOAP API の例
この例では、SOAP API の query() で FIELDS() が使用されています。
Bulk API 2.0 の例
この要求では、一括クエリジョブを作成するときに FIELDS() が使用されています。
FIELDS() に関する考慮事項
FIELDS() キーワードを使用するときには、次の点を考慮してください。
-
取得する項目がすでにわかっている場合は、FIELDS() を使用して必要以上に項目を取得するのではなく、目的の項目を明示的に指定すれば、パフォーマンスが向上します。
-
FIELDS() は、集計が必要な演算子と一緒に使用すると、エラーが発生する場合があります。
-
たとえば、次のクエリは、FIELDS() が含まれておらず、正常に機能します。
SELECT Id, MIN(NumberOfEmployees) FROM Account GROUP BY Id
ただし、クエリに FIELDS() を追加した場合、
SELECT FIELDS(ALL), MIN(NumberOfEmployees) FROM Account GROUP BY Id LIMIT 200「Field must be grouped or aggregated (項目をグループ化または集計する必要があります)」というエラーが発生します。これは、次のクエリに等しくなるためです。
SELECT IsDeleted, <etc.>,MIN(NumberOfEmployees) FROM Account GROUP BY Id LIMIT 200。
-
-
FIELDS() が大量のデータを返す場合、次のいずれかの方法を使用して、結果のすべてのページを取得します。
-
SOQL では、クエリで OFFSET と LIMIT を使用する場合、返されるレコード数が LIMIT よりも少なくなることがあります。返された結果の数を確認し、必要に応じて OFFSET を調整します。OFFSET を LIMIT のみで増分しないでください。
-
Bulk API 2.0 では、ジョブの結果で返される Sforce-Locator 応答ヘッダーを使用します。
-
REST API では、/query および /queryAll で返される nextRecordsUrl を使用します。
-
SOAP API では、queryMore() を使用します。
-
-
カスタム項目がないオブジェクトで SELECT FIELDS(CUSTOM) を使用すると、クエリの結果がエラーになります。
項目リスト内に項目が含まれていなければ、エラーは発生しません。たとえば、次のクエリは、オブジェクトにカスタム項目が含まれていない場合でも状況コード 200 を返します。
-
FIELDS() で返される項目のリストは、組織のメタデータとデータモデルの現在の状態を反映しています。組織のメタデータやデータモデルへのいかなる変更も、クエリのパフォーマンスや結果に影響します。