Grid82
grid82.comJoin the waitlist
DevelopersFiltering and SQL

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_...):

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

ParameterTypeBehaviour
searchstringSubstring search across text columns you can read
filterJSON tree{ id, kind: "group", mode: "and" | "or", children: [...] } matching a saved view
sortsJSON arrayUp to 3 { "fieldId": "fld_...", "direction": "asc" | "desc" } levels
wherestringSQL-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). 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.

Use these docs with your AI tools

An AI agent can read this documentation directly. You do not need an account or an API key. Everything here is public and read-only.

Query these docs via MCP

Recommended

Add this server to Claude, Claude Code, Cursor, Mistral, or any tool that supports MCP. Your agent can then search Grid82 documentation and read it in full, instead of answering from memory.

https://grid82.com/docs/mcp
  • searchFind the passages that answer a question.
  • fetchRead one page in full, as Markdown.
  • list_pagesSee every page in this documentation.

Query these docs over HTTP

The same tools also work as plain web requests. Use this for scripts, or for any tool that does not support MCP. There is one endpoint per tool. Arguments go in the query string, and the answer comes back as JSON.

https://grid82.com/docs/api/docs/search?query=custom+domain

Read the OpenAPI description. It is built from the same definitions as the tools, so it always matches what the endpoints do.

Read these docs as Markdown

Add .md to any page URL to get its Markdown source. You can also send the headerAccept: text/markdown to the page URL itself.

To read the whole documentation in one file, open llms-full.txt. For a short index of every page, open llms.txt.