Query parameters in NestJS - Deep Dive

Overview - Query parameters

What is it?

Query parameters are parts of a URL that come after a question mark (?) and provide extra information to the server. In NestJS, they allow you to receive data sent by the client in the URL, like filters or options. This helps your server understand what specific data the client wants without changing the URL path. They are easy to access and use inside your controller methods.

Why it matters

Without query parameters, clients would have to send all data in the URL path or request body, making URLs long and inflexible. Query parameters let users customize requests simply, like searching or sorting data. This makes web apps more interactive and user-friendly. Without them, many common web features like search filters or pagination would be hard to implement.

Where it fits

Before learning query parameters, you should understand basic NestJS controllers and routing. After mastering query parameters, you can learn about request bodies, route parameters, and advanced validation techniques. Query parameters fit into the broader topic of handling HTTP requests in NestJS.

Mental Model

Core Idea

Query parameters are named pieces of information added to a URL that tell the server extra details about what the client wants.

Think of it like...

Query parameters are like notes you add to a letter's envelope to tell the post office special instructions, such as 'Fragile' or 'Deliver after 5 PM'. The letter (URL) stays the same, but the notes (query parameters) guide how it is handled.

URL structure:

  https://example.com/resource?key1=value1&key2=value2

  ┌───────────────┐ ┌───────────────┐
  │ Base URL      │ │ Query String  │
  │ (resource)    │ │ (key=value pairs)
  └───────────────┘ └───────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding URL and Query Basics

Concept: Learn what query parameters are and how they appear in URLs.

A URL can have a question mark (?) followed by key=value pairs separated by ampersands (&). These pairs are query parameters. For example, in https://site.com/items?color=red&size=large, 'color' and 'size' are keys with values 'red' and 'large'.

Result

You can identify query parameters in any URL and understand their role in sending extra data.

Knowing the URL structure helps you see how data can be passed without changing the main path.

2

Foundation

Accessing Query Parameters in NestJS

Concept: Learn how to get query parameters inside a NestJS controller method.

In NestJS, use the @Query() decorator in a controller method to access query parameters. For example: @Get('search') search(@Query() query) { return query; } If the client calls /search?term=book, the 'query' object will be { term: 'book' }.

Result

You can read any query parameters sent by the client inside your controller.

Using @Query() connects the URL's query string to your code, making dynamic responses possible.

3

Intermediate

Using DTOs to Validate Query Parameters

🤔Before reading on: do you think query parameters can be automatically checked for correct types in NestJS? Commit to yes or no.

Concept: Learn how to define a Data Transfer Object (DTO) class to validate and type query parameters.

Create a class with properties matching expected query keys and use class-validator decorators: import { IsString, IsOptional, IsNumberString } from 'class-validator'; export class SearchDto { @IsString() term: string; @IsOptional() @IsNumberString() page?: string; } Then use @Query() with the DTO: search(@Query() query: SearchDto) { return query; } NestJS will validate and convert query parameters automatically.

Result

Your app safely accepts only valid query parameters, reducing bugs and errors.

Validating query parameters early prevents bad data from causing problems deeper in your app.

4

Intermediate

Handling Optional and Default Query Parameters

🤔Before reading on: do you think query parameters must always be provided by the client? Commit to yes or no.

Concept: Learn how to make query parameters optional and provide default values.

In your DTO, use @IsOptional() to mark parameters as not required. In your controller, you can assign defaults: search(@Query() query: SearchDto) { const page = query.page ? Number(query.page) : 1; return { ...query, page }; } This way, if 'page' is missing, your code uses 1 as default.

Result

Your API works smoothly even if clients omit some query parameters.

Handling optional parameters improves user experience and prevents errors from missing data.

5

Intermediate

Accessing Single Query Parameter Directly

Concept: Learn how to get a specific query parameter without reading the whole object.

You can ask NestJS for a single query parameter by naming it in @Query(): search(@Query('term') term: string) { return term; } If the client calls /search?term=book, 'term' will be 'book'.

