Query records

Query rows

Use the structured query model for most requests. It supports:

bounded pagination;
field projection;
nested and, or, and not filters;
sorting, grouping, and distinct selection;
type-aware casts;
supported joins and common table expressions on surfaces that explicitly allow them.

const result = await api.getDatabaseData('orders', {
  fields: ['orderId', 'customerId', 'total', 'status'],
  filter: {
    and: [
      { field: 'status', op: 'eq', value: 'READY' },
      { field: 'total', op: 'gte', value: 100, filterType: 'number' },
    ],
  },
  sort: { createdAt: 'DESC' },
  take: 100,
});

This returns up to 100 ready orders with totals of at least 100, newest first. Show it as a bounded page in the UI. For a full scan, follow the returned paging contract and use a stable order. See bounded reads.

Platform API read paths

The generated Platform API exposes two complementary read operations:

Operation	Use it for
Get Database data	Query-string filtering, projection, sorting, joins, casts, pagination, and count. An explicit `take` is validated up to 10,000; larger values are rejected rather than silently treated as 10,000.
Query Database data with a request body	A structured JSON query when nested filters, joins, expressions, or casts are awkward to encode in a URL. Joined Tables are authorization-checked independently.

Both return data, results, and next, plus total only when count is requested. The body-based query does not publish a larger guaranteed page ceiling. Keep pages bounded and prefer keyset-like business filters for large data sets instead of increasing skip indefinitely.

Preview a read plan

Use debug: true on api.getDatabaseData to inspect the complete estimated read plan before fetching records. count: true also previews the count plan. The result contains debug.explain and optional debug.countExplain; it contains no records or pagination result. Omit debug to fetch records normally.

const diagnostic = await api.getDatabaseData('orders', {
  fields: ['orderId'],
  filter: { field: 'status', op: 'eq', value: 'OPEN' },
  take: 100,
  debug: true,
});
console.log(diagnostic.debug.explain.join('\n'));

This option retains normal data access checks and query validation. Use it on getDatabaseData, rather than row, count or walk helpers. An unsupported data source rejects the diagnostic request without running the read. Continue with databases.

Start here

Build and integrate

Operate

AI and Agents

Help

Query rows

Platform API read paths

Preview a read plan

​Query rows

​Platform API read paths

​Preview a read plan

Query rows

Platform API read paths

Preview a read plan