Lightweight, type-safe filter builder for Go.
- Parse filters from Go structs via reflection (
FromStruct) - Parse filters from
url.Values/ HTTP query string (FromURL) - Whitelist allowed fields with
WithAllowedFields - Multi-field sorting with
sort=name,-created_at - Whitelist sortable fields with
WithAllowedSorts - Configurable pagination limits with
WithDefaultLimitandWithMaxLimit - Deterministic pagination validation with
ErrInvalidLimitandErrInvalidOffset - Pagination metadata helper with
filter.Pagination(),Page(),NextOffset(),PreviousOffset() - Custom struct tag name with
WithTagName - 12 operators:
=,!=,>,>=,<,<=,LIKE,ILIKE,IN,BETWEEN,IS NULL,IS NOT NULL - Zero dependencies for the core module
- Optional adapters: GORM and plain SQL (PostgreSQL-style
$Nplaceholders)
Go 1.22 or higher.
go get github.com/noormaulida/gofilt@latestThis single command installs the core package plus the GORM adapter and SQL adapter together. No separate installs required.
package main
import "github.com/noormaulida/gofilt"
type UserQuery struct {
Name string `filt:"col:name;op:ilike"`
Age int `filt:"col:age;op:gte"`
Status string `filt:"col:status"`
}
func main() {
req := UserQuery{Name: "Noor", Age: 20, Status: "active"}
filter, _ := gofilt.FromStruct(req,
gofilt.WithAllowedFields("name", "age", "status"),
)
// filter.Conditions = [
// {Field: "name", Operator: "ILIKE", Value: "Noor"},
// {Field: "age", Operator: ">=", Value: 20},
// {Field: "status", Operator: "=", Value: "active"},
// ]
}package main
import (
"errors"
"net/http"
"github.com/noormaulida/gofilt"
)
func handler(w http.ResponseWriter, r *http.Request) {
filter, err := gofilt.FromURL(r.URL.Query(),
gofilt.WithAllowedFields("name", "age", "status"),
gofilt.WithAllowedSorts("name", "created_at"),
gofilt.WithDefaultLimit(20),
gofilt.WithMaxLimit(100),
)
if errors.Is(err, gofilt.ErrInvalidLimit) {
http.Error(w, "invalid limit parameter", http.StatusBadRequest)
return
}
if errors.Is(err, gofilt.ErrInvalidOffset) {
http.Error(w, "invalid offset parameter", http.StatusBadRequest)
return
}
if err != nil {
http.Error(w, err.Error(), http.StatusBadRequest)
return
}
// Query string:
// ?name[ilike]=Noor&age[gte]=20&sort=name,-created_at&limit=10&offset=20
_ = filter.Limit // 10
_ = filter.Offset // 20
// filter.Sorts = [
// {Field: "name", Direction: "ASC"},
// {Field: "created_at", Direction: "DESC"},
// ]
}Sorting is disabled until WithAllowedSorts is configured. Unknown sort
fields are ignored, preventing query parameters from becoming arbitrary SQL
identifiers.
Supported URL syntax:
| Syntax | Operator |
|---|---|
name=Noor |
= (default) |
name[eq]=Noor |
= |
name[ne]=Noor |
!= |
age[gt]=20 |
> |
age[gte]=21 |
>= |
age[lt]=100 |
< |
age[lte]=99 |
<= |
name[like]=noo |
LIKE |
name[ilike]=noo |
ILIKE |
id[in]=1,2,3 |
IN (auto-split comma) |
status=active,pending |
IN (auto-detect comma) |
deleted_at[null]=true |
IS NULL (isnull, is_null, is are aliases; value is ignored) |
deleted_at[is]=null |
IS NULL |
deleted_at[notnull]=true |
IS NOT NULL (isnotnull, not_null, is_not_null are aliases) |
or.role=admin&or.role=moderator |
OR group, combined with other fields using AND |
or.0.role=admin&or.1.status=pending |
Separate indexed OR groups |
and.0.status=active&and.0.age[gte]=18 |
Indexed AND group |
q=noor or search=noor |
Free-text search, only after WithSearchFields |
fields=id,name,email |
Column projection, only after WithSelectFields |
sort=name |
Sort by name ascending |
sort=name,-created_at |
Sort by name ascending, then created_at descending |
limit=10 |
Pagination limit (defaults with WithDefaultLimit, capped by WithMaxLimit) |
offset=20 or page=20 |
Pagination offset |
Negative or non-integer values for limit, offset, or page return ErrInvalidLimit or ErrInvalidOffset deterministically.
Flat conditions are AND. or. and and. keys build Filter.Expr, a tree of Condition and Group values.
?status=active&age[gte]=18&or.role=admin&or.role=moderator
AND
├── status = active
├── age >= 18
└── OR
├── role = admin
└── role = moderator
Indexed keys keep separate groups: or.0.role=admin&or.0.role=moderator&or.1.status=pending. The same shape can be built in Go:
filter.Expr = gofilt.And(
gofilt.Condition{Field: "status", Operator: gofilt.OpEq, Value: "active"},
gofilt.Condition{Field: "age", Operator: gofilt.OpGte, Value: 18},
gofilt.Or(
gofilt.Condition{Field: "role", Operator: gofilt.OpEq, Value: "admin"},
gofilt.Condition{Field: "role", Operator: gofilt.OpEq, Value: "moderator"},
),
)When Expr is set, adapters render that tree and ignore Conditions. Nested groups are parenthesized. A root AND group is not wrapped.
q and search are normal columns until WithSearchFields lists the columns a list endpoint may search. The term is then matched with ILIKE on each of those columns, joined with OR, and combined with the rest of the filter using AND.
filter, err := gofilt.FromURL(r.URL.Query(),
gofilt.WithSearchFields("name", "email", "phone"),
)
// ?q=noor
// WHERE (name ILIKE '%noor%' OR email ILIKE '%noor%' OR phone ILIKE '%noor%')q wins when both q and search are set. Identifiers that are not plain column names are ignored.
fields is a normal column until WithSelectFields lists the columns a client may request. Unknown names are dropped. The SQL adapter turns the result into a SELECT list. An empty selection returns an empty string so the caller can keep SELECT *.
filter, err := gofilt.FromURL(r.URL.Query(),
gofilt.WithSelectFields("id", "name", "email"),
)
// ?fields=id,name,email
// filter.Fields = ["id", "name", "email"]
cols := gofiltsql.BuildSELECT(filter) // SELECT id, name, emailFilter.Fields is a flat column list. It does not describe GORM associations, preloads, joins, aliases, or computed expressions. The GORM adapter passes the same safe names to Select and leaves those other concerns to the caller.
Query values are strings until WithFieldTypes says otherwise. FieldTypesFrom reads column types from a query struct so the URL parser and the struct parser agree.
type UserQuery struct {
Age int `filt:"col:age;op:gte"`
Active bool `filt:"col:active"`
Since time.Time `filt:"col:created_at;op:gte"`
}
filter, err := gofilt.FromURL(r.URL.Query(),
gofilt.WithFieldTypes(gofilt.FieldTypesFrom(UserQuery{})),
)
// ?age[gte]=20&active=true&created_at[gte]=2026-01-02T15:04:05Z
// Values are int(20), bool(true), and time.Time — not strings.Supported types: string, int, int8, int16, int32, int64, uint, uint64, float32, float64, bool, and time.Time.
IN lists are converted element by element (id[in]=1,2,3 with an int field becomes []int). Accepted time layouts are RFC3339 (with optional fractional seconds), 2006-01-02 15:04:05, and 2006-01-02. A value that does not match its field type returns ErrInvalidValue. Fields without a registered type stay strings. IS NULL and IS NOT NULL values are not converted.
Filter provides a lightweight Pagination() helper to calculate page numbers and offsets:
pagination := filter.Pagination()
page := pagination.Page() // Current 1-based page number (e.g. 3)
next := pagination.NextOffset() // Offset for next page (e.g. 30)
prev := pagination.PreviousOffset() // Offset for previous page (e.g. 10, clamped to 0)Note:
Totalrecord count is intentionally excluded fromFilterandPagination. Calculating total records requires aCOUNT(*)database query, which is the responsibility of the repository or database layer.
import gofiltgorm "github.com/noormaulida/gofilt/adapter/gorm"
var users []User
db := gofiltgorm.Apply(tx, filter)
db.Find(&users)
// Adds ORDER BY name ASC, created_at DESC when filter.Sorts is populated.import gofiltsql "github.com/noormaulida/gofilt/adapter/sql"
cols := gofiltsql.BuildSELECT(filter)
where, args := gofiltsql.BuildWHERE(filter)
orderBy := gofiltsql.BuildORDER(filter)
if cols == "" {
cols = "SELECT *"
}
// cols = "SELECT id, name, email" when filter.Fields is set
// where = "WHERE name ILIKE $1 AND age >= $2"
// args = ["%Noor%", 20]
// orderBy = "ORDER BY name ASC, created_at DESC"
rows, _ := db.QueryContext(ctx,
cols+" FROM users "+where+" "+orderBy,
args...,
)| Option | Description |
|---|---|
WithTagName(name string) |
Override default struct tag ("filt") |
WithAllowUnknown(bool) |
Reserved for future URL-parser strict mode |
WithAllowedFields(...string) |
Whitelist-only mode — drop any field not in the list |
WithAllowedSorts(...string) |
Allow sorting only by listed fields; unknown fields are ignored |
WithDefaultLimit(limit int) |
Fallback limit when no limit is provided in input |
WithMaxLimit(max int) |
Cap the maximum allowed limit to guard against large queries |
WithFieldTypes(map[string]reflect.Type) |
Parse URL values into the listed Go types; omitted fields stay strings |
WithSearchFields(...string) |
Allow q / search to match these columns with ILIKE |
WithSelectFields(...string) |
Allow fields to project only these columns |
Tag format: col:<column>;op:<operator> — order does not matter. op is optional and defaults to =. Use - to ignore a field.
type Query struct {
A string `filt:"col:full_name;op:ilike"` // explicit
B string `filt:"col:status"` // op defaults to =
C string `filt:"-"` // skip
D string `custom:"col:x;op:ne"` // use WithTagName("custom")
}gofilt/
├── gofilt.go # Core types: Filter, Expression, Condition, Group, Operator
├── pagination.go # Pagination metadata helper: Page, NextOffset, PreviousOffset
├── operator.go # Operator lookup & aliases (public)
├── options.go # Option constructors + defaultOptions
├── parser_struct.go # FromStruct — reflect-based struct parser
├── parser_url.go # FromURL — url.Values parser
├── value.go # FieldTypesFrom and URL value conversion
├── adapter/
│ ├── gorm/ # Apply filters, sorting, and pagination to GORM
│ └── sql/ # Build SELECT, WHERE, and ORDER BY clauses
├── go.mod # Single module — one `go get` covers all packages
└── *_test.go # Unit tests
Note: Core and adapters are released together under the same version.
go test -v ./...