How to Use @Query Decorator in NestJS for Query Parameters

In NestJS, use the @Query decorator inside a controller method to access query parameters from the URL. You can get all query parameters as an object or extract specific ones by naming them inside @Query('paramName').

Syntax

The @Query decorator is used in controller methods to extract query parameters from the request URL.

• @Query() without arguments returns all query parameters as an object.
• @Query('paramName') extracts the value of a specific query parameter named paramName.

typescript

@Get('search')
search(@Query() query: any) {
  // query contains all query parameters as an object
}

@Get('filter')
filter(@Query('type') type: string) {
  // type contains the value of the 'type' query parameter
}

Example

This example shows a NestJS controller with a route that uses @Query to get query parameters from the URL. It returns the received query parameters as JSON.

typescript

import { Controller, Get, Query } from '@nestjs/common';

@Controller('products')
export class ProductsController {
  @Get('search')
  search(@Query() query: Record<string, string>) {
    return {
      message: 'Received query parameters',
      queryParams: query,
    };
  }

  @Get('filter')
  filter(@Query('category') category: string) {
    return {
      message: `Filtering products by category: ${category}`,
    };
  }
}

Output

{
  "message": "Received query parameters",
  "queryParams": {
    "name": "book",
    "price": "20"
  }
}

// or for /products/filter?category=electronics
{
  "message": "Filtering products by category: electronics"
}

Common Pitfalls

Common mistakes when using @Query include:

• Forgetting to specify the parameter name when you want a single query value, which returns the whole object instead.
• Assuming query parameters are automatically typed; they are always strings unless you convert them.
• Not handling missing query parameters, which can cause undefined values.

typescript

/* Wrong: expecting a single query param but missing the name */
@Get('wrong')
wrong(@Query() category: any) {
  // category will be an object, not a string
}

/* Right: specify the query param name */
@Get('right')
right(@Query('category') category: string) {
  // category is the string value of the 'category' query param
}

Quick Reference

• @Query() - gets all query parameters as an object.
• @Query('paramName') - gets a single query parameter value.
• Query parameters are always strings; convert if needed.
• Use optional chaining or default values to handle missing parameters.

Key Takeaways

Use @Query() to get all query parameters as an object in NestJS controllers.

Use @Query('paramName') to get a specific query parameter value by name.

Query parameters are strings by default; convert them if you need other types.

Always handle cases where query parameters might be missing or undefined.

Specifying the parameter name in @Query is essential to get single values correctly.