Filtering

Filtering allows you to retrieve only the data that matches specific conditions. The NestJS CRUD framework provides a comprehensive set of operators for building simple to complex filters.

Basic Syntax

Filters use the following format:

filter={field}||{operator}||{value}

field: The name of the field to filter
operator: The comparison operator to use
value: The value to compare against (optional for some operators)

Example

GET /users?filter=name||eq||John

This retrieves all users where the name equals “John”.

Comparison Operators

The framework supports both modern ($ prefixed) and deprecated operators.

Equality Operators

Operator	Modern	Description	Example
`eq`	`$eq`	Equals	`filter=name		$eq		John`
`ne`	`$ne`	Not equals	`filter=status		$ne		inactive`

# Find users named John
GET /users?filter=name||$eq||John

# Find users not named John
GET /users?filter=name||$ne||John

Comparison Operators

Operator	Modern	Description	Example
`gt`	`$gt`	Greater than	`filter=age	$gt	18`
`gte`	`$gte`	Greater than or equal	`filter=age	$gte	18`
`lt`	`$lt`	Less than	`filter=price	$lt	100`
`lte`	`$lte`	Less than or equal	`filter=price	$lte	100`

# Find users older than 18
GET /users?filter=age||$gt||18

# Find products under $100
GET /products?filter=price||$lte||100

String Operators

Operator	Modern	Description	Example
`starts`	`$starts`	Starts with	`filter=name	$starts	Jo`
`ends`	`$ends`	Ends with	`filter=email	$ends	@gmail.com`
`cont`	`$cont`	Contains	`filter=description	$cont	keyword`
`excl`	`$excl`	Excludes	`filter=name	$excl	test`

# Find users whose name starts with "Jo"
GET /users?filter=name||$starts||Jo

# Find products containing "laptop" in description
GET /products?filter=description||$cont||laptop

# Find emails ending with @gmail.com
GET /users?filter=email||$ends||@gmail.com

Case-Insensitive String Operators

All string operators have case-insensitive variants with the L suffix:

Operator	Description	Example
`$eqL`	Equals (case-insensitive)	`filter=name	$eqL	john`
`$neL`	Not equals (case-insensitive)	`filter=name	$neL	john`
`$startsL`	Starts with (case-insensitive)	`filter=name	$startsL	jo`
`$endsL`	Ends with (case-insensitive)	`filter=email	$endsL	@gmail.com`
`$contL`	Contains (case-insensitive)	`filter=description	$contL	laptop`
`$exclL`	Excludes (case-insensitive)	`filter=name	$exclL	test`

# Find users named "john" (case-insensitive)
GET /users?filter=name||$eqL||john
# Matches: "John", "JOHN", "john", "JoHn"

# Find products containing "LAPTOP" (case-insensitive)
GET /products?filter=description||$contL||LAPTOP
# Matches: "laptop", "Laptop", "LAPTOP"

Use case-insensitive operators ($eqL, $contL, etc.) when you want to match strings regardless of case.

Array Operators

Operator	Modern	Description	Example
`in`	`$in`	In array	`filter=status	$in	active,pending`
`notin`	`$notin`	Not in array	`filter=role	$notin	guest,banned`
`between`	`$between`	Between values	`filter=age	$between	18,65`

# Find users with status active or pending
GET /users?filter=status||$in||active,pending

# Find users aged between 18 and 65
GET /users?filter=age||$between||18,65

# Find users not in guest or banned roles
GET /users?filter=role||$notin||guest,banned

Case-Insensitive Array Operators

Operator	Description	Example
`$inL`	In array (case-insensitive)	`filter=status		$inL		active,pending`
`$notinL`	Not in array (case-insensitive)	`filter=role		$notinL		guest,banned`

# Find users with status "active" or "pending" (case-insensitive)
GET /users?filter=status||$inL||active,PENDING
# Matches: "Active", "PENDING", "active", "pending"

Null Operators

Operator	Modern	Description	Example
`isnull`	`$isnull`	Is null	`filter=deletedAt		$isnull`
`notnull`	`$notnull`	Is not null	`filter=email		$notnull`

# Find users that have not been deleted
GET /users?filter=deletedAt||$isnull

# Find users with email addresses
GET /users?filter=email||$notnull

Null operators do not require a value parameter. The syntax is: filter={field}||{operator}

Multiple Filters (AND)

You can apply multiple filters to create AND conditions:

# Find active users older than 18
GET /users?filter=isActive||eq||true&filter=age||gt||18

All filter conditions must be satisfied (AND logic).

OR Conditions

Use the or parameter for OR logic:

# Find users named John OR Jane
GET /users?or=name||eq||John&or=name||eq||Jane

Combining AND and OR

You can combine both filter (AND) and or parameters:

# Find active users named John OR Jane
GET /users?filter=isActive||eq||true&or=name||eq||John&or=name||eq||Jane

This translates to: isActive = true AND (name = 'John' OR name = 'Jane')

