ビュー・並び順・ページネーション

一覧は 2 種類でページングが異なり、ビューはフィルターとソートを持ち、カーソルは生成時の順序を運び、そしてすべてのフィールドを並び替えられるわけではありません。

ページング

一覧には 2 種類あり、ページングの方法が異なります。

ほとんどの一覧（商品、価格表、見積）は limit と after を取り、nextCursor を返します。次のページには nextCursor を after として渡し、null になったら終了します。nextCursor はそのページ最後の行の id です。

limit は 1 から 100 で、既定は 50。これはどちらの一覧でも同じです。

レコードの一覧はより多くを取ります。limit、dir、orderBy または view、relatedTo と via、そして cursor または after です。4 つの組み合わせは 400 で拒否され、これらはパラメータ一覧では表現できません。

• via には relatedTo が必要
• orderBy と view は併用できない
• cursor には orderBy か view のいずれかが必要
• after はそのどちらとも併用できない。順序付きのクエリは cursor でページングする

カーソルはそれを生成した順序に属します。 順序 — ソート、方向、関連レコードのフィルター、ビュー — はカーソルの内部に入っています。ビューが変わった後にカーソルを再利用すると、正しそうに見えて実際は違うページを返すのではなく、cursor_ordering_mismatch で明示的に失敗します。順序が変わったら最初のページから取り直してください。

total は最初のページでのみ数えられます。 after も cursor もないリクエストは件数を返し、以降のページは total: null を返します。件数は毎ページではなく一度だけ支払われるため、表示したい場合は最初のページの値を保持してください。

ビューはフィルターとソートをまとめたもの

ビューは条件、その結合方法、そしてソートを持ちます。条件は最大 10 件、ソートは最大 2 件です。match は all か any で既定は all なので、指定しないビューは広げるのではなく絞り込みます。

条件はフィールド、演算子、そして演算子によっては値を指定します。演算子は 4 系統に 33 個あり、系統が条件の形を決めます。

演算子は API ではなくフィールドの種類に属します。 テキストフィールドはテキスト系、数値フィールドは数値系を取り、その集合はほとんど重なりません。

この表の外の組み合わせは無視されるのではなく filter_unsupported_for_field で拒否されます。ユーザー入力から条件を組み立てる前にフィールドの種類を読んでください。

すべてのフィールドを並び替えられるわけではない

並び替えにはデータベースが生成できる全順序と、カーソルが運べる単一の値が必要です。5 つの種類はそのどちらも持ちません。

• relation、multi_select、address は並び替えの基準になる単一の値を持ちません。
• rollup と days_since は列そのものがなく、クライアントが計算します。

それ以外は並び替えできます。この 5 つを orderBy に指定すると order_field_unsupported で拒否されます。カーソルに現れられないのも同じ理由です。