Skip to main content
Query parameters allow you to customize API requests to fetch exactly the data you need. The NestJS CRUD framework supports a rich set of query parameters for filtering, sorting, pagination, and more.

​
Overview

All query parameters are parsed from the URL query string and can be combined to create powerful, flexible API requests.

​
Available Parameters

The framework supports the following query parameter types:
ParameterAliasesDescriptionExample
fieldsselectSelect specific fields to return?fields=id,name,email
filter-Filter results by conditions`?filter=nameeqJohn`
or-Filter with OR conditions`?or=agegt18`
join-Join relations?join=profile
sort-Sort results?sort=name,ASC
limitper_pageLimit number of results?limit=10
offset-Skip number of results?offset=20
page-Page number (alternative to offset)?page=2
cache-Cache results (in seconds)?cache=300
ssearchAdvanced JSON search?s={"name":"John"}
Parameter names can be customized in the framework configuration, but the default names are shown above.

​
Delimiters

The framework uses two types of delimiters:
  • Field delimiter (||): Separates parts of a filter, join, or sort parameter
  • String delimiter (,): Separates multiple values within a parameter

​
Examples

# Filter delimiter
/users?filter=name||eq||John

# String delimiter for multiple fields
/users?fields=id,name,email

# String delimiter for multiple values in filter
/users?filter=status||in||active,pending

​
Basic Usage

​
Simple Request

Fetch users with only specific fields: 
GET /users?fields=id,name,email

​
Multiple Parameters

Combine multiple query parameters: 
GET /users?fields=id,name&filter=isActive||eq||true&sort=name,ASC&limit=10

​
Array Parameters

Some parameters accept multiple values using arrays: 
# Multiple filters
GET /users?filter=name||eq||John&filter=age||gt||18

# Multiple joins
GET /users?join=profile&join=posts

# Multiple sorts
GET /users?sort=name,ASC&sort=createdAt,DESC

​
Value Parsing

The framework automatically parses values to the appropriate type:

​
Numbers

# Parsed as number: 42
/users?filter=age||eq||42

​
Booleans

# Parsed as boolean: true
/users?filter=isActive||eq||true

# Parsed as boolean: false
/users?filter=isDeleted||eq||false

​
Dates

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

​
Strings

# Remains as string
/users?filter=name||eq||John

​
Arrays

# Parsed as array: [1, 2, 3]
/users?filter=id||in||1,2,3
Large numbers that exceed JavaScript’s Number.MAX_SAFE_INTEGER are kept as strings to prevent data loss.

​
URL Encoding

When using special characters in query parameters, make sure to properly URL-encode them: 
// JavaScript example
const queryString = new URLSearchParams({
  filter: 'name||eq||John Doe',
  fields: 'id,name,email'
}).toString();

// Result: filter=name%7C%7Ceq%7C%7CJohn+Doe&fields=id%2Cname%2Cemail

​
Advanced Search Parameter

The s parameter accepts JSON for complex queries: 
# JSON search
GET /users?s={"name":"John","age":{"$gte":18}}

# With OR conditions
GET /users?s={"$or":[{"name":"John"},{"name":"Jane"}]}
When using the s (search) parameter, the filter and or parameters are ignored.

​
Best Practices

  1. Use field selection: Always request only the fields you need to reduce payload size
  2. Implement pagination: Use limit and offset or page for large datasets
  3. Encode URLs: Always URL-encode query parameters when using special characters
  4. Combine parameters: Chain multiple parameters for precise data fetching
  5. Use appropriate filters: Choose the right comparison operator for your use case

​
Example Requests

​
Get Active Users with Profiles

GET /users?filter=isActive||eq||true&join=profile&fields=id,name,email

​
Search Users by Name or Email

GET /users?or=name||cont||john&or=email||cont||john

​
Paginated Results with Sorting

GET /users?limit=20&page=1&sort=createdAt,DESC

​
Complex Query with Multiple Conditions

GET /users?filter=age||gte||18&filter=isActive||eq||true&join=profile&join=posts&fields=id,name&limit=10&sort=name,ASC

​
Next Steps

Filtering

Learn about all available filter operators

Sorting

Understand sorting and ordering results

Pagination

Implement pagination in your requests

Relations

Work with related entities using joins

Build docs developers (and LLMs) love

Get started for freeTalk to us