DEV Community: torshid

One Filter Language, Every Database: Type-Safe Filtering from React to Prisma and Drizzle

torshid — Wed, 12 Aug 2026 07:14:10 +0000

Your React app has a beautiful query builder. Your users can filter by any field, any operator, any combination. Then the filter string hits your Node.js backend and everything falls apart. You write a bespoke parser that maps ?filter=status:active to { where: { status: 'active' } }. Then someone asks for status in ['active','pending']. Then someone else wants createdAt > '2024-01-01'. Before long you have a hundred lines of string splitting, type coercion, and edge cases that break every time a new field gets added.

FilterKit solves this. It is a TypeScript library that speaks the exact same filter language as Spring Filter on the Java side, but for the Node.js ecosystem it does something different: it feeds directly into Prisma and Drizzle. One expression string. Two ORMs. Zero hand written parsers.

I will walk through the full pipeline. React query builder on the frontend, FilterKit core in the middle, Prisma or Drizzle on the backend. By the end you will have a setup where adding a new filterable field requires exactly zero backend code changes.

The filter expression format

Everything starts with a filter string. It looks like SQL but it is not SQL. It is a simple expression language that FilterKit parses into an AST:

status in ['active','pending'] and createdAt > '2024-01-01' and total >: 100

Operators are : for equals, ! for not, > < >: <: for comparisons, ~ for LIKE with % and _ wildcards, ~~ for case insensitive LIKE, in and not in for arrays, is null and is empty for null checks, between for ranges, and and/or/xor/not for logic. Parentheses control grouping. Everything is case insensitive.

This string is what travels over the wire. The frontend builds it. The backend parses it. Neither side needs to know what database the other uses.

The frontend: react-querybuilder

Same setup as every FilterKit frontend integration. Install the query builder and the adapter:

npm install react-querybuilder @turkraft/filterkit-querybuilder @turkraft/filterkit @tanstack/react-query

Configure the fields your API exposes:

import { useState } from 'react';
import { QueryBuilder } from 'react-querybuilder';
import { toFilterExpression } from '@turkraft/filterkit-querybuilder';
import { useQuery } from '@tanstack/react-query';

const fields = [
  { name: 'name',     label: 'Name',     inputType: 'text' },
  { name: 'email',    label: 'Email',    inputType: 'text' },
  { name: 'role',     label: 'Role',     inputType: 'text' },
  { name: 'active',   label: 'Active',   inputType: 'checkbox' },
  { name: 'age',      label: 'Age',      inputType: 'number' },
  { name: 'createdAt',label: 'Created',  inputType: 'date' },
];

function UserSearch() {
  const [query, setQuery] = useState({ combinator: 'and', rules: [] });
  const filterExpression = toFilterExpression(query);

  const { data } = useQuery({
    queryKey: ['users', filterExpression],
    queryFn: () =>
      fetch(`/api/users?filter=${encodeURIComponent(filterExpression)}`)
        .then(r => r.json()),
  });

  return <QueryBuilder fields={fields} query={query} onQueryChange={setQuery} />;
}

When a user filters for active users older than 25, the expression becomes active : true and age > '25'. URL encoded, sent to the backend. Simple.

Backend path A: Prisma

Prisma's where clause format is a nested object. The FilterKit Prisma adapter converts a filter expression string directly into that object. No manual parsing.

Install:

npm install @turkraft/filterkit-prisma @turkraft/filterkit

Your route handler:

import { toPrismaWhere } from '@turkraft/filterkit-prisma';

app.get('/api/users', async (req, res) => {
  const filterString = req.query.filter as string || '';
  const where = toPrismaWhere(filterString);

  const users = await prisma.user.findMany({ where });

  res.json(users);
});

That is it. The backend has three lines of filtering logic. Here is what happens under the hood for different filter expressions:

Filter expression	Prisma `where` object
`age > 25`	`{ age: { gt: 25 } }`
`role in ['admin','mod']`	`{ role: { in: ['admin','mod'] } }`
`name ~ '%john%'`	`{ name: { contains: 'john' } }`
`name ~ 'A%'`	`{ name: { startsWith: 'A' } }`
`name ~ '%doe'`	`{ name: { endsWith: 'doe' } }`
`name ~~ '%john%'`	`{ name: { contains: 'john', mode: 'insensitive' } }`
`deletedAt is null`	`{ deletedAt: null }`
`createdAt between '2024-01-01' and '2024-12-31'`	`{ createdAt: { gte: '2024-01-01', lte: '2024-12-31' } }`
`age > 25 and role : 'admin'`	`{ AND: [{ age: { gt: 25 } }, { role: 'admin' }] }`
`status : 'active' or status : 'trial'`	`{ OR: [{ status: 'active' }, { status: 'trial' }] }`
`not deletedAt is not null`	`{ NOT: { deletedAt: { not: null } } }`
`color : 'red' xor size : 'large'`	`{ OR: [{ AND: [{ color: 'red' }, { NOT: { size: 'large' } }] }, { AND: [{ NOT: { color: 'red' } }, { size: 'large' }] }] }`

The adapter handles the mapping, type coercion, operator dispatch, and all edge cases. It walks the parsed AST node by node, matching each operator with instanceof and building the corresponding Prisma structure. If you send ?filter=garbage, the parser throws an InvalidSyntaxException with the exact position of the error. You catch it in your error handler and return a 400 with a helpful message.

Nested relations work too. If your Prisma schema has:

model Post {
  id       String  @id
  title    String
  author   User    @relation(fields: [authorId], references: [id])
  authorId String
}

model User {
  id    String @id
  name  String
  posts Post[]
}

A filter expression like author.name : 'alice' produces:

{ "author": { "name": "alice" } }

The dotted field path is automatically expanded into nested objects. No recursion to write. No manual join specification. Prisma handles the SQL generation from there.

Backend path B: Drizzle

Drizzle works differently from Prisma. There is no JSON where object. Instead, Drizzle uses typed SQL builder functions (eq, gt, like, and, or) that require actual column references. This means the adapter needs a column map: a record mapping filter field names to Drizzle column objects.

Install:

npm install @turkraft/filterkit-drizzle @turkraft/filterkit drizzle-orm

Define your schema:

import { pgTable, text, integer, boolean, timestamp } from 'drizzle-orm/pg-core';

export const users = pgTable('users', {
  id:        integer('id').primaryKey(),
  name:      text('name'),
  email:     text('email'),
  role:      text('role'),
  active:    boolean('active'),
  age:       integer('age'),
  createdAt: timestamp('created_at'),
});

The column map tells the adapter how filter field names correspond to Drizzle columns:

import { toDrizzleWhere } from '@turkraft/filterkit-drizzle';

const columnMap = {
  name:      users.name,
  email:     users.email,
  role:      users.role,
  active:    users.active,
  age:       users.age,
  createdAt: users.createdAt,
};

Your route handler:

app.get('/api/users', async (req, res) => {
  const filterString = req.query.filter as string || '';

  const where = toDrizzleWhere(filterString, columnMap);

  const rows = await db
    .select()
    .from(users)
    .where(where)
    .limit(50);

  res.json(rows);
});

