Skip to main content

​
Introduction

The RequestQueryBuilder class provides a fluent API for constructing complex query strings for NestJS CRUD operations. It supports filtering, sorting, pagination, field selection, and relation joining with a chainable, type-safe interface.

​
Installation

npm install @nestjsx/crud-request

​
Basic Usage

import { RequestQueryBuilder } from '@nestjsx/crud-request';

const queryString = RequestQueryBuilder.create()
  .select(['id', 'name', 'email'])
  .setFilter({ field: 'status', operator: '$eq', value: 'active' })
  .sortBy({ field: 'createdAt', order: 'DESC' })
  .setLimit(10)
  .query();

// Result: fields=id,name,email&filter=status||$eq||active&sort=createdAt,DESC&limit=10

​
Creating an Instance

There are two ways to create a RequestQueryBuilder instance:

​
Static Factory Method

const qb = RequestQueryBuilder.create();

​
Constructor

const qb = new RequestQueryBuilder();

​
Create from Parameters

You can initialize a query builder with all parameters at once: 
const qb = RequestQueryBuilder.create({
  fields: ['id', 'name', 'email'],
  filter: { field: 'status', operator: '$eq', value: 'active' },
  sort: { field: 'createdAt', order: 'DESC' },
  limit: 10,
  page: 1
});

​
Key Features

Field Selection

Choose which fields to return in the response

Filtering

Filter records with various comparison operators

Sorting

Sort results by one or multiple fields

Pagination

Paginate results with limit/offset or page-based pagination

Relations

Join and select related entities

Search

Complex search with AND/OR conditions

​
Configuration

You can configure global options for all RequestQueryBuilder instances: 
RequestQueryBuilder.setOptions({
  delim: '||',        // Delimiter for query parts
  delimStr: ',',      // Delimiter for array values
  paramNamesMap: {
    fields: ['fields', 'select'],
    filter: 'filter',
    sort: 'sort',
    limit: ['limit', 'per_page'],
    offset: 'offset',
    page: 'page',
    cache: 'cache',
    includeDeleted: 'include_deleted'
  }
});
​
delim
string
default:"||"
Delimiter used to separate parts of a query parameter (e.g., field||operator||value)
​
delimStr
string
default:","
Delimiter used to separate array values (e.g., field1,field2,field3)
​
paramNamesMap
object
Map of parameter names used in the query string. Each key can be a string or array of strings.

​
Query Generation

After building your query, generate the query string: 
const queryString = qb.query();           // URL-encoded
const rawQuery = qb.query(false);         // Not encoded
When search() is used, it takes precedence over filter and or conditions. The filter and or parameters will be ignored in the final query string.

​
Advanced Examples

​
Complex Filtering with OR Conditions

const qb = RequestQueryBuilder.create()
  .setFilter([{ field: 'status', operator: '$eq', value: 'active' }])
  .setOr([
    { field: 'priority', operator: '$eq', value: 'high' },
    { field: 'priority', operator: '$eq', value: 'urgent' }
  ])
  .query();

​
Joining Relations

const qb = RequestQueryBuilder.create()
  .setJoin({ field: 'profile' })
  .setJoin({ field: 'posts', select: ['id', 'title', 'createdAt'] })
  .query();

​
Search with Complex Conditions

const qb = RequestQueryBuilder.create()
  .search({
    name: { $cont: 'John' },
    $or: [
      { age: { $gte: 18 } },
      { verified: true }
    ]
  })
  .query();

​
Properties

​
queryObject
object
The internal object representation of the query before it’s converted to a string
​
queryString
string
The generated query string (available after calling query())
​
options
RequestQueryBuilderOptions
The current configuration options for the builder

​
Next Steps

Methods Reference

Explore all available methods and their signatures

Operators Reference

Learn about all query operators and how to use them

Build docs developers (and LLMs) love

Get started for freeTalk to us