Read records

pawabase.from("table") starts a query. Add filters and options, then await it. Every read is made as the signed-in person, so your list and get access rules decide what comes back.

A list

const page = await pawabase.from("tasks");
page.data;       // the records
page.total;      // how many match, or null
page.page;       // 1
page.per_page;   // 20

page = pb.from_("tasks").execute()
page.data
page.total
page.page, page.per_page
for task in page: ...        # a Page is iterable
len(page)

A query returns one page, 20 records by default. See Sort and page to change that or walk through everything. total is how many records match for this caller. It is null when a per-row access rule means the server cannot count rows you may see without checking each one. Don’t build “page 3 of N” from total unless you know it is a number; use “Load more” and stop when a page comes back short.

One record by id

const task = await pawabase.from("tasks").get("01J…");          // throws NotFoundError if missing
const maybe = await pawabase.from("tasks").maybeGet("01J…");    // null if missing
const withAuthor = await pawabase.from("posts").get(id, { expand: ["author"] });

task = pb.from_("tasks").get("01J…")                  # raises NotFoundError if missing
maybe = pb.from_("tasks").maybe_get("01J…")            # None if missing
with_author = pb.from_("posts").get(post_id, expand=["author"])

A record that exists but that your rule hides is also “not found”. The two are the same on purpose, so a refusal never reveals what exists.

The first match, or exactly one

const latest = await pawabase.from("tasks").order("created_at", "desc").first();    // row or null
const mine = await pawabase.from("profiles").eq("user_id", user.id).single();        // row, or throws

latest = pb.from_("tasks").order("created_at", "desc").first()
mine = pb.from_("profiles").eq("user_id", user["id"]).single()

first() gives the first row or null. single() expects exactly one and throws if there are none or several.

Count and exists

const open = await pawabase.from("tasks").eq("done", false).count();
const any = await pawabase.from("tasks").eq("done", false).exists();

open_count = pb.from_("tasks").eq("done", False).count()
any_open = pb.from_("tasks").eq("done", False).exists()

count() respects your rules, so it counts what you may see. For a number a person shouldn’t be able to derive (total orders across customers), compute it on a server.

Only some fields

Download less by naming the fields you need:

const { data } = await pawabase.from("posts").select("id", "title");

data = pb.from_("posts").select("id", "title").execute().data

Fields you don’t select come back absent (typed as optional in TypeScript).

Everything that matches

all() follows the pages for you. Use it for results you know are bounded.

const tags = await pawabase.from("tags").all();
const some = await pawabase.from("orders").eq("status", "paid").all({ pageSize: 100, maxRecords: 5000 });

tags = pb.from_("tags").all()
some = pb.from_("orders").eq("status", "paid").all(page_size=100, max_records=5000)

See Sort and page for streaming page by page.

Plain-object style

If you prefer one call with options over chaining:

const page = await pawabase.from("tasks").list({
  where: { done: false, priority: { gte: 3 } },
  sort: "-created_at",           // a leading - means descending; separate several with commas
  select: ["id", "title"],
  expand: ["owner"],
  page: 1,
  perPage: 50,
});

page = pb.from_("tasks").list(where={"done": False, "priority": {"gte": 3}}, sort="-created_at", select=["id", "title"], expand=["owner"], per_page=50)

Cancel and time out

Every read accepts a signal and a timeout (TypeScript):

const controller = new AbortController();
const promise = pawabase.from("orders").withOptions({ signal: controller.signal, timeoutMs: 10_000 });
cancel.onclick = () => controller.abort();

An aborted read rejects with AbortError. In React, abort in the effect’s cleanup so a component that unmounts doesn’t set state afterwards.

Reading inside a framework

function useTasks(done: boolean) {
  const [tasks, setTasks] = useState<Task[]>([]);
  const [error, setError] = useState<unknown>(null);

  useEffect(() => {
    const controller = new AbortController();
    pawabase.from("tasks").eq("done", done).withOptions({ signal: controller.signal })
      .then((page) => setTasks(page.data as Task[]))
      .catch((e) => { if (!(e instanceof AbortError)) setError(e); });
    return () => controller.abort();
  }, [done]);

  return { tasks, error };
}

What can go wrong

Error	Meaning
`AuthenticationError`	The rule needs a signed-in user
`PermissionError` / `ForbiddenError`	Signed in, but the rule refused
`NotFoundError`	No such record (or hidden), on `get` / `single`
`InvalidQueryError`	You built a query the client can’t send (such as `eq("x", null)`; use `is`)
`ValidationError`	The server refused a filter value (a bad date)

Filter

Narrow what you read.

Sort and page

Order and paginate.

Getting started

Define your data

Change safely

Read and write

Protect and shape

Studio tools

Build well

A list

One record by id

The first match, or exactly one

Count and exists

Only some fields

Everything that matches

Plain-object style

Cancel and time out

Reading inside a framework

What can go wrong

Filter

Sort and page

​A list

​One record by id

​The first match, or exactly one

​Count and exists

​Only some fields

​Everything that matches

​Plain-object style

​Cancel and time out

​Reading inside a framework

​What can go wrong

Filter

Sort and page

A list

One record by id

The first match, or exactly one

Count and exists

Only some fields

Everything that matches

Plain-object style

Cancel and time out

Reading inside a framework

What can go wrong