Same three lines of filtering logic. The column map is the only Drizzle specific part, and it serves a dual purpose: it maps field names to columns, and it acts as a whitelist. If a filter references a field not in the map, toDrizzleWhere returns undefined and no where clause is applied. This prevents SQL injection via arbitrary field names and ensures only explicitly whitelisted fields are filterable.

Here is the Drizzle operator mapping:

Filter expression	Drizzle output
`age > 25`	`gt(users.age, 25)`
`role in ['admin','mod']`	`inArray(users.role, ['admin','mod'])`
`name ~ '%john%'`	`like(users.name, '%john%')`
`name ~~ '%john%'`	`ilike(users.name, '%john%')`
`deletedAt is null`	`isNull(users.deletedAt)`
`createdAt between '2024-01-01' and '2024-12-31'`	`between(users.createdAt, '2024-01-01', '2024-12-31')`
`age > 25 and role : 'admin'`	`and(gt(users.age, 25), eq(users.role, 'admin'))`
`status : 'active' or status : 'trial'`	`or(eq(users.status, 'active'), eq(users.status, 'trial'))`

The output from toDrizzleWhere is a typed Drizzle SQL object. You pass it directly into .where(). Drizzle composes it into the final parameterized SQL query. No string concatenation, no injection risk.

Prisma vs Drizzle: which adapter to choose?

Both adapters produce the same outcome from the same filter expression. The choice depends on your ORM and your preferences.

Choose Prisma if:

You already use Prisma and want zero additional configuration
You want automatic nested relation traversal. The adapter handles author.name : 'alice' without any extra setup.
You prefer a declarative, JSON based where format that you can log and inspect

Choose Drizzle if:

You already use Drizzle and want typed SQL output
You want an explicit column whitelist. The column map doubles as a security boundary: fields not in the map cannot be filtered, period.
You want zero runtime overhead. Drizzle's query builder composes directly into SQL; there is no intermediate JSON layer.
You need fine grained control over which columns map to which filter names. Your API can expose created while your database column is created_at, and the column map bridges that gap.

What about both?
You can use both adapters in the same project. Filter expressions are ORM agnostic. A service layer can take a filter string and decide at runtime whether to query via Prisma or Drizzle based on the entity or the endpoint. The adapter call itself is one line. You are not locked into either ORM for the lifetime of your project.

Security: prevention, not detection

Sending raw filter strings as URL parameters raises a fair question: is this safe? Three layers of protection.

First, the parser. FilterKit tokenizes the input and rejects any expression that does not match the grammar. Invalid syntax produces an InvalidSyntaxException with position information. No arbitrary code execution, no JavaScript evaluation, no eval() anywhere in the pipeline.

Second, the adapter. Both Prisma and Drizzle adapters produce parameterized queries. The filter values are never concatenated into SQL strings. Prisma uses its own query engine with native parameterization. Drizzle uses PostgreSQL parameterized queries via pg. Neither adapter calls toString() on a user supplied value and slaps it into a template literal.

Third, the column map in Drizzle and the field traversal in Prisma. You only map the fields you want filterable. If a user sends ?filter=creditCardNumber : '4111...' and creditCardNumber is not in the column map, Drizzle returns undefined for the where clause. If the field does not exist on the Prisma model, the query engine returns a validation error. Either way, the database never sees the attempted filter.

You can add a fourth layer, a field whitelist, directly in your route handler:

const ALLOWED_FIELDS = new Set(['name', 'email', 'role', 'active', 'age', 'createdAt']);

function validateFilter(filterString: string): string {
  const roughCheck = filterString.match(/\b[a-zA-Z._]+\b/g) || [];
  for (const field of roughCheck) {
    const topLevel = field.split('.')[0];
    if (!ALLOWED_FIELDS.has(topLevel)) {
      throw new Error(`Field "${topLevel}" is not filterable`);
    }
  }
  return filterString;
}

app.get('/api/users', async (req, res) => {
  try {
    const filterString = validateFilter(req.query.filter as string || '');
    const where = toPrismaWhere(filterString);
    const users = await prisma.user.findMany({ where });
    res.json(users);
  } catch (e) {
    res.status(400).json({ error: e.message });
  }
});

This catches attempts to filter on fields that exist in the database but should not be exposed through the search API. Combine it with the column map in Drizzle and you have defense in depth without a single annotation or decorator.

Performance: parse once, query once

FilterKit parses the filter expression into an AST, then the adapter walks the AST once to build the where clause. Both operations are synchronous and CPU bound. For a typical filter expression with five to ten conditions, parsing takes well under a millisecond.

The resulting query performance depends entirely on your database indexes. The adapter does not add overhead. A Prisma query with { where: { age: { gt: 25 } } } is identical whether you wrote that object by hand or produced it through the adapter. Drizzle's gt(users.age, 25) compiles to the same SQL parameterized query either way.

If you are worried about parsing overhead on high traffic endpoints, parse the filter once and cache the AST. The AST is a plain JavaScript object, safe to serialize and reuse. Or let your CDN cache the response if the same filter gets requested repeatedly.

The complete pipeline, from click to query

A user opens your admin panel. They click the query builder, add a rule: role equals admin, age greater than 28. They click search.

The frontend calls toFilterExpression(). The query builder state becomes role : 'admin' and age > '28'. URL encoded, sent to /api/users?filter=role%20%3A%20%27admin%27%20and%20age%20%3E%20%2728%27.

The backend extracts the query parameter. If using Prisma, it calls toPrismaWhere(filterString). The returned object is { AND: [{ role: 'admin' }, { age: { gt: 28 } }] }. Passed to prisma.user.findMany({ where }). Prisma generates a parameterized SQL query. The database returns matching rows. The backend sends JSON.

The frontend did not know the backend uses Prisma. The backend did not know the frontend uses react-querybuilder. The filter string is the contract, and FilterKit is the translator on both ends.

If you swap Prisma for Drizzle next sprint, the frontend does not change. The filter expression stays the same. Only the backend adapter call changes from toPrismaWhere to toDrizzleWhere. Everything else (pagination, sorting, field selection) remains untouched because it never depended on the ORM in the first place.

The FilterKit ecosystem

FilterKit is not just a parser. It is a family of libraries built around the same expression format:

Package	Role
`@turkraft/filterkit`	Core. Parser, builder, stringifier, in memory array filtering.
`@turkraft/filterkit-querybuilder`	react-querybuilder state to FilterKit expression. Frontend.
`@turkraft/filterkit-tanstack`	TanStack Table column filters to FilterKit expression. Frontend.
`@turkraft/filterkit-prisma`	FilterKit expression to Prisma where clause. Backend.
`@turkraft/filterkit-drizzle`	FilterKit expression to Drizzle where clause. Backend.

The core package (@turkraft/filterkit) has zero runtime dependencies. It is about 15KB minified. The adapters each add their respective ORM as a peer dependency and a few hundred lines of operator mapping code. Nothing heavy.

