# Query

**Kind:** Function

**Source:** [`packages/common/decorators/http/route-params.decorator.ts`](https://github.com/nestjs/nest/blob/master/packages/common/decorators/http/route-params.decorator.ts#L408)

**Part of:** [Common](subsystem-packages-common)

Route handler parameter decorator. Extracts the `query`
property from the `req` object and populates the decorated
parameter with the value of `query`. May also apply pipes to the bound
query parameter.

For example:
```typescript
async find(@Query('user') user: string)
```

`@Query()` is a route-handler parameter decorator that reads the `query` property from the incoming request object. It binds either the full query object or a named query value to the decorated parameter, and can apply pipes during parameter binding.

## Signature

```ts
function Query(property: string | (Type<PipeTransform> | PipeTransform), pipes: (Type<PipeTransform> | PipeTransform)[]): ParameterDecorator
```

## Parameters

| Name | Type |
|---|---|
| `property` | `string | (Type<PipeTransform> | PipeTransform)` |
| `pipes` | `(Type<PipeTransform> | PipeTransform)[]` |

**Returns:** `ParameterDecorator`

## Diagram

```mermaid
graph LR
  Request[Incoming request] --> QueryObject[req.query]
  QueryObject --> Decorator["@Query()"]
  Decorator --> HandlerParam[Route handler parameter]
  Pipes[Pipes] --> Decorator
```

## Usage

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

@Controller('users')
export class UsersController {
  @Get()
  find(@Query('user') user: string) {
    return { user };
  }

  @Get('search')
  search(@Query() query: Record<string, string>) {
    return query;
  }
}
```

## AI Coding Instructions

- Use `@Query('key')` when a handler needs a single query parameter, and `@Query()` when it needs the full query object.
- Keep query parameter names aligned with the request contract, such as `?user=value` for `@Query('user')`.
- Apply pipes through the decorator when query values need validation or transformation.
- Treat query values as request input and account for missing, repeated, or non-string values where applicable.