> ## 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.
# Select Fields
> Control which fields are returned in API responses using field selection in NestJS CRUD
Field selection allows you to specify exactly which fields to return in your API responses. This reduces payload size, improves performance, and gives clients fine-grained control over the data they receive.
## Basic Syntax
The fields parameter uses the following format:
```bash theme={null}
fields={field1},{field2},{field3}
```
* **fields**: Comma-separated list of field names to return
### Aliases
The `fields` parameter has aliases:
* `fields`
* `select`
```bash theme={null}
# Both are equivalent
GET /users?fields=id,name,email
GET /users?select=id,name,email
```
## Basic Usage
### Single Field
```bash theme={null}
# Return only the name field
GET /users?fields=name
```
### Multiple Fields
```bash theme={null}
# Return id, name, and email fields
GET /users?fields=id,name,email
```
Fields are separated by commas (`,`) with no spaces.
## Default Behavior
Without field selection, all fields are returned:
```bash theme={null}
# Returns all fields
GET /users/1
# Response:
{
"id": 1,
"name": "John Doe",
"email": "john@example.com",
"age": 30,
"isActive": true,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-15T00:00:00.000Z"
}
```
With field selection:
```bash theme={null}
# Returns only selected fields
GET /users/1?fields=id,name,email
# Response:
{
"id": 1,
"name": "John Doe",
"email": "john@example.com"
}
```
## Common Use Cases
### Minimal Data for Lists
```bash theme={null}
# User list with minimal data
GET /users?fields=id,name,avatar&limit=50
```
Perfect for rendering user lists where you only need basic info.
### ID and Name for Dropdowns
```bash theme={null}
# For select/dropdown components
GET /categories?fields=id,name
GET /users?fields=id,name
GET /products?fields=id,title
```
### Excluding Sensitive Fields
```bash theme={null}
# Public profile (exclude sensitive data)
GET /users?fields=id,name,bio,avatar
# Excludes: email, phone, address, etc.
```
### Mobile API Responses
```bash theme={null}
# Lightweight response for mobile
GET /posts?fields=id,title,excerpt,thumbnail&limit=20
# Excludes: full content, author details, etc.
```
## Field Selection with Relations
Combine field selection with joins:
```bash theme={null}
# Select fields from main entity
GET /posts?fields=id,title,content&join=author
# Select fields from both main and related entities
GET /posts?fields=id,title,content&join=author||name,email
```
### Main Entity Fields
The `fields` parameter controls the main entity fields:
```bash theme={null}
GET /posts?fields=id,title&join=author||name,email
```
Returns:
```json theme={null}
{
"id": 1,
"title": "My Post",
"author": {
"name": "John Doe",
"email": "john@example.com"
}
}
```
### Related Entity Fields
Use the join syntax to select related entity fields:
```bash theme={null}
join={relation}||{field1},{field2}
```
```bash theme={null}
# Select specific fields from author
GET /posts?join=author||name,avatar
# Select from multiple relations
GET /posts?join=author||name&join=category||name
```
## Nested Field Selection
For nested relations, use dot notation in field names:
```bash theme={null}
# Select nested fields
GET /users?fields=id,name,profile.city,profile.country
# Or use join with field selection
GET /users?fields=id,name&join=profile||city,country
```
Using join syntax is generally more explicit and recommended for selecting related entity fields.
## Complete Examples
### User Profile API
```bash theme={null}
# Public profile
GET /users/123?fields=id,name,bio,avatar,createdAt
# Profile with location
GET /users/123?fields=id,name,email&join=profile||city,country
# Minimal user info
GET /users?fields=id,name&limit=100
```
### Blog API
```bash theme={null}
# Post list with preview
GET /posts?fields=id,title,excerpt,thumbnail,publishedAt&limit=20
# Full post with author
GET /posts/456?fields=id,title,content,publishedAt&join=author||name,avatar
# Post titles only
GET /posts?fields=id,title&sort=publishedAt,DESC
```
### E-commerce API
```bash theme={null}
# Product list
GET /products?fields=id,name,price,thumbnail,inStock&limit=50
# Product details
GET /products/789?fields=id,name,description,price,sku&join=category||name
# Minimal product info for cart
GET /products?fields=id,name,price&filter=id||in||1,2,3
```
## Combining with Other Parameters
### With Filtering
```bash theme={null}
GET /users?filter=isActive||eq||true&fields=id,name,email
```
### With Sorting
```bash theme={null}
GET /products?sort=price,ASC&fields=id,name,price
```
### With Pagination
```bash theme={null}
GET /users?limit=20&page=1&fields=id,name,email&sort=name,ASC
```
### Complete Query
```bash theme={null}
GET /posts?filter=status||eq||published&filter=category||eq||Technology&fields=id,title,excerpt&join=author||name,avatar&sort=publishedAt,DESC&limit=20&page=1
```
This request:
1. Filters published posts in Technology category
2. Returns only id, title, and excerpt from posts
3. Joins author with name and avatar
4. Sorts by publish date (newest first)
5. Returns 20 posts per page
6. Returns first page
## Performance Benefits
### Reduced Payload Size
```bash theme={null}
# ❌ Bad: Returns all fields (large response)
GET /users?limit=1000
# Response size: ~500KB
# ✅ Good: Returns only needed fields
GET /users?fields=id,name&limit=1000
# Response size: ~50KB (10x smaller)
```
### Faster Database Queries
Selecting fewer fields can improve database query performance:
```bash theme={null}
# ❌ Bad: SELECT * FROM users
GET /users
# ✅ Good: SELECT id, name, email FROM users
GET /users?fields=id,name,email
```
### Reduced Network Transfer
```bash theme={null}
# Mobile app: Only load essential data
GET /posts?fields=id,title,thumbnail&limit=20
```
Especially important for mobile apps on slow connections.
## Security Considerations
### Protecting Sensitive Fields
Configure which fields can be selected:
```typescript theme={null}
import { Crud } from '@nestjsx/crud';
@Crud({
model: { type: User },
query: {
exclude: ['password', 'passwordResetToken'], // Never allow these
},
})
@Controller('users')
export class UsersController {}
```
### Field Whitelisting
```typescript theme={null}
@Crud({
model: { type: User },
query: {
allow: ['id', 'name', 'email', 'avatar'], // Only allow these fields
},
})
```
Always use `exclude` or `allow` in your CRUD configuration to prevent exposure of sensitive fields like passwords, tokens, or internal IDs.
## Entity Configuration
### TypeORM Example
```typescript theme={null}
import { Entity, Column, PrimaryGeneratedColumn } from 'typeorm';
import { Exclude } from 'class-transformer';
@Entity()
export class User {
@PrimaryGeneratedColumn()
id: number;
@Column()
name: string;
@Column()
email: string;
@Column()
@Exclude() // Never include in responses
password: string;
@Column()
avatar: string;
@Column()
bio: string;
}
```
### Controller Configuration
```typescript theme={null}
import { Crud, CrudController } from '@nestjsx/crud';
import { Controller } from '@nestjs/common';
import { UsersService } from './users.service';
import { User } from './user.entity';
@Crud({
model: {
type: User,
},
query: {
exclude: ['password'], // Never return password
allow: ['id', 'name', 'email', 'avatar', 'bio', 'createdAt'], // Allowed fields
},
})
@Controller('users')
export class UsersController implements CrudController {
constructor(public service: UsersService) {}
}
```
## Frontend Implementation
### React Example
```javascript theme={null}
import { useState, useEffect } from 'react';
function UserList() {
const [users, setUsers] = useState([]);
useEffect(() => {
// Only fetch fields needed for the list
fetch('/api/users?fields=id,name,avatar&limit=50')
.then(res => res.json())
.then(data => setUsers(data));
}, []);
return (
{users.map(user => (
{user.name}
))}