SOQL および SOSL リファレンス
jSOQL SELECT の構文
SOQL クエリ構文は、必須の SELECT ステートメントとそれに続く 1 つ以上の省略可能な句 (TYPEOF、WHERE、WITH、GROUP BY、ORDER BY など) で構成されます。
SOQL SELECT ステートメントでは、次の構文を使用しま��。
1SELECT fieldList [subquery][...]
2[TYPEOF typeOfField whenExpression[...] elseExpression END][...]
3FROM objectType[,...]
4 [USING SCOPE filterScope]
5[WHERE conditionExpression]
6[WITH [DATA CATEGORY] filteringExpression]
7[GROUP BY {fieldGroupByList|ROLLUP (fieldSubtotalGroupByList)|CUBE (fieldSubtotalGroupByList)}
8 [HAVING havingConditionExpression] ]
9[ORDER BY fieldOrderByList {ASC|DESC} [NULLS {FIRST|LAST}] ]
10[LIMIT numberOfRowsToReturn]
11[OFFSET numberOfRowsToSkip]
12[{FOR VIEW | FOR REFERENCE} ]
13[UPDATE {TRACKING|VIEWSTAT} ]
14[FOR UPDATE]| 構文 | 説明 |
|---|---|
| fieldList subquery | 指定した object から取得する、1 つ以上の項目のカンマ区切りのリストを指定します。次の例の太字の要素が fieldlist 値です。
クエリでリレーションをトラバースする場合、fieldList には、サブクエリを含めることができます。次に例を示します。
fieldlist は、COUNT() や COUNT(fieldName) などの集計関数とすることも、返された結果を翻訳する toLabel() 関数でラップすることもできます。詳細は、「SELECT」を参照してください。 |
| typeOfField | 複数のオブジェクト種別を参照できる、objectType の多態的なリレーション項目、または objectType の親の多態的な項目。たとえば、Task の Who リレーション項目には、Contact または Lead のいずれかを使用できます。typeOfField は、fieldList でも参照されているリレーション項目は参照できません。詳細は、「TYPEOF」を参照してください。 |
| whenExpression | WHEN whenObjectType THEN whenFieldList という形式の句。TYPEOF 式内には、1 つ以上の whenExpression 句を使用できます。詳細は、「TYPEOF」を参照してください。 |
| elseExpression | ELSE elseFieldList という形式の句。これは、TYPEOF 式内の省略可能な句です。詳細は、「TYPEOF」を参照してください。 |
| objectType | query() の対象オブジェクトの種別を指定します。Account など、有効なオブジェクトを指定します。そのオブジェクトの参照レベルの権限を持っている必要があります。 |
| filterScope | API バージョン 32.0 以降で使用できます。filterScope は、クエリの結果を制限するために指定します。 |
| conditionExpression | WHERE が指定されている場合は、指定したオブジェクト (objectType) 内で絞り込みをする行と値が判断されます。指定されていない場合、query() はオブジェクト内でユーザが参照可能なすべての行を取得します。 |
| filteringExpression |
WITH DATA CATEGORY が指定されている場合、query() は指定したデータカテゴリに関連付けられていて、ユーザが参照可能な、条件に一致するレコードのみを返します。指定されていない場合、query() はユーザが参照可能な、条件に一致するレコードを返します。WITH DATA CATEGORY 句は次の種別のオブジェクトのみを絞り込みます。
WITH DATA CATEGORY が指定されていない場合、filteringExpression を使用して、項目およびオブジェクトレベルの権限を強制したり、Apex コードでユーザまたはシステムモードのアクセスを指定したりできます。
|
| fieldGroupByList | API バージョン 18.0 以降で使用できます。クエリ結果をグループ化するために使用される 1 つ以上の項目のカンマ区切りのリストを指定します。GROUP BY 句は、データを集計するために、集計関数と共に使用します。この句によって、コード内で個々のレコードを処理せずに、クエリ結果を積み上げ集計できます。「GROUP BY」を参照してください。 |
| fieldSubtotalGroupByList | API バージョン 18.0 以降で使用できます。クエリ結果をグループ化するために使用される項目を最大 3 つまでカンマで区切って指定します。結果にはグループ化されたデータの小計行が含まれます。「GROUP BY ROLLUP」および「GROUP BY CUBE」を参照してください。 |
| havingConditionExpression | API バージョン 18.0 以降で使用できます。クエリに GROUP BY 句が含まれている場合、この条件式では GROUP BY によって返されるレコードが絞り込まれます。「HAVING」を参照してください。 |
| fieldOrderByList | クエリ結果を並び替えるために使用される 1 つ以上の項目のカンマ区切りのリストを指定します。たとえば、取引先責任者を照会し、結果を姓、次に名の順に並び替えることができます。 |
SELECT ステートメントの実装のヒント
- ステートメントの文字数制限 — デフォルトでは、SOQL ステートメントの長さは 100,000 文字を超えることができません。この最大長を超える SOQL ステートメントでは、API は MALFORMED_QUERY 例外コードを返します。結果の行は返されません。
-
ステートメントが多数の結果を返す場合 — SELECT 文がレコードごとに大量のデータを返す場合、SOQL によって自動的に結果の数が減らされます。リストビューを検索すると、リストの最初の 2,000 件のレコードのみが検索されます。オブジェクトに数式項目、派生項目、CLOB 項目、または BLOB 項目が含まれる場合は、大量のデータが返される場合もあります。結果のすべてのページを取得するには、次のいずれかの方法を使用します。
- SOQL では、SOQL クエリで OFFSET と LIMIT を使用する場合、返されるレコード数が LIMIT よりも少なくなることがあります。返された結果の数を確認し、必要に応じて OFFSET を調整します。OFFSET を LIMIT で増分しないでください。
- SOAP API では、queryMore() を使用します。
- REST API では、/query および /queryAll で返される nextRecordsUrl を使用します。
- Bulk API 2.0 では、ジョブの結果で返される Sforce-Locator 応答ヘッダーを使用します。
- 結果のローカライズ — SELECT ステートメントには、ローカライズされた項目をサポートする toLabel()、convertCurrency()、および FORMAT() 関数を含めることができます。
- Apex の動的 SOQL — Apex では、使用しているステートメントで SOQL や SOSL ステートメントを使うには、角括弧で囲む必要があります。前にコロン (:) がある場合は、Apex スクリプト変数と式を使用できます。
- 結果の並び替え — クエリで ORDER BY 句を使用しない限り、結果の順序は保証されません。
- 選択リスト値 — API バージョン 39.0 以降では、値の API 参照名で選択リスト値を照会するため、実際の値とは異なる可能性があります。
- クエリタイムアウトの回避 — WHERE または WITH 句を使用して、クエリ操作時間を短縮することを検討してください。REST API では、クエリ処理に関する情報を得るために、explain パラメータ (ベータ) を試すことも可能です。詳細は、『REST API 開発者ガイド』の「クエリのパフォーマンスに関するフィードバックを取得する」を参照してください。