One filter language.
Three surfaces.
Zero injection risk.

# the same filter, three ways

The same filter, three ways

Italian recipes with at least one four-star review, no soft-deleted rows, sorted by recency. One predicate. Three surfaces.

query {
  recipes(
    where: {
      cuisine: { name: { icontains: "italian" } }
      reviews: { some: { rating: { gte: 4 } } }
      deletedAt: { isNull: true }
    }
    orderBy: [createdAt_DESC]
    first: 20
  ) {
    edges { node { id title cuisine { name } } }
  }
}

GET /api/v1/recipes
  ?filter=cuisine.name icontains 'italian'
          AND reviews ANY (rating >= 4)
          AND deletedAt is null
  &sort=-createdAt
  &page[size]=20

{
  "name": "graphql_query",
  "arguments": {
    "query": "{ recipes(limit: 20,
      filterql: \"cuisine.name icontains 'italian'
        AND reviews ANY (rating >= 4)
        AND deletedAt is null\",
      orderBy: [createdAt_DESC])
      { edges { node { id title } } } }"
  }
}

# operators

What it can express

Grouped by what you actually reach for. Every operator below is real syntax — copy any line into a search box, a URL, or an MCP filter argument and it will parse and run.

• Comparisons

  • =
  • !=
  • <
  • <=
  • >
  • >=
  • between 2 and 8
  • not between 18 and 65
  • is distinct from :x

• Strings & patterns

  • like 'Pa%'
  • ilike '%pasta%'
  • icontains 'pasta'
  • starts_with 'quick-'
  • not_starts_with 'draft-'
  • regex '^[A-Z]'
  • iregex '^pasta'
  • fts '"quick dinner" -mushroom'

• Lists & ranges

  • status in ('draft', 'published')
  • status not in ('archived', 'spam')
  • servings in [2, 8)
  • servings in [2, 8]
  • servings in (2, 8]

• Arrays & JSONB

  • tags contains ('vegan', 'gluten-free')
  • tags overlap ('vegan', 'dairy-free')
  • tags contained_by ('a','b','c')
  • meta has_key 'tier'
  • meta has_keys_any ('tier','plan')
  • nutrition__calories > 400
  • nutrition__macros__proteinG >= 20
  • nutrition__ingredients ANY (organic = true)

• Relations

  • cuisine.name icontains 'italian'
  • author.team.name = 'Platform'
  • reviews ANY (rating >= 5)
  • reviews ALL (rating >= 3)
  • reviews NONE (flagged is true)

• Relative time

  • createdAt >= now-7d
  • createdAt >= now-1M
  • createdAt >= now/d
  • createdAt >= now/M
  • createdAt >= now-1M/M
  • expiresAt < now+30d

• One operator, many values

  • title icontains(any) ('react','vue','angular')
  • title icontains(all) ('pasta','fresh')
  • filename ends_with(any) ('.jpg','.png','.gif')
  • slug not_starts_with(all) ('draft-','arch-')

• Null, boolean, empty

  • deletedAt is null
  • cuisineId is not null
  • isShared is true
  • tags is empty
  • tags is not empty

• Aggregates → HAVING

  • count(*) >= 5
  • count(distinct assignee) > 1
  • avg(rating) >= 4
  • max(priceCents) < 10000

• Your own SQL as a predicate

  • recipes_rated_at_least(4)
  • NOT recipes_rated_at_least(4)
  • in_season()

• Named parameters

  • status = :status
  • tenantId = :tenantId
  • createdAt >= :since
  • role in :roles

# beyond

Beyond where most filter dialects stop

Every GraphQL engine ships a `where`. Most stop at eq / in / contains, on the row's own columns. filtr goes past that — without leaving its lane.

filtr is a predicate language — it filters rows, it does not transform values. There are no tolower()-style value transforms and no arithmetic in the WHERE clause, and they are not on the roadmap. What IS callable inside a filter: the aggregate functions (compiled to HAVING) and any SETOF Postgres function you tag with @gqlith.filterPredicate — so when you genuinely need SQL-level logic, you write it as SQL and the filter language calls it.

# in the wild

Real filters from real screens

Concrete predicates the kind of app you ship actually needs. None of these require a hand-written resolver.

• My recent published recipes in Italian cuisine, plus any unpublished drafts I authored.

  (authorId = :userId)
  AND ((status = 'published' AND cuisine.name icontains 'italian')
       OR status = 'draft')
  ORDER BY createdAt DESC

• Orders with at least one item over $50, paid in the last calendar month.

  items ANY (priceCents >= 5000)
  AND paidAt >= now-1M/M
  AND paidAt < now/M

• Vegan and gluten-free recipes that are currently in season — no soft-deleted rows.

  tags contains ('vegan', 'gluten-free')
  AND ingredients ALL (inSeason is true)
  AND deletedAt is null

• Comments from the last 7 days on posts I follow, excluding flagged or deleted.

  post.followers ANY (userId = :userId)
  AND createdAt >= now-7d
  AND deletedAt is null
  AND flagged is false

• Pro-tier notifications on a typed JSONB payload that have not been seen.

  payload__tier = 'pro'
  AND seenAt is null
  ORDER BY createdAt DESC

• Users active in the last week with at least one purchase, not banned, in specific roles.

  lastLoginAt >= now-7d
  AND purchases ANY (status = 'paid')
  AND status != 'banned'
  AND role in ('admin', 'editor', 'moderator')

• Busy tickets: open, grouped work with real volume — HAVING without writing SQL.

  status = 'open'
  AND count(*) >= 5
  AND count(distinct assignee) > 1

• Reusable: tenant-bound query parameterized for a saved view.

  tenantId = :tenantId
  AND status in :statuses
  AND createdAt >= :since
  AND createdAt <= :until

# safety

Safe by construction

Every front-end goes through the same path. There is no string concatenation anywhere; user input never reaches the database as SQL text.

1. 01

   Parse

   A GraphQL `WhereInput`, a FiltrQL string, or an MCP tool argument all parse to the same AST. The AST is shape-checked against the entity's schema before any SQL is touched.

2. 02

   Resolve

   Identifiers are mapped to columns and join paths. Unknown fields fail loudly at the API layer with a structured error pointing at `source.parameter` or `source.pointer`.

3. 03

   Compile

   The AST is compiled to a parameterized SQL fragment. Literals become `$1`, `$2`, …; the database driver binds them as values, never as text. Even regex sources are parameterized.

4. 04

   Compose

   The compiled fragment composes with row-level filters, tenancy and soft-delete predicates — written once as SQL comments — into a single WHERE clause. One model, every protocol.

The same pipeline runs whether the filter came from a search box, a URL, or an AI agent. The AI agent cannot construct a SQL string. It can only describe a predicate.

# per protocol

One filter, native to each protocol

The grammar is shared. The shape adapts — typed JSON for GraphQL, a text DSL for REST, a string argument for MCP — so each surface still feels native.

{
  status: { eq: "published" },
  servings: { gte: 4 },
  cuisine: { name: { icontains: "italian" } },
  reviews: { some: { rating: { gte: 5 } } }
}

GET /api/v1/recipes
  ?filter=status = 'published'
          AND servings >= 4
          AND cuisine.name icontains 'italian'
          AND reviews ANY (rating >= 5)
  &sort=-createdAt

{ "name": "filter_help",
  "arguments": { "entity": "recipes" } }

{
  "name": "graphql_query",
  "arguments": {
    "query": "{ recipes(limit: 20,
      filterql: \"cuisine.name
        icontains 'italian'\")
      { edges { node { id title } } } }"
  }
}