---
title: "Filtering, views, and SQL"
description: "Query records using saved views, structured filter trees, search, and Grid82's permission-compiled SQL read/write dialect."
canonical: "https://grid82.com/docs/developers/rest/filtering-and-sql"
updated: "2026-11-20"
---

# Filtering, views, and SQL

Every query mechanism in Grid82 combines cleanly with your compiled permissions: filters, views, and SQL statements can only narrow what your roles already permit.

## Saved views

Requesting a saved view applies that view's filters, sorts, and visible columns in one parameter (`?viewId=viw_...`):

```http
GET /v1/tables/tbl_8fj3kq2wmv5d/records?viewId=viw_e4ks9mz2bh7w
```

Views belong strictly to the user who created them (`views.list` returns only your personal views). Builders query tables in the Studio using raw filters or SQL.

## Query parameters on `records.list`

| Parameter | Type       | Behaviour                                                                           |
| --------- | ---------- | ----------------------------------------------------------------------------------- |
| `search`  | string     | Substring search across text columns you can read                                   |
| `filter`  | JSON tree  | `{ id, kind: "group", mode: "and" \| "or", children: [...] }` matching a saved view |
| `sorts`   | JSON array | Up to 3 `{ "fieldId": "fld_...", "direction": "asc" \| "desc" }` levels             |
| `where`   | string     | SQL-style predicate (for example `Stage = 'Won' AND Amount > 50000`)                |

You may reference fields in filters and sorts by permanent ID or exact current name. Attempting to filter or sort by a field that you can read only on a subset of records returns `403 forbidden`; check the `constrained` list returned by `GET /v1/app`.

Use [`filters.suggest`](/docs/app-api/filters/suggest) to translate a natural-language sentence into a structured filter tree you can review before executing.

## Permission-compiled SQL (`sql.query` and `sql.execute`)

Grid82 supports a safe SQL subset compiled through your permissions and bound parameters:

- **Read queries (`POST /v1/sql/query`).** Supports `SELECT` (up to `1,000` result rows per call) with aggregations (`COUNT`, `SUM`, `AVG`, `MIN`, `MAX`), `GROUP BY`, `CASE`, `ORDER BY`, and `LIMIT`.
- **Bulk mutations (`POST /v1/sql/execute`).** Supports `UPDATE ... WHERE` and `DELETE ... WHERE` over up to `500` records in one atomic changeset. Requires `WHERE` unless `confirm: true` is passed, and supports `dryRun: true` to preview matched record counts and sample IDs first.
- **Builder plane.** Builders run the same endpoints against any app at `/v1/apps/{appId}/sql/query` and `/v1/apps/{appId}/sql/execute`.

```sql
SELECT stage, COUNT(*) AS deals, SUM(amount) AS pipeline
FROM Deals
GROUP BY stage
ORDER BY pipeline DESC

UPDATE Deals
SET probability = 100
WHERE stage = 'Won'
```

### Supported SQL features and limits

- **Single table per query.** Reference the table by exact name, plural, or ID, and quote column names containing spaces with double quotes (`"Expected close"`). No `JOIN`, `UNION`, subqueries, `WITH`, or `INSERT` (use `records.create` for inserts).
- **Operators and functions.** `AND`, `OR`, `NOT`, `LIKE`, `IN (...)`, `IS [NOT] NULL`, `BETWEEN`, `CASE`, `LENGTH`, `LOWER`, `UPPER`, `TRIM`, `ABS`, `ROUND`, `COALESCE`, `SUBSTR`, `DATE`, `STRFTIME`, `IFNULL`, `INSTR`, and `REPLACE`.
- **Link predicates.** Use `HAS ANY ('rec_...')`, `HAS ALL ('rec_...')`, and `IS EMPTY` on relation columns. Setting a `link` column must use `records.update` with an array of record IDs rather than SQL `UPDATE`.
- **Hidden columns.** Referencing a restricted column fails as `"Unknown column"`. A column readable on only some records evaluates as `NULL` on the remaining records inside aggregates and expressions.
