Skip to content
Aurabase Logo
aurabase

Read rows

GET/v1/db/{project_id}/{table}

Query a table with filters, order, pagination and joins. PostgREST under the hood, RLS applied automatically.

Headers#

HeaderRequiredValue
apikeyyesProject API key (anon or service_role). X-API-Key is accepted too.
AuthorizationnoBearer <JWT>. Without it, the request runs as anon

Query parameters#

ParameterTypeRequiredDescription
selectstringnoColumns to return. * by default. Relationship embed (FK): posts(*), author:authors(name).
orderstringnocaptured_at.desc · name.asc. NULL placement (.nullsfirst/.nullslast) is only honored on MongoDB in its native form (asc.nullsfirst, desc.nullslast); the other two combinations are refused in 400 rather than issuing an order different from that requested.
limitintegernoMax number of lines. Default 1000, max 1000 — beyond that, the response is capped and meta.per_page indicates the limit actually applied.
offsetintegernoPaging offset. Only pagination available on PostgREST, the nominal engine of a Postgres project.
cursorstringnoaura-db only (MongoDB, or Postgres with PostgREST disabled) — not available on PostgREST, which responds 400 by naming offset. Pagination keyset: return the opaque meta.next_cursor of the previous page as is. Stable, without dup/skip (int/uuid/text). Aligns with sort_by.
countenumnoexact, planned, or estimated. No counting is done by default. This is the portable form: on the aura-db path, only this query parameter is read — a Prefer: count=exact header there would be ignored (it is only honored by PostgREST).
<column>.<op>filternoFilters: value.gt.24, status.eq.active, name.like.%alice%, tags.cs.{urgent}.

To know#

Tip

Relationship embed (FK) via select: author:authors(name) (LEFT JOIN — rows without relationships return null). Inner-join filtering is supported with !inner: e.g. author:authors!inner(name)&author.country=eq.FR.

Attention

The Range header is not a universal alternative paging: the aura-db path (MongoDB project, or Postgres with PostgREST disabled) only reads the query parameters and ignores it. It only has effect if the request reaches PostgREST. Use limit/offset.

Attention

The answer is wrapped : { data, meta }, never a bare array. On the PostgREST path, meta only contains total (and only if a count has been requested); on the aura-db path it also carries per_page and next_cursor.

Info

numeric/decimal columns are serialized as JSON number by default in PostgREST and typed as number by @aurabase/gen. When exact arbitrary precision (> 15 significant digits) is required, cast the expression (amount::text in SQL / view) or pass --numeric-as-string (numericAsString: true) to @aurabase/gen.