Gidsen
Query’s en paginering
Filter, sorteer, zoek en blader door records, met cursorpaginering voor integraties die dieper moeten gaan.
Een lijst met GET of een query met POST
GET /{resource} en POST /{resource}/query gebruiken hetzelfde leespad. GET encodeert filters in de enkelvoudige queryparameter filter; POST gebruikt een filters-array in de JSON-body. POST /query werkt met een alleen-lezensleutel. Onbekende of herhaalde queryparameters geven 400 invalid_request.
| Parameter | Betekenis |
|---|---|
page / cursor | Kies één mode. Page is standaard 1; begin een cursorwandeling met start. |
page_size | 1–100 records; standaard 25. |
sort / order | Een sorteerbare veldkey en asc of desc. Standaard: nieuwste eerst. |
search | Vrije tekst op resources met searchable: true; een begrensd venster van 500 kandidaten. |
include_archived | Gearchiveerde records opnemen; standaard false. |
filter / filters, join | Gestructureerde filters, gecombineerd met and (standaard) of or. |
fields | Komma’s tussen namen bij GET; een array bij POST /query. |
model_id | Verplicht voor data_model_records; geldt niet voor andere resources. |
Gecertificeerde filters gebruiken
Elk filter heeft field, op en zo nodig value. Velden, operators en waarden worden gecontroleerd tegen de capabilities van de werkruimte. Een standaardveld gebruikt de veldkey, een aangepast veld de beschreven filter_key, en een gerelateerd veld rel:<foreign-key-column>.<column>.
| Operators | Waarde |
|---|---|
eq, ne, gt, gte, lt, lte | Een compatibele scalaire waarde. |
iLike, notILike | Hoofdletterongevoelige tekstvergelijking. |
inArray, notInArray | Een array met compatibele waarden. |
isBetween | Een bereik met twee waarden. |
isEmpty, isNotEmpty | Geen waarde nodig. |
curl --fail-with-body --request POST "$SQUARIO_API_BASE/companies/query" \
--header "Authorization: Bearer $SQUARIO_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"filters": [{ "field": "name", "op": "iLike", "value": "Northfold" }],
"join": "and",
"page_size": 25,
"fields": ["name"]
}'curl --fail-with-body --get "$SQUARIO_API_BASE/companies" \
--header "Authorization: Bearer $SQUARIO_API_KEY" \
--data-urlencode 'filter=[{"field":"name","op":"iLike","value":"Northfold"}]' \
--data-urlencode 'fields=name' \
--data-urlencode 'page_size=25'De pagineringsmetadata lezen
Een lijst geeft data en meta. Paginamode bevat page, page_size, total en has_more. total_is_capped: true betekent dat total een ondergrens is. Paginanummers bereiken een offsetvenster tot 10.000; verder gaan geeft 400 met details.max_page. Gebruik cursors voor exports en diepe synchronisatie.
{
"data": [{ "id": "c91b7028-f985-4bc1-9f75-c76533c3133a", "name": "Northfold" }],
"meta": { "page": 1, "page_size": 25, "total": 1, "has_more": false }
}Doorlopen met een ondoorzichtige cursor
Stuur cursor=start, vervolgens de ontvangen meta.next_cursor ongewijzigd totdat die null is. Stuur geen page mee. Houd filters, sortering en andere instellingen gelijk tijdens de wandeling. Een cursor is een positie, geen momentopname van een veranderende werkruimte.
- Cursorantwoorden bevatten
page_size,next_cursor,cursor_supported,totalenhas_more. - Sorteren op tekstrelevantie ondersteunt geen wandeling;
cursor_supportedis false op de eerste pagina. Gebruik paginamode voor die query. - Een gepositioneerde cursor die niet bij de query past geeft 400. Begin opnieuw na een gewijzigde sortering of filter.
- Behandel cursors als ondoorzichtig. Decodeer, verander of maak ze niet zelf.
const base = process.env.SQUARIO_API_BASE?.replace(/\/$/, "");
const key = process.env.SQUARIO_API_KEY;
if (!base || !key) throw new Error("Set SQUARIO_API_BASE and SQUARIO_API_KEY");
let cursor = "start";
while (cursor !== null) {
const url = new URL(`${base}/companies`);
url.searchParams.set("cursor", cursor);
url.searchParams.set("page_size", "100");
url.searchParams.set("fields", "name");
const response = await fetch(url, {
headers: { Authorization: `Bearer ${key}` },
signal: AbortSignal.timeout(30_000),
});
const body = await response.json();
if (!response.ok) throw new Error(`${body.error.code} (${body.error.request_id})`);
if (!body.meta.cursor_supported) throw new Error("Use page mode for this sort");
for (const record of body.data) console.log(record.id, record.name);
cursor = body.meta.next_cursor;
}