Queries
The query language over HTTP: where, order, limits, cursors.
The shape of a query
GET /v1/projects/{project}/collections/{collection}/records
?where=[["status","==","open"],["priority",">",2]]
&orderBy=created_at&direction=desc
&limit=50
&cursor=…where is a JSON array of [field, operator, value] triples, combined with AND.
Operators
| Operator | Meaning |
|---|---|
==, != | Equality. |
>, >=, <, <= | Ordering — numeric for number, chronological for datetime. |
contains | Substring match on text. |
in | Value is one of a list. |
Only fields in the collection's schema can be filtered or sorted, and only these operators are
accepted. Values are always bound, never interpolated — the query language is not a SQL
passthrough and cannot be made into one.
Paging
A response carries records and, when more exist, a cursor. Pass it back
as ?cursor=… for the next page. Cursors are stable under inserts, so paging does not
skip or repeat rows the way an offset does.
let cursor = null;
do {
const url = new URL(base + '/collections/tasks/records');
url.searchParams.set('limit', '100');
if (cursor) { url.searchParams.set('cursor', cursor); }
const page = await fetch(url, { headers }).then(r => r.json());
handle(page.records);
cursor = page.cursor ?? null;
} while (cursor);Rules still apply
A query returns only records the caller may read. Filtering happens after the rule, not instead of it — an unauthorised record is absent, never merely hidden client-side. Security rules →