Backend

Filter expressions

Every generated list endpoint accepts ?filter=, an expression over the model's own fields, plus ?fields= to ask for less, ?expand= to ask for more and ?skip_total=1 to skip the count. Between them they are the difference between adding a query parameter for each new question and answering questions nobody asked you about in advance.

GET /api/v1/machines?filter=status = "active" && hours > 100
GET /api/v1/orders?filter=total >= 500 && created_at >= @monthStart
GET /api/v1/posts?filter=author.country = "UG" || tags.label ?= "urgent"
GET /api/v1/invoices?filter=paid_at = null && due_at < @now

What makes it safe

Not the parser. Every identifier is resolved against the model's GORM schema, which is the only description of the table anybody maintains, and a name the model does not declare is refused with the list of names it does. Every value is a bound parameter, so a filter containing a quotation mark is a string containing a quotation mark.

$ curl -G /api/v1/machines --data-urlencode 'filter=nonsense = 1'
{"error":{"code":"VALIDATION_ERROR","message":"unknown field \"nonsense\" at position 0
(this endpoint accepts: created_at, hours, id, name, serial, status)"}}
$ curl -G /api/v1/machines --data-urlencode 'filter=name = "x" OR 1=1'
{"error":{"code":"VALIDATION_ERROR","message":"unexpected identifier \"OR\" at position 11"}}

A refused filter is 422, not 500: it is the caller's sentence that is wrong, and the message says where and what the alternatives are.

Operators

OperatorMeaning
= !=Equal, not equal. != includes rows where the column is null, because that is what the sentence says and not what SQL does.
> >= < <=Comparison, on numbers and dates.
~ !~Contains, case-insensitively. A value with no % in it is wrapped in them, so title ~ "lor" is a contains and title ~ "Lor%" is a starts-with.
?= ?~ ?> …The any-of forms. On a field that can hold many values, a plain operator means every one of them matches and the ? form means at least one does.
&& || ( )And, or, grouping. // starts a comment.
Match-all is the default over a relationcomments.approved = true asks whether every comment is approved.comments.approved ?= true asks whether any is. The first is true for a row with no comments at all, which is the same answer SQL gives and the one most people want when they write it.

Relations

A dotted name walks a relation, as deep as six hops. Each one becomes a correlated subquery, so a filter over a has-many does not multiply the rows the way a join would.

author.name = "Ada" # belongs-to
author = "u_1" # the same thing: a relation named alone means its key
comments.approved ?= true # has-many, any
comments.approved = true # has-many, all
tags.label ?= "urgent" # many-to-many, through the join table
settings.theme = "dark" # a path into a JSON column

The request

@request is what the server knows about the caller. It resolves in Go and arrives in the query as a bound value, so none of it is ever syntax.

@request.auth.id the signed-in user's id, "" for a guest
@request.auth.role and anything else on the record
@request.query.x a query parameter
@request.headers.x_id a header; X-Id is written x_id
@request.method the HTTP method
@request.context where this is being evaluated: default, realtime, protectedFile
# "mine", which is the filter nearly every application writes first
GET /api/v1/orders?filter=user_id = @request.auth.id

Dates

The macros resolve in Go, in UTC, at the moment the request is compiled, so a rule means the same thing on every database.

@now @yesterday @tomorrow
@todayStart @todayEnd
@weekStart @weekEnd
@monthStart @monthEnd
@yearStart @yearEnd
@second @minute @hour @weekday @day @month @year # the parts, as numbers

Modifiers

ModifierWhat it does
:lengthCounts the items of a list column: tags:length > 2.
:eachApplies the condition to every item of a list column: labels:each ?= "go".
:lowerCase-insensitive comparison: status:lower = "ACTIVE".
:issetOn @request.* only: did the caller send this field at all. A different question from whether its value is empty.
:changedOn @request.body.* only: was it sent and is it different from what is stored.

Functions

geoDistance(lon_a, lat_a, lon_b, lat_b) < 25 # kilometres, haversine
strftime("%Y-%m", created_at) = "2026-01"
lower(name) = "ada"

Which fields an endpoint accepts

The union of what it already admits it can be searched, sorted and filtered on: Searchable, Sortable, Filterable, RangeFilterable and InFilterable on its paginate.Config. An endpoint willing to sort by a column has already decided that column is public, so a generated resource gets expression filtering with nothing further to remember.

var machineListConfig = paginate.Config{
Searchable: []string{"name", "serial"},
Sortable: map[string]bool{"created_at": true, "hours": true},
Filterable: map[string]bool{"status": true, "hours": true},
// Or say so explicitly, which is what you want on anything served
// without authentication: there the question is not "can this be
// ordered by" but "may a stranger ask about it".
FilterFields: []string{"status", "hours"},
}

Columns that look like credentials are never filterable, whatever the model calls them: password, token, secret, api_key and the rest. password ~ "$2a$10$ab" reads a hash one character at a time, and a whitelist that forgot to exclude it would not stop that.

That list is a guess about names, though, and it is only a backstop. A column called recovery_phrase is on nobody's list, and the filter reads it a character at a time just as happily. Declare it on the model instead:

grit generate resource Wallet label:string phrase:text:sensitive

A sensitive column is written and never read back. The expression engine refuses the name in a filter, a sort and a row rule; the model's MarshalJSON drops the key, so no response carries it; and it is not an admin column, not in the export and not searchable. grit doctor points out columns that look like secrets and have not said so.

Asking for less: ?fields=

A list screen showing four columns does not need forty, and a phone on a slow connection pays for every one it throws away.

GET /api/v1/orders?fields=id,total,customer.name
{ "data": [ { "id": "o1", "total": 500, "customer": { "name": "Ada" } } ] }

The projection is applied to the marshalled document, not to the SELECT. A partial select leaves the struct's other fields at their zero values and they serialise anyway: the client asks for two columns and receives forty, thirty-eight of them untrue. A field that was not asked for is absent, which is the only honest way to send less.

Dotted paths walk into an expanded relation, and two paths into the same object merge, so customer.name,customer.email gives one customer with both. Nothing is checked against the model: a path the response does not have is simply missing from the projection, which is what the client would see if it asked for everything and read the key itself.

Asking for more: ?expand=

Without it, a list of orders carries customer_id and the client makes one request per row to turn it into a name. That is the N+1 problem moved onto the network, where it is slower and nobody can see it in a profiler.

GET /api/v1/orders?expand=customer,lines.product

Each name is resolved against the model's own schema and translated into the association GORM knows, so the client writes line_items.product the way the JSON spells it and Preload receives LineItems.Product. A relation the model does not declare is a 422 naming the ones it does, rather than an error from inside the ORM with the caller's string in it.

var orderListConfig = paginate.Config{
// Empty means every relation the model declares, which is right for an
// authenticated endpoint: those rows are already reachable at their own
// URLs. Set it on a public one, where expanding a relation is how a row
// nobody may read arrives inside one they may.
Expandable: map[string]bool{"customer": true},
}

At most six relations per request and three levels deep. Each one is another query, and a client that can ask for forty can make one request cost forty.

Skipping the count

?skip_total=1 drops the COUNT from an offset page. The page itself is a LIMIT over an index; the total is a scan of everything that matched, and on a large filtered table it is most of the request. A client rendering "next" and "previous" never reads it.

{
"data": [ ... ],
"meta": { "total": 0, "page": 1, "page_size": 20, "pages": 0, "has_more": true }
}

total and pages come back zero, and has_more answers the only question a next button needs.

Limits

3500 characters the longest expression parsed
200 comparisons the most one expression may contain
6 relations the deepest path

A filter arrives in a query string from anybody at all, and parsing is work. The limits are generous for a written query and far below what it takes to make the parser expensive.

Where the engine lives

internal/rules in your project: a tokeniser, a parser and a compiler, around nine hundred lines with its tests. It is yours, it is readable, and it is the same engine that evaluates a declared access rule.