Customizing the Query

execute() takes a fourth, optional argument: an options object with two hooks.

execute(source, query, rules, {
  transformPlan?: (plan: TypedQueryPlan) => TypedQueryPlan,
  customize?: (native: TNative) => void,
  customizeScope?: 'data' | 'count' | 'both',   // default 'both'
})

In 2.x the fourth argument was the callback itself. It is an object now, because there are two different hooks at two different altitudes.

The pipeline, and where each hook sits

The order is fixed. transformPlan is the last point at which the plan can change; customize runs after compilation, on the adapter's native context. Data and count derive from the same frozen plan, which is why the two queries always describe the same question.

transformPlan — adapter-agnostic

Use it for policy that belongs to your application and must hold whatever ORM is behind the source: tenant scoping expressed in plan terms, an internal default, a forced projection. It receives and returns a TypedQueryPlan.

await this.queryBuilderService.execute(source, query, rules, {
  // Adapter-agnostic hook: tenant, soft delete, internal policy.
  // Return the plan, or a modified copy of it.
  transformPlan: (plan) => plan,
});

Note where it sits: parsing, authorisation and coercion have already happened, so the plan you receive is a valid one — and the terms you add to it are not re-validated before compilation. A hook that introduces a term the schema cannot serve is your bug, not a rejected request. Prefer reshaping what the plan already contains over inventing new terms.

customize — adapter-specific

Use it for capabilities outside the REST contract. It receives the native context, once per query in scope, and what "native" means depends on the adapter:

await this.queryBuilderService.execute(
  typeormSource(this.userRepository),
  query,
  rules,
  {
    customize: (qb) => {
      qb.andWhere('root.tenant_id = :tenant', { tenant });
    },
  }
);

await this.queryBuilderService.execute(
  prismaSource({ client: this.prisma, model: 'user', manifest }),
  query,
  rules,
  {
    customize: (native) => {
      native.args.where = { AND: [native.args.where ?? {}, { tenantId }] };
    },
  }
);

await this.queryBuilderService.execute(
  drizzleSource({ db, dialect: 'postgres', table, relations }),
  query,
  rules,
  {
    customize: (native) => {
      native.statement.where = {
        op: 'and',
        terms: [
          ...(native.statement.where ? [native.statement.where] : []),
          {
            op: 'compare',
            ref: { alias: native.statement.alias, column: 'tenantId' },
            comparator: '=',
            value: tenant,
          },
        ],
      };
    },
  }
);

The root alias under TypeORM is root.

customizeScope

The hook is invoked once per query, not once with both — and that is what makes the default actually work.

A single qb.andWhere(...) under 'both' therefore lands on both queries. A partial scope lets the count answer a different question than the data — so the library logs a structured warning when you choose one:

customize is scoped to a single query; data and count may diverge

When to use what

Native text search

search is a first-class parameter, not something to build in customize. Declare the searchable paths in the rules and send ?search=term:

export const userRules = defineQueryRules(USER_SCHEMAS, 'user', {
  // ...
  search: ['name', 'email', 'company.name'],
});

The targets are combined with OR, each compared through its folded column, against the term normalised by the same foldText. So no ILIKE is emitted, and the result does not depend on the server's collation. A target that crosses one many relation compiles to a correlated EXISTS, so the page keeps its size and total keeps counting root rows.

Two constraints are worth repeating here: a search path needs a foldedField or the application does not boot, and folding does not strip diacritics. See Endpoint whitelist rules.

search versus filter

Still reach for customize when search has to deviate from that: per-field weights, AND between term groups, a database-specific full-text index, or rules that depend on tenant, role or authentication context.

Inspecting the plan

There is no buildQuery() in v3 — nothing hands you a half-built SelectQueryBuilder, because the plan is the ORM-free artefact and each adapter compiles it. What exists is buildPlan, which stops right after transformPlan and the freeze:

const plan = this.queryBuilderService.buildPlan(query, rules, {
  transformPlan: (p) => p,
});

It is the seam to assert on in tests, or to inspect when a request does not produce the SQL you expected. To reach the ORM's own builder, use customize.