Result

You can quickly get just the data you need without extra code.

Direct access simplifies code when only one query parameter matters.

6

Advanced

Combining Query Parameters with Pipes

🤔Before reading on: do you think pipes can transform query parameters before your method uses them? Commit to yes or no.

Concept: Learn how to use NestJS pipes to transform or validate query parameters automatically.

Pipes are functions that run before your controller method. For example, use ParseIntPipe to convert a string to a number: import { ParseIntPipe } from '@nestjs/common'; search(@Query('page', ParseIntPipe) page: number) { return page; } If the client sends /search?page=2, 'page' is a number 2, not a string.

Result

Your controller receives clean, validated data without manual parsing.

Pipes help keep your code clean and safe by handling common transformations and checks.

7

Expert

Query Parameters in Complex Nested Routes

🤔Before reading on: do you think query parameters are shared across nested routes or isolated? Commit to your answer.

Concept: Understand how query parameters behave in nested controllers and how to manage them properly.

In NestJS, query parameters are global to the request URL, so nested routes receive the same query parameters. For example, if you have /users/:id/posts?sort=desc, both the users and posts controllers can access 'sort'. You can selectively pick or validate parameters in each controller. Be careful to avoid conflicts or assumptions about which parameters exist.

Result

You can design modular controllers that handle query parameters correctly in complex apps.

Knowing query parameters flow through nested routes prevents bugs and improves API design.

Under the Hood

When a client sends a request with query parameters, the HTTP server parses the URL and extracts the part after the question mark. NestJS uses its routing system to match the path and then provides the query parameters as a plain JavaScript object to the controller method via the @Query() decorator. If validation or transformation pipes are used, NestJS runs them before the method executes. This process happens synchronously during request handling.

Why designed this way?

NestJS follows the HTTP standard where query parameters are part of the URL. Providing a simple decorator like @Query() fits the framework's goal of clean, declarative code. Using DTOs and pipes leverages TypeScript and class-validator to improve safety and developer experience. This design balances flexibility, clarity, and performance.

Request flow:

Client Request URL
      ↓
HTTP Server parses URL
      ↓
NestJS Router matches path
      ↓
Extract query parameters object
      ↓
Apply validation/transformation pipes
      ↓
Inject query object into controller method
      ↓
Controller processes request and returns response

Myth Busters - 4 Common Misconceptions

Quick: Do you think query parameters are case-sensitive? Commit to yes or no.

Common Belief: Query parameters are case-insensitive, so 'Term' and 'term' are the same.

Reality: Query parameters are case-sensitive by standard, so 'Term' and 'term' are different keys.

Why it matters: Assuming case-insensitivity can cause bugs where parameters are missed or ignored, leading to unexpected behavior.

Quick: Do you think query parameters can contain complex objects or arrays directly? Commit to yes or no.

Common Belief: You can send nested objects or arrays directly as query parameters without special handling.

Reality: Query parameters are simple strings; to send complex data, you must serialize it (e.g., JSON string) or use repeated keys with conventions.

Why it matters: Misunderstanding this leads to broken data parsing and errors when expecting complex structures.

Quick: Do you think query parameters are always safe and cannot cause security issues? Commit to yes or no.

Common Belief: Query parameters are harmless and don't need validation or sanitization.

Reality: Query parameters come from the client and can contain malicious input; they must be validated and sanitized to prevent attacks like injection.

Why it matters: Ignoring validation can open security holes and cause crashes or data leaks.

Quick: Do you think query parameters are part of the request body? Commit to yes or no.

Common Belief: Query parameters are sent inside the request body like form data or JSON.

Reality: Query parameters are part of the URL, not the body, and are handled differently by servers and frameworks.

Why it matters: Confusing this can cause wrong code that tries to read query data from the body, leading to bugs.

Expert Zone

1

Query parameters are always strings at first; understanding when and how to convert them properly avoids subtle bugs.

2

Using validation pipes with DTOs can combine type safety and runtime checks, but improper ordering or missing decorators can cause silent failures.