Advanced Search

For complex queries, use the s (search) parameter with JSON:

Simple Search

GET /users?s={"name":"John"}

With Operators

GET /users?s={"age":{"$gte":18}}

Complex OR Conditions

GET /users?s={"$or":[{"name":"John"},{"email":{"$ends":"@gmail.com"}}]}

Nested AND Conditions

GET /users?s={"name":"John","age":{"$gte":18},"isActive":true}

When using the s (search) parameter, any filter and or parameters are ignored.

Filtering Nested Fields

You can filter by nested object fields using dot notation:

# Filter by nested profile field
GET /users?filter=profile.city||eq||New York

# Filter by nested relation field
GET /posts?filter=author.name||eq||John

Type Conversion

Values are automatically parsed to the correct type:

# Number
/users?filter=age||eq||25  # value is number 25

# Boolean
/users?filter=isActive||eq||true  # value is boolean true

# Date
/users?filter=createdAt||gt||2024-01-01T00:00:00.000Z  # value is Date object

# String
/users?filter=name||eq||John  # value is string "John"

# Array
/users?filter=id||in||1,2,3  # value is array [1, 2, 3]

Practical Examples

E-commerce Filters

# Find products in a price range
GET /products?filter=price||gte||10&filter=price||lte||100

# Find products by category and in stock
GET /products?filter=category||eq||electronics&filter=stock||gt||0

# Find products with specific tags
GET /products?filter=tags||in||sale,featured,new

User Management

# Find active users created this year
GET /users?filter=isActive||eq||true&filter=createdAt||gte||2024-01-01

# Find users by role
GET /users?filter=role||in||admin,moderator

# Find unverified users
GET /users?filter=emailVerified||eq||false

Content Management

# Find published posts containing keyword
GET /posts?filter=status||eq||published&filter=title||cont||tutorial

# Find draft posts by author
GET /posts?filter=status||eq||draft&filter=authorId||eq||123

# Find posts without comments
GET /posts?filter=commentsCount||eq||0

Error Handling

Invalid filters will throw a RequestQueryException:

# Invalid operator
GET /users?filter=name||invalid||John
# Error: Invalid comparison operator

# Missing value for non-null operator
GET /users?filter=name||eq
# Error: Invalid filter value

# Invalid field format
GET /users?filter=||eq||John
# Error: Invalid field type in filter condition

Best Practices

Use modern operators: Prefer $eq, $gt, etc. over deprecated operators
Use case-insensitive operators: Use $eqL, $contL for user input to avoid case sensitivity issues
Validate user input: Always validate and sanitize filter values from user input
Index filtered fields: Add database indexes to fields commonly used in filters
Combine with pagination: Always use limit when filtering to prevent large result sets
Use appropriate operators: Choose the right operator for the data type (e.g., $between for ranges)

Next Steps

Sorting

Learn how to sort filtered results

Pagination

Paginate through filtered data

Relations

Filter related entities with joins

Query Parameters

Overview of all query parameters

Get Started

Core Concepts

Controllers

Services

Request Handling

Advanced

Frontend Usage

Basic Syntax

Example

Comparison Operators

Equality Operators

Comparison Operators

String Operators

Case-Insensitive String Operators

Array Operators

Case-Insensitive Array Operators

Null Operators

Multiple Filters (AND)

OR Conditions

Combining AND and OR

Advanced Search

Simple Search

With Operators

Complex OR Conditions

Nested AND Conditions

Filtering Nested Fields

Type Conversion

Practical Examples

E-commerce Filters

User Management

Content Management

Error Handling

Best Practices

Next Steps

Sorting

Pagination

Relations

Query Parameters

Build docs developers (and LLMs) love

Get Started

Core Concepts

Controllers

Services

Request Handling

Advanced

Frontend Usage

​Basic Syntax

​Example

​Comparison Operators

​Equality Operators

​Comparison Operators

​String Operators

​Case-Insensitive String Operators

​Array Operators

​Case-Insensitive Array Operators

​Null Operators

​Multiple Filters (AND)

​OR Conditions

​Combining AND and OR

​Advanced Search

​Simple Search

​With Operators

​Complex OR Conditions

​Nested AND Conditions

​Filtering Nested Fields

​Type Conversion

​Practical Examples

​E-commerce Filters

​User Management

​Content Management

​Error Handling

​Best Practices

​Next Steps

Sorting

Pagination

Relations

Query Parameters

Build docs developers (and LLMs) love

Basic Syntax

Example

Comparison Operators

Equality Operators

Comparison Operators

String Operators

Case-Insensitive String Operators

Array Operators

Case-Insensitive Array Operators

Null Operators

Multiple Filters (AND)

OR Conditions

Combining AND and OR

Advanced Search

Simple Search

With Operators

Complex OR Conditions

Nested AND Conditions

Filtering Nested Fields

Type Conversion

Practical Examples

E-commerce Filters

User Management

Content Management

Error Handling

Best Practices

Next Steps