Force.com SOQL および SOSL リファレンス
jOFFSET
クエリ結果に大量のレコードが含まれると予想される場合、SOQL クエリに OFFSET 句を使用して結果を複数ページに表示できます。たとえば、OFFSET を使用して 51 ～ 75 番目のレコードを表示した後、スキップして 301 ～ 350 番目のレコードを表示できます。OFFSET を使用すると、大きな結果セットを効率よく処理できます。
クエリによって返される結果セットへの開始行オフセットを指定するには、OFFSET を使用します。オフセットの計算はサーバで実行されて結果サブセットのみが返されるため、完全な結果セットを取得して結果をローカルで絞り込むよりも OFFSET を使用した方が効率的です。OFFSET は、API バージョン 24.0 以降で使用できます。
1SELECT fieldList
2FROM objectType
3[WHERE conditionExpression]
4ORDER BY fieldOrderByList
5LIMIT numberOfRowsToReturn
6OFFSET numberOfRowsToSkip例として、SOQL クエリが通常は 50 行を返す場合、クエリで OFFSET 10 を使用して最初の 10 行をスキップできます。
1SELECT Name
2FROM Merchandise__c
3WHERE Price__c > 5.0
4ORDER BY Name
5LIMIT 100
6OFFSET 10前述の例の結果セットは、完全な結果セットの行 11 ～ 50 が返されたサブセットです。
OFFSET を使用するときの考慮事項
クエリで OFFSET を使用する場合、次のいくつかの事項を考慮してください。
- 最大オフセットは 2,000 行です。2,000 より大きいオフセットを要求すると NUMBER_OUTSIDE_VALID_RANGE エラーが発生します。
-
OFFSET は最上位のクエリでのみ使用可能で、ほとんどのサブクエリでは使用できないため、次のクエリは無効であり、MALFORMED_QUERY エラーを返します。サブクエリは、親クエリに LIMIT 1 句がある場合に限りOFFSETを使用できます。次のクエリは、サブクエリでの OFFSET の有効な使用を示します。
1SELECT Name, Id 2FROM Merchandise__c 3WHERE Id IN 4 ( 5 SELECT Id 6 FROM Discontinued_Merchandise__c 7 LIMIT 100 8 OFFSET 20 9 ) 10ORDER BY NameOFFSET は、親クエリに LIMIT 1 句がある場合でも WHERE 句のサブクエリとして使用できません。1SELECT Name, Id 2 ( 3 SELECT Name FROM Opportunity LIMIT 10 OFFSET 2 4 ) 5FROM Account 6ORDER BY Name 7LIMIT 1 - OFFSET を使用する場合、結果セットの順序付けの一貫性を保つため ORDER BY 句を使用することをお勧めします。ORDER BY 句を使用しない結果セットの行の順序は一定ですが、順序付けキーは変更される可能性があるため信頼しないようにしてください。
- 同様に、同じ結果セットの後続のサブセットを取得する必要がある場合は、LIMIT 句を OFFSET と組み合わせて使用することをお勧めします。たとえば、次を使用してクエリの最初の 100 行を取得できます。その後、以下のクエリを使用して次の 100 行 (101 ～ 201) を取得できます。
1SELECT Name, Id 2FROM Merchandise__c 3ORDER BY Name 4LIMIT 100 5OFFSET 01SELECT Name, Id 2FROM Merchandise__c 3ORDER BY Name 4LIMIT 100 5OFFSET 100 -
OFFSET は、クエリの時点で返された結果セットに適用されます。その後の OFFSET クエリで完全な結果セットをキャッシュするサーバ側のカーソルは作成されません。OFFSET を使用して同じ結果セットに複数のクエリを実行しているときに、基になるデータが変更された場合、ページ結果が変更される可能性があります。たとえば、次のクエリは通常は 50 行の完全な結果セットを返し、OFFSET 句を使用して最初の 10 行がスキップされるとします。クエリが実行された後に、並び替え順で先頭になる Name 値を含む新しい 10 行が Merchandise__c に挿入されます。同じ OFFSET 値でクエリを再度実行すると、異なる行のセットがスキップされます。一貫したサーバ側カーソルでレコードの複数のページをクエリする必要がある場合は、SOAP API の queryMore() を使用します。
1SELECT Name 2FROM Merchandise__c 3ORDER BY Name 4OFFSET 10 - 最大オフセットサイズとサーバ側カーソルの欠如を考慮すると、オフセットは queryMore() の代わりに使用するようには意図されていません。大きな結果セットへのオフセットを含む複数のクエリは、サーバ側カーソルに対して queryMore() を使用するよりもパフォーマンス上の影響が大きくなります。
- OFFSET を使用する場合、所定のクエリではレコードの最初のバッチのみが返されます。次のバッチを取得する場合、オフセット値を高くしたクエリを再実行する必要があります。
- OFFSET 句は、SOAP API、REST API、および Apex で使用される SOQL で許可されます。Bulk API またはストリーミング API 内で使用される SOQL では許可されません。