Filtering, views, and SQL
Query records using saved views, structured filter trees, search, and Grid82's permission-compiled SQL read/write dialect.
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_...):
GET /v1/tables/tbl_8fj3kq2wmv5d/records?viewId=viw_e4ks9mz2bh7wViews 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 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). SupportsSELECT(up to1,000result rows per call) with aggregations (COUNT,SUM,AVG,MIN,MAX),GROUP BY,CASE,ORDER BY, andLIMIT. - Bulk mutations (
POST /v1/sql/execute). SupportsUPDATE ... WHEREandDELETE ... WHEREover up to500records in one atomic changeset. RequiresWHEREunlessconfirm: trueis passed, and supportsdryRun: trueto preview matched record counts and sample IDs first. - Builder plane. Builders run the same endpoints against any app at
/v1/apps/{appId}/sql/queryand/v1/apps/{appId}/sql/execute.
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"). NoJOIN,UNION, subqueries,WITH, orINSERT(userecords.createfor 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, andREPLACE. - Link predicates. Use
HAS ANY ('rec_...'),HAS ALL ('rec_...'), andIS EMPTYon relation columns. Setting alinkcolumn must userecords.updatewith an array of record IDs rather than SQLUPDATE. - Hidden columns. Referencing a restricted column fails as
"Unknown column". A column readable on only some records evaluates asNULLon the remaining records inside aggregates and expressions.