3

In complex apps, query parameters can collide or overlap in nested routes; designing clear parameter namespaces or prefixes helps maintain clarity.

When NOT to use

Query parameters are not suitable for sending large amounts of data or sensitive information, as URLs have length limits and are logged in many places. Use request bodies (POST/PUT) for large or private data instead.

Production Patterns

In real-world NestJS apps, query parameters are used for filtering, sorting, pagination, and feature toggles. Developers often combine DTO validation with custom pipes for sanitization. They also document query parameters clearly in API specs and use global validation pipes to enforce rules consistently.

Connections

HTTP Request Lifecycle

Query parameters are part of the HTTP request URL and are processed early in the request lifecycle.

Understanding query parameters helps grasp how HTTP requests carry data and how servers parse and route them.

Data Validation and Transformation

Query parameters often require validation and transformation before use, linking them closely to data validation concepts.

Mastering query parameter validation improves overall data handling and security in web applications.

Database Query Filtering

Query parameters commonly map to database filters, enabling dynamic queries based on client input.

Knowing how query parameters translate to database queries helps design efficient and secure APIs.

Common Pitfalls

#1 Assuming query parameters are always present and not checking for undefined.

Wrong approach:

search(@Query() query) {
return query.page.toUpperCase();
}

Correct approach:

search(@Query() query) {
if (query.page) {
return query.page.toUpperCase();
}
return 'default';
}

Root cause:

Not handling optional parameters leads to runtime errors when accessing properties of undefined.

#2 Not validating query parameters, trusting client input blindly.

Wrong approach:

search(@Query() query: any) {
return `Page number is ${query.page}`;
}

Correct approach:

search(@Query() query: SearchDto) {
return `Page number is ${query.page}`;
}

Root cause:

Skipping validation allows invalid or malicious data to enter the system.

#3 Trying to read query parameters from the request body.

Wrong approach:

search(@Body() body) {
return body.page;
}

Correct approach:

search(@Query('page') page: string) {
return page;
}

Root cause:

Confusing query parameters with body data causes incorrect data access.

Key Takeaways

Query parameters are key=value pairs in URLs that let clients send extra info to servers without changing the path.

In NestJS, the @Query() decorator accesses these parameters easily inside controller methods.

Validating and transforming query parameters with DTOs and pipes improves safety and code clarity.

Query parameters are always strings initially and may be optional, so handle defaults and types carefully.

Misunderstanding query parameters can cause bugs, security issues, or broken APIs, so learn their behavior deeply.

Practice

1. What is the purpose of using @Query() decorator in a NestJS controller?

easy

A. To inject a service into the controller

B. To define a new route path

C. To handle POST request bodies

D. To access query parameters sent in the URL

Solution

1. Step 1: Understand the role of @Query()

   The @Query() decorator extracts query parameters from the URL in a GET request.

2. Step 2: Compare with other decorators

   Other decorators like @Body() handle POST bodies, and @Param() handles route params, so they don't fit here.

3. Final Answer:

   To access query parameters sent in the URL -> Option D

4. Quick Check:

   @Query() reads URL queries = A [OK]

Hint: Remember: @Query() reads URL query strings [OK]

Common Mistakes:

• Confusing @Query() with @Body()
• Thinking @Query() defines routes
• Using @Query() to inject services

2. Which of the following is the correct syntax to get a query parameter named page in a NestJS controller method?

easy

A. async getItems(@Param('page') page: number) {}

B. async getItems(@Body('page') page: number) {}

C. async getItems(@Query('page') page: number) {}

D. async getItems(@Query.page page: number) {}

Solution

1. Step 1: Identify correct decorator usage

   To get a specific query parameter, use @Query('paramName') syntax.

2. Step 2: Check syntax correctness

   async getItems(@Query('page') page: number) {} uses @Query('page') correctly. Options A and C use wrong decorators, and D has invalid syntax.

3. Final Answer:

   async getItems(@Query('page') page: number) {} -> Option C

