FIELDS()

取得すべき項目が多数ある場合は、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

1SELECT Id, FIELDS(ALL) FROM User LIMIT 200

1HTTP/1.1 400 Bad Request
2[
3   {
4      "message" : "duplicate field selected: Id",
5      "errorCode" : "INVALID_FIELD"
6   }
7]

FIELDS() は、サブクエリでも使用できます。次に例を示します。

1SELECT
2   Account.Name, 
3   (SELECT FIELDS(ALL) FROM Account.Contacts LIMIT 200)
4FROM Account

FIELDS() は、次のプラットフォーム機能でサポートされます。

• Apex
• SOQL 言語 (query または queryAll 操作を実行できる場所であればどこでも)。
• Salesforce CLI。
• Lightning Platform REST API の /query および /queryAll リソース。
• Lightning Platform SOAP API の query() および queryAll() 操作。

  SOAP API インテグレーションを構築するときは、グループオプションが STANDARD、CUSTOM、ALL の FIELDS() を採用する場合に注意してください。組織のオブジェクトモデルに対する変更 (システム管理者による変更、機能の有効化、メジャーリリースによる更新など) は Enterprise WSDL ですぐに反映する必要があります。反映しなかった場合、クエリ操作でクライアントとの契約に一致しない結果が返されるため、エラーが発生します。

  オブジェクトモデルとの結び付きが弱いため、Partner WSDL はオブジェクトモデルと基になる XML の違いの対象になりません。

  メモ

• Bulk API 2.0 のクエリジョブ。

次の例では、Salesforce CLI で FIELDS() が使用されています。

1sfdx force:data:soql:query -u DevHub --query "SELECT FIELDS(STANDARD) FROM Account"

(この例では、API のバージョン 51.0 以降で機能するように CLI が更新されているものと想定しています。)

この要求では、REST API の /query で FIELDS() が使用されています。

1GET https://yourInstance.salesforce.com/services/data/v56.0/query?​q=SELECT+FIELDS(STANDARD)+FROM+Account

1POST https://yourInstance.salesforce.com/services/Soap/c/56.0
2
3<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:enterprise.soap.sforce.com">
4   <soapenv:Header>
5          <urn:SessionHeader>
6         <urn:sessionId>sessionId</urn:sessionId>
7      </urn:SessionHeader>
8   </soapenv:Header>
9   <soapenv:Body>
10      <urn:query>
11         <urn:queryString>SELECT FIELDS(STANDARD) FROM Account</urn:queryString>
12      </urn:query>
13   </soapenv:Body>
14</soapenv:Envelope>

この要求では、一括クエリジョブを作成するときに FIELDS() が使用されています。

1POST https://yourInstance.salesforce.com/services/data/v56.0/jobs/query
2{
3  "operation": "query",
4  "query": "SELECT FIELDS(STANDARD) FROM Account"
5}

• 取得する項目がすでにわかっている場合は、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.

• SELECT ステートメントが返すデータの量が多く、取得にコストがかかる場合、SOQL は、結果を自動的にページ単位で表示します。この状況は、たとえば、オブジェクトに多数の項目が含まれている場合や、CLOB 項目または BLOB 項目が含まれている場合に発生することがあります。また、FIELDS() が大量のデータを返す場合にも発生することがあります。結果のすべてのページを取得するには、次のいずれかの方法を使用します。

  • Bulk API 2.0 では、ジョブの結果で返される Sforce-Locator 応答ヘッダーを使用します。

  • REST API では、/query および /queryAll で返される nextRecordsUrl を使用します。

  • SOAP API では、queryMore() を使用します。

  • SOQL では、SOQL クエリで OFFSET と LIMIT を使用する場合、返されるレコード数が LIMIT よりも少なくなることがあります。返された結果の数を確認し、必要に応じて OFFSET を調整します。OFFSET を LIMIT のみで増分しないでください。

• カスタム項目がないオブジェクトで SELECT FIELDS(CUSTOM) を使用すると、結果がエラーになります。

  1HTTP/1.1 400 Bad Request
  2[ 
  3   {
  4      "message": "'FIELDS(...)' expansion function must result in at least one field being selected.",
  5      "errorCode" : "MALFORMED_QUERY"
  6   }
  7]

  項目リスト内の項目が実際に存在すれば、エラーは発生しません。たとえば、次のクエリは、状況コード 200 を返します (オブジェクトにカスタム項目が含まれていない場合でも)。

  1SELECT Id, FIELDS(CUSTOM) FROM User LIMIT 200

• FIELDS() で返される項目のリストは、組織のメタデータとデータモデルの現在の状態を反映しています。このため、クライアントは、メタデータやデータモデルが変化したときにさまざまな結果を受け入れる準備を整えておく必要があります。これらの変化は、クエリのパフォーマンスに影響を与える場合もあります。