> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nestjsx/crud/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Build your first CRUD API with NestJS CRUD in minutes

Get started with NestJS CRUD by building a complete CRUD API for managing users. This guide will walk you through creating an entity, service, controller, and testing your API.

## Prerequisites

Make sure you have completed the [installation](/installation) steps and have a NestJS project set up with TypeORM and NestJS CRUD installed.

## Create your first CRUD API

<Steps>
  <Step title="Create an entity">
    Create a TypeORM entity to define your data model. Add validation decorators from `class-validator`:

    ```typescript User.entity.ts theme={null}
    import { Entity, Column, PrimaryGeneratedColumn } from 'typeorm';
    import { IsString, IsEmail, IsOptional, MaxLength } from 'class-validator';

    @Entity('users')
    export class User {
      @PrimaryGeneratedColumn()
      id: number;

      @IsString()
      @MaxLength(100)
      @Column({ type: 'varchar', length: 100 })
      name: string;

      @IsEmail()
      @Column({ type: 'varchar', unique: true })
      email: string;

      @IsOptional()
      @IsString()
      @Column({ type: 'text', nullable: true })
      bio?: string;
    }
    ```
  </Step>

  <Step title="Create a service">
    Create a service that extends `TypeOrmCrudService` to handle database operations:

    ```typescript users.service.ts theme={null}
    import { Injectable } from '@nestjs/common';
    import { InjectRepository } from '@nestjs/typeorm';
    import { TypeOrmCrudService } from '@nestjsx/crud-typeorm';
    import { Repository } from 'typeorm';
    import { User } from './user.entity';

    @Injectable()
    export class UsersService extends TypeOrmCrudService<User> {
      constructor(
        @InjectRepository(User)
        repository: Repository<User>,
      ) {
        super(repository);
      }
    }
    ```

    That's it! The `TypeOrmCrudService` provides all CRUD methods out of the box.
  </Step>

  <Step title="Create a controller">
    Create a controller with the `@Crud()` decorator to automatically generate REST endpoints:

    ```typescript users.controller.ts theme={null}
    import { Controller } from '@nestjs/common';
    import { Crud } from '@nestjsx/crud';
    import { User } from './user.entity';
    import { UsersService } from './users.service';

    @Crud({
      model: {
        type: User,
      },
      query: {
        alwaysPaginate: true,
      },
    })
    @Controller('users')
    export class UsersController {
      constructor(public service: UsersService) {}
    }
    ```

    The `@Crud()` decorator automatically creates these endpoints:

    * `GET /users` - Get all users
    * `GET /users/:id` - Get one user
    * `POST /users` - Create user
    * `POST /users/bulk` - Create multiple users
    * `PATCH /users/:id` - Update user
    * `PUT /users/:id` - Replace user
    * `DELETE /users/:id` - Delete user
  </Step>

  <Step title="Register the module">
    Register your entities and services in a NestJS module:

    ```typescript users.module.ts theme={null}
    import { Module } from '@nestjs/common';
    import { TypeOrmModule } from '@nestjs/typeorm';
    import { User } from './user.entity';
    import { UsersService } from './users.service';
    import { UsersController } from './users.controller';

    @Module({
      imports: [TypeOrmModule.forFeature([User])],
      controllers: [UsersController],
      providers: [UsersService],
    })
    export class UsersModule {}
    ```
  </Step>
</Steps>

## Test your API

Start your NestJS application and test the auto-generated endpoints:

<CodeGroup>
  ```bash Create a user theme={null}
  curl -X POST http://localhost:3000/users \
    -H "Content-Type: application/json" \
    -d '{
      "name": "John Doe",
      "email": "john@example.com",
      "bio": "Software developer"
    }'
  ```

  ```bash Get all users theme={null}
  curl http://localhost:3000/users
  ```

  ```bash Get one user theme={null}
  curl http://localhost:3000/users/1
  ```

  ```bash Update a user theme={null}
  curl -X PATCH http://localhost:3000/users/1 \
    -H "Content-Type: application/json" \
    -d '{"bio": "Senior software developer"}'
  ```

  ```bash Delete a user theme={null}
  curl -X DELETE http://localhost:3000/users/1
  ```
</CodeGroup>

## Advanced querying

NestJS CRUD provides powerful query capabilities out of the box. Try these advanced queries:

<CodeGroup>
  ```bash Filter by name theme={null}
  curl "http://localhost:3000/users?filter=name||eq||John%20Doe"
  ```

  ```bash Search with partial match theme={null}
  curl "http://localhost:3000/users?filter=name||cont||John"
  ```

  ```bash Pagination theme={null}
  curl "http://localhost:3000/users?page=1&limit=10"
  ```

  ```bash Sorting theme={null}
  curl "http://localhost:3000/users?sort=name,ASC"
  ```

  ```bash Select specific fields theme={null}
  curl "http://localhost:3000/users?fields=id,name,email"
  ```

  ```bash Multiple filters theme={null}
  curl "http://localhost:3000/users?filter=name||cont||John&filter=email||cont||example"
  ```
</CodeGroup>

## Filter operators

NestJS CRUD supports a wide range of filter operators:

| Operator   | Description           | Example        |   |           |   |         |
| ---------- | --------------------- | -------------- | - | --------- | - | ------- |
| `$eq`      | Equals                | \`filter=name  |   | eq        |   | John\`  |
| `$ne`      | Not equals            | \`filter=name  |   | ne        |   | John\`  |
| `$gt`      | Greater than          | \`filter=age   |   | gt        |   | 18\`    |
| `$lt`      | Less than             | \`filter=age   |   | lt        |   | 65\`    |
| `$gte`     | Greater than or equal | \`filter=age   |   | gte       |   | 21\`    |
| `$lte`     | Less than or equal    | \`filter=age   |   | lte       |   | 100\`   |
| `$starts`  | Starts with           | \`filter=name  |   | starts    |   | Jo\`    |
| `$ends`    | Ends with             | \`filter=email |   | ends      |   | .com\`  |
| `$cont`    | Contains              | \`filter=name  |   | cont      |   | oh\`    |
| `$excl`    | Excludes              | \`filter=name  |   | excl      |   | test\`  |
| `$in`      | In array              | \`filter=id    |   | in        |   | 1,2,3\` |
| `$notin`   | Not in array          | \`filter=id    |   | notin     |   | 4,5\`   |
| `$isnull`  | Is null               | \`filter=bio   |   | isnull\`  |   |         |
| `$notnull` | Is not null           | \`filter=bio   |   | notnull\` |   |         |
| `$between` | Between values        | \`filter=age   |   | between   |   | 18,65\` |

<Tip>
  Add `L` suffix to any operator for case-insensitive comparisons (e.g., `$contL`, `$startsL`, `$eqL`)
</Tip>

## Configure query options

Customize the query behavior in your controller:

```typescript users.controller.ts theme={null}
@Crud({
  model: {
    type: User,
  },
  query: {
    alwaysPaginate: true,
    limit: 20,
    maxLimit: 100,
    sort: [{ field: 'id', order: 'DESC' }],
    join: {
      posts: {
        eager: true,
        alias: 'userPosts',
      },
    },
  },
})
@Controller('users')
export class UsersController {
  constructor(public service: UsersService) {}
}
```

## Override endpoints

You can override any auto-generated endpoint to add custom logic:

```typescript users.controller.ts theme={null}
import { Override, ParsedRequest, CrudRequest } from '@nestjsx/crud';

@Crud({
  model: { type: User },
})
@Controller('users')
export class UsersController {
  constructor(public service: UsersService) {}

  @Override()
  async getOne(@ParsedRequest() req: CrudRequest) {
    console.log('Custom logic before fetching user');
    return this.service.getOne(req);
  }

  @Override('createOneBase')
  async createOne(
    @ParsedRequest() req: CrudRequest,
    @ParsedBody() dto: User,
  ) {
    // Add custom validation or business logic
    console.log('Creating user:', dto);
    return this.service.createOne(req, dto);
  }
}
```

## Next steps

<CardGroup cols={2}>
  <Card title="Query parameters" icon="filter" href="/requests/query-params">
    Learn about all available query parameters and filtering options
  </Card>

  <Card title="Controllers" icon="brackets-curly" href="/concepts/controllers">
    Understand CRUD controllers and configuration options
  </Card>

  <Card title="Services" icon="server" href="/concepts/services">
    Dive deeper into CRUD services and custom implementations
  </Card>

  <Card title="Advanced features" icon="rocket" href="/advanced/global-config">
    Explore authentication, serialization, and Swagger integration
  </Card>
</CardGroup>