If you are on the Java side, Spring Filter speaks the exact same expression language for JPA Criteria, MongoDB queries, and in memory Java Predicates. Same syntax, same AST structure, same operator precedence. A frontend built with FilterKit can target either a Node.js backend or a Spring Boot backend without changing a single line of filter construction code. The expression string is the universal layer.

When not to use this

The filter expression language is designed for WHERE clauses. It does not handle aggregations, GROUP BY, HAVING, window functions, or subqueries. If your API needs to expose SELECT department, AVG(salary) FROM employees GROUP BY department HAVING AVG(salary) > 50000, you need a different approach. A reporting endpoint with a predefined query set, or a BI tool embedded in your application, will serve that use case better than a general purpose filter parser.

If your database schema changes rapidly and you cannot maintain a column map or rely on Prisma's introspection, you may prefer a more dynamic approach. But you probably should not be exposing a raw filter API on a rapidly changing schema in the first place. Version your API.

If your filter expressions routinely exceed a few hundred characters, the URL length limit may become a concern. Most browsers and servers support URLs up to 8000 characters. Keep your filter expressions concise and consider POST based search endpoints for complex queries.

FilterKit: github.com/turkraft/filterkit | npm: @turkraft/filterkit
Spring Filter (Java): github.com/turkraft/springfilter

Both are MIT licensed. The Prisma and Drizzle adapters live alongside the core library at the same GitHub organization.

Fullstack Dynamic Filtering: React Query Builder to Spring Boot in One Pipeline

torshid — Wed, 12 Aug 2026 07:11:48 +0000

Here's something that took me way too long to realize: filtering isn't a frontend problem or a backend problem. It's a pipeline problem. Your React app builds a query object. Your Spring Boot app receives a query string. If the two disagree on what >= means or how between works or whether name ~ 'A%' is case-sensitive, you're shipping a bug that neither side will catch because neither side is wrong. They're just speaking different languages.

FilterKit and Spring Filter speak the same language. Exactly the same syntax, same AST, same operator precedence. What gets built on the frontend is byte-for-byte what the backend expects. This article walks through the full pipeline: React query builder → filter expression string → HTTP request → Spring Boot controller → JPA Specification → SQL query.

I'll walk through two frontend approaches since different teams prefer different UIs: react-querybuilder for a Jira-style filter panel, and TanStack Table for column header filters. Both end up producing the exact same query string on the wire. The backend doesn't know or care which one you used.

I'll use a car dealership inventory app as the example because it has everything: range filters (year, km), multi-select (brand), fuzzy text search (model name), and nested relations (brand → manufacturer → country). Real-world messy.

The app we're building

A single-page React app with a filter panel on the left and a results table on the right. The filter panel has:

Year: range slider (2010 to 2025)
Brand: multi-select checkboxes
Model: text search with autocomplete
Max km: number input
Color: enum dropdown
Accident history: toggle (has accidents / no accidents)

When any filter changes, the table updates. Filtering happens server-side (manual filtering, not client-side). Pagination, sorting, and field selection are included but I won't dwell on them; they're in the Spring Filter page-sort module and just work.

Step 1: The filter query string format

Before we write any code, we agree on the wire format. Spring Filter and FilterKit share this:

year between 2018 and 2025 and brand.name in ['audi','bmw'] and km < 50000

Operators: : for equals, ! for not, > < >: <: for comparisons, ~ for LIKE, ~~ for case-insensitive LIKE, in / not in for collections, is null / is empty for null/empty checks, and / or / xor / not for logic. Parentheses for grouping. All case-insensitive.

This gets URL-encoded and sent as ?filter=year%20between.... The backend parses it, turns it into a JPA Specification, runs the query.

Step 2: The Spring Boot backend

Standard Spring Boot setup. Dependencies:

<dependency>
    <groupId>com.turkraft.springfilter</groupId>
    <artifactId>jpa</artifactId>
    <version>4.0.4</version>
</dependency>
<dependency>
    <groupId>com.turkraft.springfilter</groupId>
    <artifactId>page-sort</artifactId>
    <version>4.0.4</version>
</dependency>
<dependency>
    <groupId>com.turkraft.springfilter</groupId>
    <artifactId>openapi</artifactId>
    <version>4.0.4</version>
</dependency>

Car entity (abbreviated, you know what an entity looks like):

@Entity
public class Car {
    @Id @GeneratedValue
    private Long id;
    private int year;
    private int km;
    private String model;
    @Enumerated(EnumType.STRING)
    private Color color;
    @ManyToOne
    private Brand brand;
    @OneToMany(mappedBy = "car")
    private List<Accident> accidents;
}

Brand entity:

@Entity
public class Brand {
    @Id @GeneratedValue
    private Long id;
    private String name;
    @ManyToOne
    private Manufacturer manufacturer;
}

Repository:

public interface CarRepository extends JpaRepository<Car, Long>,
    JpaSpecificationExecutor<Car> {}

Controller:

@Fields
@GetMapping("/cars")
public Page<Car> search(
        @Filter Specification<Car> spec,
        @Pagination Pageable pageable) {
    return carRepository.findAll(spec, pageable);
}

That's the whole controller. Three lines. The @Filter annotation tells Spring Filter to parse the ?filter= query parameter into a JPA Specification. The @Pagination annotation handles ?page=0&size=20&sort=-year. The @Fields annotation handles ?fields=id,model,year,brand.name. All without writing any parameter parsing code.

What happens under the hood when ?filter=year between 2018 and 2025 and km < 50000 arrives:

Spring MVC extracts the filter parameter
FilterNodeArgumentResolver picks it up (because of @Filter)
FilterParser tokenizes and parses the string into an AST
FilterSpecificationConverter walks the AST and builds a JPA Criteria Specification<Car>
Spring Data JPA's findAll(Specification, Pageable) executes it
Hibernate generates SQL like:

   SELECT ... FROM car c
   LEFT JOIN brand b ON c.brand_id = b.id
   WHERE c.year >= 2018 AND c.year <= 2025 AND c.km < 50000
   LIMIT 20 OFFSET 0

Zero custom query methods. Zero @Query annotations. The controller doesn't know what fields exist on Car. Add a new field to the entity and it's automatically filterable.

Step 3: The React frontend: react-querybuilder

For the filter panel, I'm using react-querybuilder. It gives you a drag-and-drop query builder UI with rule groups, combinators, and operator selectors. Users who've used Jira's advanced search or Salesforce reports know the pattern.

Install:

npm install react-querybuilder @turkraft/filterkit-querybuilder @turkraft/filterkit @tanstack/react-query

Configure the query builder with the fields and operators our API supports:

import { useState } from 'react';
import { QueryBuilder } from 'react-querybuilder';
import { toFilterExpression } from '@turkraft/filterkit-querybuilder';
import { useQuery } from '@tanstack/react-query';

const fields = [
  { name: 'year',       label: 'Year',        inputType: 'number' },
  { name: 'km',          label: 'Kilometers',   inputType: 'number' },
  { name: 'model',       label: 'Model',        inputType: 'text' },
  { name: 'brand.name',  label: 'Brand',        inputType: 'text' },
  { name: 'color',       label: 'Color',        inputType: 'text' },
  { name: 'accidents',   label: 'Accidents',    inputType: 'text' },
];

