Skip to main content

Query records

A Database query starts with a table and composes only the operations the application needs: filters, ordering, field selection, and pagination. TaruviBase returns the current page together with the complete matching count.

The examples use tasks from the quickstart.

For Refine, register the provider and sign in, import useList from @refinedev/core, and place the hooks inside a component beneath <Refine>.

Filter, sort, and paginate#

Return the first 20 tasks whose title contains release, in title order with id as the final tie-breaker.

await database
  .from('tasks')
  .filters('title', 'contains', 'release')
  .sort('title', 'asc')
  .sort('id', 'asc')
  .page(1)
  .pageSize(20)
  .execute();

Pages are one-indexed. Stable ordering makes an unchanged result set deterministic. Separate page requests do not share a database snapshot, so concurrent inserts, updates, or deletes can move records between pages.

Select response fields#

Project only the fields used by the application when the interface supports server-side field selection.

await database
  .from('tasks')
  .fields('id,title,done')
  .sort('title', 'asc')
  .sort('id', 'asc')
  .page(1)
  .pageSize(20)
  .execute();

Match every condition#

Flat filters use AND logic. This query finds incomplete tasks whose title contains release.

await database
  .from('tasks')
  .filters('done', 'eq', false)
  .filters('title', 'contains', 'release')
  .sort('title', 'asc')
  .sort('id', 'asc')
  .page(1)
  .pageSize(20)
  .execute();

For nested logical groups, negation, set membership, text operators, null checks, arrays, and PostgreSQL range fields, use the filter operator reference.

Count matching records#

The SDK count methods and REST total represent all matching records, not only the current page. Refine exposes the same value as result.total.

await database
  .from('tasks')
  .filters('done', 'eq', false)
  .pageSize(1)
  .count();

Request per-record action hints#

A list query can ask TaruviBase which row-level actions are available for each record. The response adds _allowed_actions to every row and includes a subset of update and delete.

await database
  .from('tasks')
  .allowedActions(['update', 'delete'])
  .sort('id', 'asc')
  .page(1)
  .pageSize(20)
  .execute();

Use these values to choose which controls to display. They are hints for the current response, not reusable permission grants; TaruviBase evaluates the actual authorization policy again when a mutation is submitted. Action hints cannot be combined with an aggregation query.

Plan indexes from real queries#

Stable sorting is required for predictable pagination whether or not the sorted columns are indexed. When an important query becomes slow, capture its filters, ordering, representative parameters, row count, and latency, then use Plan indexes to prepare and verify the index change.

Validate query controls#

Build queries from the supported operators and stay within the Database limits before sending them. Validate filter and sort input in your application instead of relying on API errors to catch bad input.

Query checklist#

  • Set page and page_size for every collection read.
  • Use a stable order before moving through multiple pages.
  • Before an export or bulk delete, pause writes or save the full list of record IDs first, so records don't shift between pages.
  • Select only the fields the application needs where projection is supported.
  • Read total separately from the number of records on the current page.
  • Use a logical tree when AND and OR precedence matters.
  • Treat _allowed_actions as display guidance and let every write authorize independently.

Next steps#