4. Quick Check:

   Use @Query('param') for query params = B [OK]

Hint: Use @Query('name') to get specific query param [OK]

Common Mistakes:

• Using @Param() instead of @Query()
• Trying to access query param as @Query.page
• Using @Body() for query parameters

3. Given this NestJS controller method:

async find(@Query() query) {
  return query.page + '-' + query.limit;
}

What will be the output if the URL is /items?page=2&limit=5?

medium

A. "2-5"

B. "page-limit"

C. "undefined-undefined"

D. Runtime error

Solution

1. Step 1: Understand @Query() behavior

   The @Query() decorator without arguments returns an object with all query parameters as strings.

2. Step 2: Check the returned string concatenation

   With URL ?page=2&limit=5, query.page is "2" and query.limit is "5". Concatenation returns "2-5".

3. Final Answer:

   "2-5" -> Option A

4. Quick Check:

   Query object has keys = "2-5" [OK]

Hint: Without param name, @Query() gets all query params as object [OK]

Common Mistakes:

• Expecting numbers instead of strings from query params
• Assuming @Query() returns undefined
• Thinking it causes runtime error

4. What is wrong with this NestJS controller method to get a query parameter search?:

async search(@Query(search) searchTerm: string) {
  return searchTerm;
}

medium

A. The method must be synchronous, not async

B. The @Query decorator argument should be a string: @Query('search')

C. The parameter name cannot be searchTerm

D. The method should use @Param('search') instead

Solution

1. Step 1: Check @Query decorator syntax

   The argument to @Query() must be a string literal naming the query parameter, e.g., @Query('search').

2. Step 2: Identify the error in the code

   The code uses @Query(search) without quotes, which is invalid syntax and causes an error.

3. Final Answer:

   The @Query decorator argument should be a string: @Query('search') -> Option B

4. Quick Check:

   Decorator argument must be string literal = D [OK]

Hint: Always quote query param name in @Query('name') [OK]

Common Mistakes:

• Forgetting quotes around query param name
• Using @Param() for query params
• Thinking async keyword is disallowed

5. You want to create a NestJS GET endpoint that accepts optional query parameters sort and filter. If filter is missing, it should default to "all". Which code snippet correctly implements this behavior?

hard

A. async getItems(@Query() query) {
const filter = query.filter || 'all';
return { sort: query.sort, filter };
}

B. async getItems(@Query('sort') sort: string, @Query('filter') filter: string = 'all') {}

C. async getItems(@Query('sort') sort: string, @Query('filter') filter?: string) {
if (!filter) filter = 'all';
return { sort, filter };
}

D. async getItems(@Query('sort') sort: string, @Query('filter') filter: string) {
filter = filter ?? 'all';
return { sort, filter };
}

Solution

1. Step 1: Understand default value handling for query params

   Query parameters come as strings or undefined. Default values should be set inside the method, not in parameter defaults.

2. Step 2: Analyze each option

   async getItems(@Query('sort') sort: string, @Query('filter') filter: string = 'all') {} tries to set default in parameter, which doesn't work well with @Query(). async getItems(@Query() query) { const filter = query.filter || 'all'; return { sort: query.sort, filter }; } extracts all query params and sets default for filter inside method correctly. async getItems(@Query('sort') sort: string, @Query('filter') filter?: string) { if (!filter) filter = 'all'; return { sort, filter }; } tries to assign to parameter which is readonly. async getItems(@Query('sort') sort: string, @Query('filter') filter: string) { filter = filter ?? 'all'; return { sort, filter }; } assigns default after parameter, but parameter is readonly, so it causes error.

3. Final Answer:

   async getItems(@Query() query) { const filter = query.filter || 'all'; return { sort: query.sort, filter }; } -> Option A

4. Quick Check:

   Set defaults inside method body = A [OK]

Hint: Set default query values inside method, not in parameters [OK]

Common Mistakes:

• Trying to assign default values in parameter list with @Query()
• Mutating readonly parameters
• Not handling missing query params properly