const operators = [
  { name: '=',       label: 'is' },
  { name: '!=',      label: 'is not' },
  { name: '<',       label: 'less than' },
  { name: '>',       label: 'greater than' },
  { name: '<=',      label: 'less or equal' },
  { name: '>=',      label: 'greater or equal' },
  { name: 'between', label: 'between' },
  { name: 'in',      label: 'in' },
  { name: 'contains', label: 'contains' },
  { name: 'beginsWith', label: 'starts with' },
  { name: 'null',    label: 'is null' },
  { name: 'notNull', label: 'is not null' },
];

const initialQuery = {
  combinator: 'and',
  rules: [],
};

The component:

function CarFilterPanel() {
  const [query, setQuery] = useState(initialQuery);

  // Convert react-querybuilder state → SpringFilter expression string
  const filterExpression = toFilterExpression(query);

  // Fetch cars whenever the filter changes
  const { data, isLoading } = useQuery({
    queryKey: ['cars', filterExpression],
    queryFn: () =>
      fetch(`/api/cars?filter=${encodeURIComponent(filterExpression)}`)
        .then(r => r.json()),
  });

  return (
    <div>
      <QueryBuilder
        fields={fields}
        query={query}
        onQueryChange={setQuery}
        controlClassnames={{ queryBuilder: 'queryBuilder-branches' }}
      />
      <CarTable cars={data?.content ?? []} />
    </div>
  );
}

That's it. The user builds a query in the UI. toFilterExpression() converts it to a SpringFilter string. The string goes in a URL parameter. The backend parses it natively. No translation layer, no mapping, no mismatches.

What does toFilterExpression() actually produce? If the user adds rules:

year >= 2018
year <= 2025
km < 50000

The output is: year >: '2018' and year <: '2025' and km < '50000'

If they add a "contains" rule on model with value "audi":
model ~ '%audi%'

The % is the SQL LIKE wildcard. Spring Filter's JPA transformer maps ~ to the JPA like() function and % works identically in both worlds. No case conversion, no parameter splitting, no "wait does contains mean substring match or word match?" ambiguity.

Step 4: TanStack Table with column header filters

If your app already uses TanStack Table for data display, you can skip the separate query builder panel and let users filter directly from column headers. FilterKit ships a TanStack adapter that translates column filter state into the same wire format.

Install:

npm install @tanstack/react-table @turkraft/filterkit-tanstack @turkraft/filterkit @tanstack/react-query

Configure the table with manualFiltering: true. This tells TanStack your backend handles filtering, not the browser:

import { useReactTable, getCoreRowModel, getFilteredRowModel } from '@tanstack/react-table';
import type { ColumnFilter } from '@tanstack/react-table';
import { toFilterString } from '@turkraft/filterkit-tanstack';
import { useQuery } from '@tanstack/react-query';

function CarTable() {
  const [columnFilters, setColumnFilters] = useState<ColumnFilter[]>([]);

  const filterQuery = toFilterString(columnFilters);

  const { data } = useQuery({
    queryKey: ['cars', filterQuery],
    queryFn: () =>
      fetch(`/api/cars?filter=${encodeURIComponent(filterQuery)}`)
        .then(r => r.json()),
  });

  const table = useReactTable({
    data: data?.content ?? [],
    columns,
    state: { columnFilters },
    onColumnFiltersChange: setColumnFilters,
    manualFiltering: true,    // server-side, not client-side
    getCoreRowModel: getCoreRowModel(),
    getFilteredRowModel: getFilteredRowModel(),
  });

  return <TableComponent table={table} />;
}

toFilterString() takes TanStack's ColumnFilter[] array ([{ id: 'year', value: [2018, 2025] }, { id: 'km', value: [0, 50000] }]) and produces year between '2018' and '2025' and km between '0' and '50000'.

Same backend. Different frontend. Same wire format. The TanStack adapter handles the mapping for you. A range filter [2018, 2025] becomes year between '2018' and '2025', a string value 'audi' becomes brand.name : 'audi', an array of strings becomes an in clause. Same filter expression, same URL parameter, same backend response.

If you're wondering which frontend to pick: react-querybuilder gives you more flexibility (nested AND/OR groups, custom operators), TanStack Table is more streamlined (column headers, no separate panel). Both hit the same endpoint. You can even mix them: querybuilder on the admin dashboard, TanStack on the public listing page. The backend doesn't care.

Step 5: What if you need security? Multi-tenancy?

The pipeline doesn't break when you bolt on ParseContext. In fact, that's where it shines.

Let's say each dealership only sees their own cars. The filter panel still sends ?filter=year > 2020. The controller still receives it. But before it hits the repository, a ParseContext injects the tenant clause:

@Service
public class TenantCarService {

    @Autowired FilterParser parser;
    @Autowired FilterSpecificationConverter converter;
    @Autowired FilterBuilder fb;

    public Specification<Car> parse(String filter, Long dealershipId) {
        ParseContext ctx = new ParseContextImpl(null, userNode -> {
            FilterNode tenantFilter = fb.field("dealership.id")
                .equal(fb.input(dealershipId))
                .get();
            return fb.and(tenantFilter, userNode).get();
        });

        FilterNode node = parser.parse(filter, ctx);
        return converter.convert(node);
    }
}

Your controller changes from the @Filter Specification shortcut to a manual call:

@GetMapping("/cars")
public Page<Car> search(@Filter String rawFilter,
                         @AuthenticationPrincipal User user,
                         @Pagination Pageable pageable) {
    Specification<Car> spec = tenantService.parse(rawFilter, user.getDealershipId());
    return carRepository.findAll(spec, pageable);
}

The frontend never sends dealershipId. Doesn't even know it exists. The backend injects it. The SQL becomes:

WHERE (c.dealership_id = 42) AND (c.year >= 2020)

You trade one line of magic (@Filter Specification<Car> spec) for one line of explicit control (tenantService.parse(rawFilter, ...)). Well worth it when the alternative is sprinkling tenant_id = ? through every repository method. Same pattern works for soft deletes, row-level security, audit logging. The frontend sends what the user typed. ParseContext adds what the system needs.

Step 6: MongoDB instead of JPA? Same frontend, different converter

If you switch from JPA to MongoDB, or run both simultaneously, the frontend code doesn't change. The filter expression is database-agnostic.

Backend with MongoDB:

@GetMapping("/cars")
public List<Car> search(@Filter(entityClass = Car.class) Query query, Pageable pageable) {
    return mongoTemplate.find(query.with(pageable), Car.class);
}

The query.with(pageable) call applies skip and limit, so the result is already paginated even though we return a plain List.

Same ?filter=year > 2020, different converter: FilterQueryConverter instead of FilterSpecificationConverter. The AST is the same. The serialization is the same. Only the target output changes.

Database-agnostic filtering means you can start with JPA + H2 for development, move to PostgreSQL for staging, add MongoDB for a specific collection, and never touch the frontend. This is the kind of thing that saves you from rewriting filter panels when the CTO decides to "just try MongoDB for the search index."

