> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gavai.io/llms.txt
> Use this file to discover all available pages before exploring further.
# runQuery
> Read rows from the workspace's Postgres database via a typed filter DSL.
export const ExpectedOutput = ({caption = "Expected output", children}) => ;
export const ErrorTable = ({errors}) =>
Error
Cause
Fix
{errors.map((err, i) =>
{err.code}
{err.cause}
{err.fix}
)}
;
export const Def = ({term, type, defaultValue, required, children}) => <>
{term}
{type && {type}}
{required && required}
{defaultValue !== undefined &&
default {defaultValue}
}
{children}
;
export const DefList = ({children}) => {children}
;
export const ArrowItem = ({children}) =>
{"↳︎"}
{children}
;
export const ArrowList = ({children}) => ;
export const Eyebrow = ({label, tone = "default"}) =>
{label}
;
`runQuery` fetches rows from the workspace's managed Postgres database using a typed filter DSL. It is the in-page data-fetching primitive: blocks like `Table` and `KanbanBoard` use it to populate themselves from live data. You declare the filter in the page document and the runtime translates it to a parameterized Postgres query server-side — raw SQL is never accepted and never exposed. By the end of this page you can wire a Table block to a schema table with filters, sort order, and cursor pagination.
## Invoke from a Table block
The canonical pattern is binding `Table` to a `schema_table`. The block calls `runQuery` automatically and surfaces sort, filter, and pagination through its UI.
```json leads-table.json theme={null}
{
"block": "Table",
"props": {
"schema_table": "leads",
"sort": [{ "field": "created_at", "dir": "desc" }],
"limit": 50,
"filter": {
"status": { "eq": "active" }
}
}
}
```
A `KanbanBoard` uses `runQuery` the same way, grouping rows by a status field:
```json deals-kanban.json theme={null}
{
"block": "KanbanBoard",
"props": {
"schema_table": "deals",
"status_field": "stage",
"sort": [{ "field": "updated_at", "dir": "desc" }]
}
}
```
The runtime resolves the filter against the table's column types, parameterizes the query, executes against Postgres, and returns the rows in a validated envelope.
You do not write SQL. The `filter` argument is a typed DSL validated against the page's declared schema. The runtime translates it to a parameterized Postgres query server-side — raw SQL is not accepted as input.
`runQuery` runs in the security context of the calling page. The user's session — read via [`authUser`](/capabilities/auth-user) — gates which rows return. If the calling user does not have access to a row, that row is excluded. Multi-tenant isolation is enforced at this layer; changing the `table` name does not grant access to another workspace's data.
For server-side scripts and integrations, prefer the public REST API (see the [API reference](/api-reference/introduction)). `runQuery` is designed for in-page data fetching where the user's session should govern row-level access. Using it from a background job would require a user session, which is the wrong tool for the job.
## Inputs
Table name as declared in the page's schema. Must exist in the workspace schema.
Typed DSL filter expression. Validated server-side against the table's column types. Not raw SQL.
Ordered list of sort fields and directions, applied before pagination.
Maximum rows to return. Hard-capped at `1000`.
Pagination cursor from a previous response's `next_cursor`. Omit for the first page.
## Outputs
The returned rows, typed against the table's declared schema columns.
Pass as `cursor` on the next call to fetch the following page. Absent when there are no more rows.
Total row count matching the filter, when requested. Not always present — check for the field before reading.
## Provisioning
The workspace's managed Postgres database is auto-provisioned. Tables must be declared in the page document's `schema` section before they can be queried. Schemas are managed in the Builder's schema editor or via the pages API.
## Error codes
Every error returns the standard envelope:
```json error-envelope.json theme={null}
{
"ok": false,
"error": {
"code": "unknown_table",
"message": "Table 'leadz' is not declared in the workspace schema.",
"details": { "table": "leadz" }
}
}
```
## Related
The session whose roles gate row-level access on every `runQuery` call.
End-to-end: declare a schema, wire a Table, paginate with `next_cursor`.