Skip to main content

Filtering

Every property decorated with @FilterableField becomes an optional equality query parameter. Multiple parameters are combined with AND.

todo-item.dto.ts
import { FilterableField, IDField } from '@ptc-org/nestjs-query-rest'

export class TodoItemDTO {
  @IDField()
  id!: number

  @FilterableField()
  title!: string

  @FilterableField()
  completed!: boolean
}
GET /todo-items?title=Write%20docs&completed=false

This produces the service filter equivalent to:

{
  title: { eq: 'Write docs' },
  completed: { eq: false }
}

The field type controls query-string conversion and validation. For example, completed=false becomes the boolean false, and a numeric field is converted to a number.

Required and filter-only fields​

export class TodoItemDTO {
  @FilterableField({ filterRequired: true })
  tenantId!: string

  @FilterableField({ filterOnly: true })
  ownerId!: string
}

tenantId must be supplied to endpoints that use this generated filter. ownerId can be used in a query but is excluded from response serialization.

Defaults and disabling filters​

Set a filter on @QueryOptions or the endpoint definition to scope every collection request:

@QueryOptions({ defaultFilter: { archived: { eq: false } } })
export class TodoItemDTO {}
{
  DTOClass: TodoItemDTO,
  EntityClass: TodoItemEntity,
  disableFilter: true
}

disableFilter removes generated filter query parameters from the read collection endpoint. The CSV export endpoint still exposes its filter parameters, and authorization filters are still applied by the server.

Search terms​

Set enableSearch: true to expose a free-form query parameter. The core query service does not interpret this value automatically; use a BeforeQueryMany hook or a custom service to translate it into a data-source filter.

GET /todo-items?query=documentation

See hooks for a complete query hook example.