Step 7: Bonus: automatic Swagger docs

Remember the openapi dependency we added? Launch the app, navigate to /swagger-ui.html, and the filter parameter on /cars is documented automatically:

Type: string (filter expression)
All filterable fields listed with types (year: integer, brand.name: string, color: enum)
Example queries generated from entity metadata
Operator reference table
Pagination and sort parameters documented

Your frontend team can read the Swagger docs and know exactly what fields are filterable without reading entity source code. If you add a field to the entity, it appears in Swagger on the next restart. No manual annotation updates.

Step 8: The complete architecture diagram

┌─────────────────────────────────────────┐
│  BROWSER                                │
│                                         │
│  react-querybuilder  or  TanStack       │
│       ↓ toFilterExpression /           │
│         toFilterString                 │
│  "year > 2020 and km < 50000"          │
│       ↓ encodeURIComponent()           │
│  GET /api/cars?filter=year%20...       │
└─────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────┐
│  SPRING BOOT                            │
│                                         │
│  @Filter Specification<Car> spec        │
│       ↓ FilterParser.parse()           │
│  AST: AND(GT(year,2020), LT(km,50000)) │
│       ↓ ParseContext (optional)        │
│  AST: AND(tenant=42, AND(original...))  │
│       ↓ FilterSpecificationConverter   │
│  JPA Specification<Car>                │
│       ↓ repository.findAll(spec)       │
│  SQL: WHERE c.dealership_id = 42       │
│       AND c.year > 2020                │
│       AND c.km < 50000                  │
└─────────────────────────────────────────┘

Wait, but this sends filter queries as URL params. Isn't that a security problem?

It's the same security model as ?page=2&size=20&sort=-year. The filter expression is parsed, validated, and turned into parameterized JPA Criteria queries. No SQL injection. No string concatenation. The parser rejects invalid syntax with a 400. The converter builds the query using CriteriaBuilder methods, not string templates.

If you need field-level access control on top of that, ParseContext handles it the same way as the tenant example above. Add a field mapper that throws if the field isn't on a per-role whitelist. The filter never touches the database if a restricted field is referenced.

Real talk: when does this NOT work well?

If your users need to write really complex queries like subqueries, aggregations with HAVING, or window functions, this isn't the right tool. The filter language is designed for WHERE clauses, not full SQL. For reporting dashboards that need GROUP BY and HAVING, you need a different approach (maybe a BI tool, maybe a custom endpoint with a predefined query set).

If your entities have 200 fields... the auto-generated Swagger docs will be massive and the query builder UI will be overwhelming. Consider splitting into domain-specific search endpoints (/cars/search, /cars/admin-search) with appropriate field sets.

If your team has never used a query builder UI... there's a learning curve. The react-querybuilder component helps (it's visual, not text-based), but some users will prefer typing year > 2020 directly. Spring Filter supports both: the @Filter annotation accepts any valid filter string, whether built by a UI component or typed by hand.

The code, all together

Backend (Spring Boot + Spring Filter):

One dependency: com.turkraft.springfilter:jpa:4.0.4
One annotation on the controller parameter: @Filter
One repository extending JpaSpecificationExecutor
Optional: ParseContext for security/tenant/soft-delete injection
That's it

Frontend (React + FilterKit):

With react-querybuilder: @turkraft/filterkit + @turkraft/filterkit-querybuilder → toFilterExpression(query)
With TanStack Table: @turkraft/filterkit + @turkraft/filterkit-tanstack → toFilterString(columnFilters)
Standard fetch() or useQuery() call either way
That's it

The "that's it" part is what I'm happiest about. I've built this pipeline probably six or seven times across different projects. Querydsl, custom JSON schema, manual parameter parsing, Swagger docs by hand, frontend state management for filter values. Every single time it was 500+ lines of boilerplate that broke in subtle ways. This pipeline is tiny compared to what it replaces. And it breaks loudly (parser error, 400 response) rather than silently (wrong results, zero rows, confused users). That alone is worth the switch.

The code for both libraries is on GitHub: FilterKit for the frontend, Spring Filter for the backend. There's a live demo at springfilter-jpa.onrender.com if you want to try the filter syntax without setting anything up.

From Querydsl to Spring Filter: One Syntax, Three Backends

torshid — Wed, 12 Aug 2026 06:53:53 +0000

Querydsl is one of those libraries that everyone used for years and then quietly stopped updating. The 5.0 release has been "coming soon" since 2019. The GitHub shows commits but no milestone. The issue tracker has a thread titled "Is Querydsl dead?" with hundreds of comments.

It's not dead. But if you're starting a new project in 2026 and you're picking between Querydsl and something that's actively maintained, has Spring Boot 4 support, works with MongoDB and in-memory collections, generates OpenAPI docs automatically, and has companion frontend libraries... well, you see where I'm going.

This isn't a "Querydsl bad, Spring Filter good" article. Querydsl pioneered type-safe querying for Java and it deserves credit. But migrations happen, and if you're considering one, here's what the conversion looks like.

Side-by-side: basic filtering

Querydsl:

QCar car = QCar.car;

BooleanExpression filter = car.year.gt(2020)
    .and(car.km.lt(50000))
    .and(car.color.eq(Color.RED));

List<Car> results = new JPAQuery<>(entityManager)
    .select(car)
    .from(car)
    .where(filter)
    .fetch();

Spring Filter (query string):

@Filter Specification<Car> spec
// URL: ?filter=year > 2020 and km < 50000 and color : 'red'
List<Car> results = carRepo.findAll(spec);

Spring Filter (programmatic builder):

FilterNode filter = fb.field("year").greaterThan(fb.input(2020))
    .and(fb.field("km").lessThan(fb.input(50000)))
    .and(fb.field("color").equal(fb.input(Color.RED)))
    .get();

Specification<Car> spec = converter.convert(filter);
List<Car> results = carRepo.findAll(spec);

Spring Filter (type-safe builder):

FilterNode f = CarFilter.where(fb)
    .year().greaterThan(2020)
    .and()
    .km().lessThan(50000)
    .and()
    .color().equal(Color.RED)
    .build();

Specification<Car> spec = converter.convert(f);
List<Car> results = carRepo.findAll(spec);

The type-safe builder reads almost exactly like Querydsl. The difference is that CarFilter is generated from your JPA entity via annotation processor, not from a separate Q-class that needs its own build step.

What Querydsl does that Spring Filter doesn't

Gotta be honest about this part.

1. SQL-level joins and subqueries.
Querydsl can express SELECT * FROM cars WHERE brand_id IN (SELECT id FROM brands WHERE country = 'DE'). Spring Filter doesn't generate subqueries. It handles entity relation traversal (brand.name : 'audi') which generates a JOIN under the hood, but complex subquery logic isn't in scope. If your query needs EXISTS (SELECT ...), you'll still need CriteriaBuilder or native SQL for that part.

2. Update and delete queries.
Querydsl has new JPAUpdateClause() and new JPADeleteClause(). Spring Filter is read-only. It generates WHERE clauses, not DML. If you need to bulk-update filtered records, you apply the generated Specification to find them, then update manually. Not as clean.

