filter

func BuildPredicate ¶ added in v0.20.0

func BuildPredicate(p *Predicate) Condition

BuildPredicate compiles a validated predicate tree into one WHERE Condition: a fully-parenthesized SQL string with sequential $N placeholders in depth-first order and a matching, same-order Args slice. Field names are interpolated (they came from the schema allow-list in ParseWhere); every value is a bound arg. Hand the result to qb.Where(c.SQL, c.Args...) ONCE, the builder wraps it in its own parens and AND-joins it to the framework scopes, so the user's boolean logic can never escape to widen a scope.

The $N numbers are positional only; core/query.renumberPlaceholders rewrites them left-to-right and advances by len(Args), so the sole invariant is that placeholders appear in the same order as Args, which building both in one DFS pass guarantees.

func SearchConditions ¶ added in v0.18.0

func SearchConditions(fields []string, term string) ([]Condition, error)

SearchConditions builds a slice of AND-composed search conditions from a free-text term over the given DB column names. Each whitespace- delimited token produces one Condition whose SQL is a parenthesized OR-group: (LOWER(f1) LIKE $1 ESCAPE '\' OR LOWER(f2) LIKE $2 ESCAPE '\'). Every Condition must match (AND); within one Condition, any field may match (OR). A blank/whitespace-only term returns nil (no conditions). A term that is not storable text (invalid UTF-8 or a NUL byte) returns an error naming "q": Postgres refuses it in a text bind.

Case contract: LOWER() is ASCII-only on SQLite and locale-aware on Postgres, so matching is ASCII-case-insensitive everywhere. Unicode case folding is a Postgres bonus. The token itself is lowercased before building the LIKE pattern so the comparison is consistent across dialects.

LIKE metacharacters (%, _, \) in each token are escaped via the existing escaper so they match literally, a user searching for "50%" finds rows containing "50%", not every row with any character sequence. The args are ordered to match the $N placeholders left-to-right; the crud query builder renumbers $N on Build.

func ReadKey ¶ added in v0.96.0

func ReadKey(key string, named func(string) bool) (name string, op FilterOp, ok bool, err error)

ReadKey reads one filter key against the names a target answers to. named reports whether a name is one a caller may put in a filter key: the column or wire name of a field that is not Hidden. NoQuery fields count (they are refused by name afterwards); Hidden ones never do, so a Hidden field and an absent one read alike.

The bracket form name[op] names its field with the whole text before the brackets and its operator by word (BracketOps). A word outside that list is a refusal, but only once name is named: an unnamed name reads as an unknown field first, the answer an absent one gets.

A bare key is equality on itself when it is a name, or op on the name before its operator suffix when that is a name. When both hold (fields check and check_in, key check_in) the key reads two ways and is refused, naming both readings and the bracket spellings that pick one: guessing either answered the other reading's rows with a 200.

ok is false when no reading names a field. name and op are then the reading the caller most likely meant, for the unknown-field refusal: the bracket name, else the cut at the key's suffix, else the key.

func Allow ¶ added in v0.35.0

func Allow(keys ...string) FilterOption

Allow declares extra query-param keys that are NOT entity fields but are legitimately consumed elsewhere on the request (a BeforeList hook, custom middleware). Strict parsing skips them instead of rejecting them, so a host keeps typo-protection for real fields without falling back to Lenient (which disables it entirely). Keys are matched exactly.

func Lenient ¶ added in v0.35.0

func Lenient() FilterOption

Lenient restores the pre-strict behavior: an unknown top-level filter key is silently dropped instead of returning an error. It exists as a migration escape hatch for apps that historically relied on unrecognized query params being ignored. Prefer the strict default, a dropped filter returns an UNFILTERED result set, which is a data-exposure and broken-client hazard.

func NewKeySpeller ¶ added in v0.96.0

func NewKeySpeller(names ...string) KeySpeller

NewKeySpeller builds a KeySpeller over names. Empty names are ignored.

func SpellerFor ¶ added in v0.96.0

func SpellerFor(fields []schema.Field) KeySpeller

SpellerFor is the KeySpeller over the names ParseFiltersValues reads for fields: each non-Hidden field's column name and WireName, NoQuery fields included (a NoQuery name still makes a bare key read two ways).

func ParseFilters ¶

func ParseFilters(r *http.Request, fields []schema.Field, opts ...FilterOption) ([]ParsedFilter, error)

ParseFilters extracts filters from query parameters based on entity fields. Supported patterns:

?field=value        → equals
?field_ne=value     → not equals
?field_gt=value     → greater than
?field_lt=value     → less than
?field_gte=value    → greater than or equal
?field_lte=value    → less than or equal
?field_like=value   → LIKE (contains)
?field_in=v1,v2,v3  → IN
?field[op]=value    → the same operators by word (eq, ne, gt, gte,
                      lt, lte, like, in); the name before the
                      brackets is always the whole field name

A bare key cuts at its suffix only when the name before the suffix is a field, so a lone opt_in field filters as ?opt_in=. When the key is a field AND another field plus a suffix (check beside check_in, key check_in) it reads two ways and is a 400 naming both readings and the bracket spellings that pick one (?check_in[eq]=, ?check[in]=), Lenient included. An unknown bracket word is a 400 too; a bracket on an unknown or Hidden field is the unknown-filter 400.

`?field_ne=` follows OpEq's NULL semantics rather than SQL three-valued intuition: a row whose column is NULL matches neither `=` nor `!=`, no `OR field IS NULL` arm is added.

Only fields present in the schema are accepted. Hidden fields are excluded from the allow-list (mirroring ParseSort): building a WHERE predicate on a column the caller can't read turns row-count/result changes into a value-disclosure oracle, an attacker could probe a Hidden column (e.g. a password hash) via ?password_hash_like=… and exfiltrate it prefix by prefix. A Hidden field name is treated as an unknown filter param and never produces a ParsedFilter.

NoQuery fields are excluded too, and for the same oracle reason, a value masked on the way out (last-4, redacted by an AfterGet hook) is still recoverable a character at a time if the stored column remains filterable. They are rejected by name rather than as unknown: the field is in the response, so its existence is not a secret worth protecting.

STRICT by default: an unknown top-level filter key (a typo like ?stauts=active, or a suffixed op on a non-field) returns a structured error rather than being silently dropped. Dropping it would return an UNFILTERED 200, a broken client reads the whole table and an attacker's probe looks identical to the real query. Reserved list controls (sort, page, cursor, …) and nested relation filters (dotted keys like author.name, validated separately by parseNestedFilters) are skipped, not rejected. Pass Lenient to restore the old drop-silently behavior.

This is a thin wrapper around ParseFiltersValues that parses the request URL once. Callers that already have a url.Values (e.g. the CRUD List handler, which parses once and threads the result through every helper) should call ParseFiltersValues directly to avoid the re-parse.

func ParseFiltersValues ¶ added in v0.36.0

func ParseFiltersValues(q url.Values, fields []schema.Field, opts ...FilterOption) ([]ParsedFilter, error)

ParseFiltersValues is the allocation-conscious variant of ParseFilters: it accepts an already-parsed url.Values so a caller that parsed ?field=value once can reuse it across filter/sort/paginate/include helpers without re-paying url.URL.Query (which re-parses RawQuery and allocates a fresh url.Values on every call). Behaviour is identical to ParseFilters for the same underlying query string.

func ParseSort ¶

func ParseSort(r *http.Request, fields []schema.Field) ([]ParsedSort, error)

ParseSort extracts sort information from query parameters. Supported: ?sort=field (ascending), ?sort=-field (descending).

Hidden fields are excluded from the allow-list: sorting by a hidden column reveals row ordering by a value the caller can't read, which is an information-disclosure path. NoQuery fields are excluded for the same reason, but rejected by name, they appear in responses, so the caller already knows the column exists. Unknown fields fail closed with a 400-shaped error rather than being silently ignored, silent drop turns probe attempts into "the API works the same with or without this param" oracles that mask broken client code.

Thin wrapper around ParseSortValues; callers that already hold a url.Values should call ParseSortValues directly.

func ParseSortValues ¶ added in v0.36.0

func ParseSortValues(q url.Values, fields []schema.Field) ([]ParsedSort, error)

ParseSortValues is the allocation-conscious variant of ParseSort: it accepts an already-parsed url.Values so the CRUD List handler can thread the same parsed query through every helper.

func ParseWhere ¶ added in v0.20.0

func ParseWhere(raw string, fields []schema.Field) (*Predicate, error)

ParseWhere parses a `?where=<json>` predicate tree and validates every leaf field against the schema allow-list (Hidden fields excluded, same value-disclosure-oracle rationale as ParseFilters) and every operator against the supported set. Returns (nil, nil) when raw is empty. Any unknown field, unknown operator, malformed JSON, empty/ambiguous node, or a tree that exceeds the depth/node bounds returns an error, the caller maps it to 400. On success the tree is safe for BuildPredicate to compile.

func ValidatePredicate ¶ added in v0.87.0

func ValidatePredicate(p *Predicate, fields []schema.Field) (*Predicate, error)

ValidatePredicate runs over a predicate tree built in Go code — a view func's return value, a ListOptions.Where, anything that did not arrive through ParseWhere — the SAME checks ParseWhere applies to input from a URL: every leaf field exists on the schema and is neither Hidden nor NoQuery (Hidden under either its column name or its wire alias), the operator is known and suits the field's type, an OpIn leaf carries 1… MaxINListEntries values, and the tree stays inside the depth and node caps.

It never writes to the input: the caller's tree may be shared across goroutines (a parsed Display view handed to concurrent requests), so the two resolutions a validated tree carries — a wire alias resolved to its column name, a Bool leaf's coercion marker — are written on a deep copy that is returned, and that copy is the tree to hand BuildPredicate. The input stays byte-for-byte what the caller built.

Field names in a predicate are spliced into SQL by BuildPredicate (values are bound as placeholders, names are not), so this check is what keeps a Go-built tree safe to compile: a field that is not on the schema's allow-list — an invented name, a Hidden column, SQL metacharacters in a key — is refused before any SQL exists. A node that is neither a well-formed leaf nor a non-empty group is refused too.

nil is valid (the empty predicate) and returns (nil, nil).