Abfragen und Paginierung

Liste per GET oder Abfrage per POST#

GET /{resource} und POST /{resource}/query nutzen denselben Lesepfad. GET codiert Filter im einzelnen Parameter filter; POST nutzt ein filters-Array im JSON-Anfragekörper. POST /query funktioniert mit einem Leseschlüssel. Unbekannte oder wiederholte Queryparameter ergeben 400 invalid_request.

Zertifizierte Filter verwenden#

Jeder Filter enthält field, op und bei Bedarf value. Felder, Operatoren und Werte werden gegen die Arbeitsbereichsfähigkeiten geprüft. Ein natives Feld nutzt seinen Schlüssel, ein benutzerdefiniertes den beschriebenen filter_key, ein verknüpftes Feld rel:<foreign-key-column>.<column>.

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'

Paginierungsmetadaten lesen#

Eine Liste liefert data und meta. Seitenmodus enthält page, page_size, total und has_more. total_is_capped: true bedeutet, dass total eine Untergrenze ist. Seitennummern erreichen ein Offsetfenster bis 10.000; darüber folgt 400 mit details.max_page. Verwenden Sie Cursors für Exporte und tiefe Synchronisierung.

{
  "data": [{ "id": "c91b7028-f985-4bc1-9f75-c76533c3133a", "name": "Northfold" }],
  "meta": { "page": 1, "page_size": 25, "total": 1, "has_more": false }
}

Mit einem undurchsichtigen Cursor laufen#

Senden Sie cursor=start, dann meta.next_cursor unverändert, bis der Wert null ist. Senden Sie nicht zusätzlich page. Halten Sie Filter, Sortierung und weitere Einstellungen während des Laufs konstant. Ein Cursor ist eine Position, kein Snapshot eines sich ändernden Arbeitsbereichs.

• Cursorantworten enthalten page_size, next_cursor, cursor_supported, total und has_more.
• Textrelevanzsortierung kann nicht durchlaufen werden; cursor_supported ist auf der ersten Seite false. Nutzen Sie dafür Seitenmodus.
• Ein positionierter Cursor, der nicht zur Abfrage passt, ergibt 400. Beginnen Sie nach Änderung von Sortierung oder Filtern neu.
• Behandeln Sie Cursors als undurchsichtig. Nicht decodieren, bearbeiten oder selbst erstellen.

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;
}