3. Tuple projections without mapping to DTOs.
Querydsl lets you select arbitrary expressions into Tuple objects. Spring Filter doesn't do projections at all -- it only generates WHERE clauses. Your SELECT is handled by Spring Data or your own CriteriaQuery setup. You can use Spring Filter's Specification in a projection query (the README shows how), but the projection itself is still CriteriaBuilder code.

4. Maturity of the type system.
Querydsl's APT processor handles generics, wildcards, and complex type hierarchies better than Spring Filter's @Filterable processor. If your entities use Map<Class<?>, List<? extends Serializable>> or similar, Querydsl generates correct Q-types. Spring Filter will skip or approximate these. For the 95% case (simple fields, enums, dates, basic collections), it's fine.

What Spring Filter does that Querydsl doesn't

1. MongoDB support with the same syntax.
Same filter string, same builder API, different converter:

// JPA
?filter=year > 2020  -->  Specification<Car>

// MongoDB
?filter=year > 2020  -->  Query (MongoDB query object)

One syntax across two databases. Querydsl has a MongoDB module but its syntax differs from the JPA module. Spring Filter's AST is database-agnostic.

2. In-memory predicate filtering.
No database at all:

@Filter Predicate<Car> predicate
// URL: ?filter=year > 2020
cars.stream().filter(predicate).collect(Collectors.toList());

This is useful for filtering cached data, testing, or filtering API responses after fetch. Querydsl has CollQuery for collections but it's more verbose and less commonly used.

3. Automatic OpenAPI/Swagger docs.
Add the openapi module and your Swagger UI automatically documents every filterable field, its type, available operators, and example queries. With Querydsl you're writing parameter docs by hand.

4. Frontend libraries that speak the same language.
FilterKit (the JS/TS sister library) uses the exact same filter syntax and AST. Your React frontend builds a query object, serializes it, sends it as a URL parameter, and your Spring backend parses it natively. No translation layer, no mapping, no mismatches. Querydsl has no frontend story.

5. ParseContext.
I keep talking about this in every article because it's the killer feature. ParseContext lets you intercept and rewrite filter expressions before they hit the database. Multi-tenancy, soft deletes, security filters, audit logging, field whitelisting -- all without touching your controllers. Querydsl's equivalent would be writing custom BooleanExpression wrappers per endpoint, which is more code and harder to enforce consistently.

Migration strategy: entity by entity

You don't have to rip out Querydsl in one commit. Spring Filter and Querydsl coexist fine. They use different dependency injection paths (Querydsl uses generated Q-types, Spring Filter uses @Filter annotations and converters). You can convert entities one at a time.

Step 1: Add the Spring Filter dependency alongside your existing Querydsl setup. No conflicts.
Step 2: Pick a low-traffic entity. Add @Filterable and wire up a controller with @Filter.
Step 3: Run both endpoints side by side (the old Querydsl one and the new Spring Filter one) for a release.
Step 4: Verify query results match. They should, since both generate JPA Criteria queries.
Step 5: Remove the Querydsl endpoint. Move to the next entity.

For the @Filterable part: you'll need the annotation processor in your compiler plugin. If you're already running Querydsl's APT processor, you just add a second processor path. Maven supports multiple annotation processors in the same plugin config.

The query syntax conversion cheat sheet

Operation	Querydsl (JPAQuery)	Spring Filter (AST / URL)
Equals	`car.year.eq(2020)`	`year : 2020`
Not equals	`car.year.ne(2020)`	`year ! 2020`
Greater than	`car.year.gt(2020)`	`year > 2020`
Less than	`car.year.lt(2020)`	`year < 2020`
Between	`car.year.between(2020, 2025)`	`year between 2020 and 2025`
Like	`car.name.like("%Audi%")`	`name ~ '%Audi%'`
In	`car.brand.in("audi", "bmw")`	`brand.name in ['audi', 'bmw']`
Is null	`car.deletedAt.isNull()`	`deletedAt is null`
AND	`.and(...)`	`and`
OR	`.or(...)`	`or`
Join (relation)	`car.brand.name.eq("audi")`	`brand.name : 'audi'`
Size	`car.parts.size().gt(2)`	`size(parts) > 2`

The URL syntax is more readable to non-Java developers (frontend, QA, support). The builder syntax is readable to Java developers. Both map to the same AST.

When NOT to migrate

If your project:

Uses Querydsl's SQL module (not JPA) extensively
Has complex subqueries that can't be expressed as simple filters
Is in maintenance mode and nobody's touching it
Has a team that deeply knows Querydsl and has no interest in learning a new library

...then stay on Querydsl. Don't migrate for the sake of migrating.

If your project:

Is actively developed and will be for years
Has or wants a MongoDB component alongside JPA
Has a React/Angular frontend that builds filter queries dynamically
Needs automatic Swagger docs for filterable endpoints
Wants to centralize cross-cutting concerns like multi-tenancy and soft deletes

...then the migration is worth it.

github.com/turkraft/springfilter. The JPA module is the most mature, MongoDB is close behind, and the predicate module is deceptively useful. The examples directory has working Spring Boot apps for all three.

Type-Safe Query Builders for JPA: No Strings, No Typos

torshid — Wed, 12 Aug 2026 06:49:55 +0000

String-based field references are the silent killer of JPA projects. They compile. They run. Then someone renames unitPrice to price and your /search?filter=unitPrice > 100 endpoint returns an empty result set forever. No error. No stacktrace. Just... nothing. Users think there's no data. You think the query is broken. Nobody knows what's actually happening until someone digs through logs and finds the Criteria API silently ignoring a field that no longer exists.

I've been bitten by this. Multiple times. On different projects. Same exact bug every time because "it's just a search endpoint, I'll refactor it later" and then you never do.

Spring Filter has an annotation processor that solves this. You annotate your entity with @Filterable, it generates a fluent builder class at compile time, and suddenly you can't reference fields that don't exist because the compiler won't let you.

Before: the string soup

Let's say you have a Car entity. You're building a search API and want to let users filter by year, brand name, mileage, and color. Here's how most people do it with Spring Filter's builder (which is already nicer than raw CriteriaBuilder, but still string-based):

FilterNode filter = fb.field("year")
    .greaterThan(fb.input(2020))
    .and(fb.field("brand.name")
        .in(fb.collection(fb.input("audi"), fb.input("bmw"))))
    .and(fb.field("km")
        .lessThan(fb.input(50000)))
    .and(fb.field("color")
        .equal(fb.input(Color.RED)))
    .get();

This works. It compiles. If you rename brand to manufacturer on the entity, this code doesn't break. It runs. It just... silently does nothing. The parser won't find a field called brand.name in the entity metadata and it'll throw some kind of error at parse time -- but only when a user actually sends that filter. The builder code above (which constructs the AST programmatically) might or might not fail depending on how the transformer resolves unknown fields. Point is: there's no compile-time safety.

After: the generated builder

Step 1: annotate your entity. Nothing special, just one import:

import com.turkraft.springfilter.typesafe.Filterable;

@Entity
@Filterable
public class Car {
    @Id private Long id;
    private int year;
    private int km;
    private String model;
    private boolean active;
    @Enumerated private Color color;
    @ManyToOne private Brand brand;
    @OneToMany private List<Accident> accidents;
}

Step 2: add the annotation processor to your Maven compiler plugin:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <annotationProcessorPaths>
            <path>
                <groupId>com.turkraft.springfilter</groupId>
                <artifactId>typesafe-processor</artifactId>
                <version>4.0.4</version>
            </path>
        </annotationProcessorPaths>
    </configuration>
</plugin>

Step 3: compile. The processor generates CarFilter.java in your build output.

Step 4: use it:

@Autowired FilterBuilder fb;

FilterNode f = CarFilter.where(fb)
    .year().between(2020, 2025)
    .and()
    .model().startsWith("Audi")
    .and()
    .brand().name().equal("audi")
    .and()
    .active().isTrue()
    .build();

Now if you rename model to carModel on the entity, this code won't compile. CarFilter gets regenerated with the new field names and the startsWith("Audi") line now has no matching method. Your IDE underlines it in red before you even hit save. You fix it immediately. This is the whole point.

What fields get generated?

The processor walks your entity's fields and their types and generates appropriate step classes:

int, long -> IntFieldStep (between, greaterThan, lessThan, equal, etc.)
double, BigDecimal -> DoubleFieldStep (same range ops)
boolean -> BooleanFieldStep (isTrue, isFalse)
String -> StringFieldStep (startsWith, endsWith, contains, like, equal)
Date, LocalDate, LocalDateTime -> DateFieldStep (after, before, between)
Enums -> EnumFieldStep (equal, in, notIn)
Collections (List, Set) -> CollectionFieldStep (size, isEmpty, isNotEmpty)
Entity references (@ManyToOne) -> a nested builder for that entity's fields

Fields annotated with @Transient or @JsonIgnore are skipped. Inherited fields from superclasses are included. If you have an @ElementCollection of primitives, it'll generate appropriate collection operations.

The generated code isn't some reflection black box either. You can read it. It's in your target/generated-sources directory. It's just Java classes that delegate to the filter builder. No runtime reflection, no proxy objects, nothing that would confuse your debugger.

Nested relations work out of the box

One of the things I'm kind of proud of: nested entity traversal. If Car has a Brand and Brand has a Manufacturer, you get:

CarFilter.where(fb)
    .brand().manufacturer().country().equal("germany")
    .and()
    .year().greaterThan(2020)
    .build();

Every level of nesting generates another inner builder. The processor handles @ManyToOne, @OneToOne, and embedded objects. It stops at collections (you can't chain into elements of a @OneToMany, though you can filter on collection size).

What about compile time?

The processor runs during javac. For a typical entity with 20 fields, it adds maybe 100ms to your build. It generates about 300-500 lines of Java across a handful of classes. You'll only notice it if you have hundreds of @Filterable entities, and even then, incremental compilation means it only re-processes entities that changed.

The limitation: you're locked to the entity structure

Your filterable fields mirror your JPA entity exactly. If your API exposes a field called price but your entity calls it unitPrice, you need to alias it. Spring Filter's ParseContext (covered in the multi-tenancy article) handles this with a field mapper:

ParseContext ctx = new ParseContextImpl(field -> {
    if ("price".equals(field)) return "unitPrice";
    return field;
}, null);

But the type-safe builder doesn't know about this alias. If you're using the generated builder AND field aliasing, you have a choice: either rename the entity field to match the API (preferred, if you can) or use the string-based builder for aliased fields and the type-safe builder for everything else.

Not ideal, but it's an edge case. Most projects I've seen either expose entity field names directly or have a clean enough naming convention that aliasing isn't needed.

Real world: before and after

Here's a bug I actually shipped in 2021. Entity had a field called createdAt. API docs said you could filter on createdDate because that's what the frontend team decided sounded better. We added a field mapper in ParseContext: "createdDate" -> "createdAt". Six months later someone refactored the entity, renamed createdAt to created, updated the field mapper... but forgot to update one raw @Query in a reporting endpoint that still referenced created_at (snake_case because MySQL).

Result: the reporting endpoint silently returned zero results for two weeks. Nobody noticed because the reports had low traffic.

With @Filterable, the refactor would have broken compilation. The generated CarFilter class would no longer have a createdAt() method. The mapper would still need updating, but the raw SQL query? If we were using the type-safe builder to generate filters and feeding them through the same converter, the field name change would have been caught at build time.

But we were mixing approaches. That's the real lesson: pick one consistency mechanism and stick with it. Don't half-use a type-safe builder.

Summary

The @Filterable processor gives you:

Compile-time field name validation
IDE autocomplete on every filterable field
Correctly typed comparison methods (no between() on a String field)
No runtime overhead (it's just Java code, generated once)
Works with your existing Maven/Gradle setup

What it costs:

An extra dependency (typesafe-processor)
An annotation on each entity you want to filter
100ms of build time per entity (negligible)
You have to recompile when entity fields change (which you already do)

For me the trade is obvious. I've shipped too many silent bugs from string-based field references to ever go back. The annotation processor catches what code review misses, and it catches it before QA even gets the build.

Full setup docs at github.com/turkraft/springfilter. The processor is in the typesafe-processor module if you want to poke around.

Multi-Tenant Query Filtering That Doesn't Touch Your Controllers

torshid — Wed, 12 Aug 2026 06:45:48 +0000

Remember when you first added multi-tenancy to an app? You probably went through the exact same stages I did:

Phase 1: just add tenant_id = ? to the controller. Easy.
Phase 2: realize you have 30 controllers. Add it everywhere. Swear a lot.
Phase 3: someone adds a new endpoint and forgets. Bug in prod. More swearing.
Phase 4: create a base repository method. Feels clever for about a week.
Phase 5: someone writes a native query or a report endpoint that bypasses the base repo. Swearing intensifies.

I went through all five phases before I realized the problem isn't the repository layer at all. The problem is that filtering happens at the wrong level. If your controller receives a filter string, parses it, and then slaps on a tenant clause, you're doing surgery at the reception desk. You should intercept the filter before anyone even sees the patient.

Here's the thing about Spring Filter's ParseContext: it sits between the HTTP request and your JPA repository. The filter string comes in as status : 'active'. Before it hits the query builder, ParseContext can rewrite the AST and turn it into tenantId : 42 and status : 'active'. Your controller has no idea. Your repository has no idea. Neither of them needs to.

The 20-minute setup

I'm using Spring Boot 4 here but it's the same for 3.x.

Maven dependency for the JPA module:

<dependency>
    <groupId>com.turkraft.springfilter</groupId>
    <artifactId>jpa</artifactId>
    <version>4.0.5</version>
</dependency>

Your controller stays exactly as you'd write it for a non-tenant app:

@GetMapping("/invoices")
Page<Invoice> search(@Filter Specification<Invoice> spec, Pageable pageable) {
    return invoiceRepo.findAll(spec, pageable);
}

That's it. No tenantId parameter. No @AuthenticationPrincipal. No custom repository method. The controller is done.

Now the clever part. You create a service that wraps the raw filter:

@Service
public class TenantFilterService {

    @Autowired FilterParser parser;
    @Autowired FilterSpecificationConverter converter;
    @Autowired FilterBuilder fb;

    public <T> Specification<T> parseForTenant(String rawFilter, Long tenantId) {
        ParseContext ctx = new ParseContextImpl(null, userNode -> {
            FilterNode tenantNode = fb.field("tenantId")
                .equal(fb.input(tenantId))
                .get();
            return fb.and(tenantNode, userNode).get();
        });

        FilterNode finalNode = parser.parse(rawFilter, ctx);
        return converter.convert(finalNode);
    }
}

And your controller calls that instead of letting Spring auto-resolve the @Filter:

@GetMapping("/invoices")
Page<Invoice> search(@Filter String rawFilter, Pageable pageable,
                     @AuthenticationPrincipal User user) {
    Specification<Invoice> spec = tenantService
        .parseForTenant(rawFilter, user.getTenantId());
    return invoiceRepo.findAll(spec, pageable);
}

Couple of things to notice here:

The controller still receives the raw filter string. We just pass it through parseForTenant before converting it.
The tenant node gets AND-wrapped around whatever the user sends. So status : 'paid' becomes tenantId : 42 and status : 'paid'.
If the user sends an empty filter (or no filter param), the @Filter annotation with Optional or a default handles that, and the tenant clause still gets injected. The node mapper always fires.
Native queries, custom @Query methods, projections — they all pass through the same parseForTenant method. No more "oh but this endpoint uses a native query so it bypasses the tenant filter" hell.

What if someone tries to filter on `tenantId` directly?

Valid question. If a user crafts ?filter=tenantId : 99, the node mapper will turn it into tenantId : 42 and tenantId : 99 which always returns nothing. That's actually correct behavior for a tenant filter — user 42 should never see tenant 99's data, even by accident.

But you can also be explicit about it if you prefer. Override the field mapper in ParseContext to reject or rewrite any field named tenantId:

ParseContext ctx = new ParseContextImpl(field -> {
    if ("tenantId".equals(field)) {
        throw new IllegalArgumentException("nice try");
    }
    return field;
}, nodeMapper);

Or silently redirect it to the current tenant. Up to you.

One context, multiple backends

The same parseForTenant approach works if you switch to MongoDB. Instead of returning a Specification, you return a Query or Document. The ParseContext step is identical because it operates on the AST, not on JPA or Mongo specifics. The AST doesn't know or care what database you're using.

// Same ParseContext, different converter:
@Autowired FilterQueryConverter mongoConverter;

Query mongoQuery = mongoConverter.convert(finalNode);

Why this beats the alternatives

approach	why it fails
`@Where(clause = "tenant_id = ?")` in Hibernate	doesn't work for native queries, doesn't work for projections, doesn't work if you need per-request tenant switching
Base repository method	same problems plus someone always finds a way to call `entityManager.createNativeQuery()` directly
Spring Security ACL	overkill, requires separate ACL tables, massive performance hit for simple tenant filtering
Interceptor/filter on HTTP level	can't inject into the query language itself, can only add request params which might conflict

ParseContext works at the right level of abstraction. It sees the parsed query tree and rewrites it before any database-specific code runs. That's the whole trick.

Real talk: what you lose

Not much but worth mentioning. You can't just annotate your controller and have it work magically anymore — you need to call parseForTenant explicitly. It's one extra line per search endpoint. That's the trade.

Also, if you have endpoints that should NOT be tenant-filtered (admin dashboards, cross-tenant reports), you can either skip parseForTenant for those endpoints or pass a flag that tells the node mapper to stay out of the way.

The full code, no commentary

// TenantFilterService.java
@Service
public class TenantFilterService {

    @Autowired private FilterParser parser;
    @Autowired private FilterSpecificationConverter jpaConverter;
    @Autowired private FilterQueryConverter mongoConverter;
    @Autowired private FilterBuilder fb;

    public <T> Specification<T> parseJpa(String rawFilter, Long tenantId) {
        FilterNode node = wrapWithTenant(rawFilter, tenantId);
        return jpaConverter.convert(node);
    }

    public <T> Query parseMongo(String rawFilter, Long tenantId, Class<T> entityClass) {
        FilterNode node = wrapWithTenant(rawFilter, tenantId);
        return mongoConverter.convert(node, entityClass);
    }

    private FilterNode wrapWithTenant(String rawFilter, Long tenantId) {
        ParseContext ctx = new ParseContextImpl(null, userNode -> {
            FilterNode tenantNode = fb.field("tenantId")
                .equal(fb.input(tenantId))
                .get();
            return fb.and(tenantNode, userNode).get();
        });
        return parser.parse(rawFilter, ctx);
    }
}

That's the whole thing. Twenty-ish lines that save you from touching every controller every time a tenant requirement changes.

I first wrote about this library when it was at v1 and all it did was parse filter strings for JPA entities. Feels like a lifetime ago. The ParseContext stuff came later and it's by far the most underrated feature — it turns the library from "handy query parser" into "query interception framework" without anyone having to learn a new DSL or wire up Spring Security magic.

Repo's at turkraft/springfilter if you want to dig in. PRs welcome, especially if you've got a weird tenant setup I haven't thought of yet.

DEV Community: torshid

One Filter Language, Every Database: Type-Safe Filtering from React to Prisma and Drizzle

The filter expression format

The frontend: react-querybuilder

Backend path A: Prisma

Backend path B: Drizzle

Prisma vs Drizzle: which adapter to choose?

Security: prevention, not detection

Performance: parse once, query once

The complete pipeline, from click to query

The FilterKit ecosystem

When not to use this

Fullstack Dynamic Filtering: React Query Builder to Spring Boot in One Pipeline

The app we're building

Step 1: The filter query string format

Step 2: The Spring Boot backend

Step 3: The React frontend: react-querybuilder

Step 4: TanStack Table with column header filters

Step 5: What if you need security? Multi-tenancy?

Step 6: MongoDB instead of JPA? Same frontend, different converter

Step 7: Bonus: automatic Swagger docs

Step 8: The complete architecture diagram

Wait, but this sends filter queries as URL params. Isn't that a security problem?

Real talk: when does this NOT work well?

The code, all together

From Querydsl to Spring Filter: One Syntax, Three Backends

Side-by-side: basic filtering

What Querydsl does that Spring Filter doesn't

What Spring Filter does that Querydsl doesn't

Migration strategy: entity by entity

The query syntax conversion cheat sheet

When NOT to migrate

Type-Safe Query Builders for JPA: No Strings, No Typos

Before: the string soup

After: the generated builder

What fields get generated?

Nested relations work out of the box

What about compile time?

The limitation: you're locked to the entity structure

Real world: before and after

Summary

Multi-Tenant Query Filtering That Doesn't Touch Your Controllers

The 20-minute setup

What if someone tries to filter on tenantId directly?

One context, multiple backends

Why this beats the alternatives

Real talk: what you lose

The full code, no commentary

What if someone tries to filter on `tenantId` directly?