Sorting

Sort API results in ascending or descending order using the NestJS CRUD framework

Sorting allows you to order API results by one or more fields in ascending or descending order. This is essential for presenting data in a meaningful way to users.

Basic Syntax

The sort parameter uses the following format:

sort={field},{order}

• field: The name of the field to sort by
• order: Either ASC (ascending) or DESC (descending)

The field and order are separated by a comma (,), not the standard delimiter (||).

Example

GET /users?sort=name,ASC

This retrieves users sorted by name in ascending order (A to Z).

Sort Orders

There are two sort orders available:

Order	Description	Example
ASC	Ascending (A-Z, 0-9, oldest-newest)	sort=name,ASC
DESC	Descending (Z-A, 9-0, newest-oldest)	sort=createdAt,DESC

Sort order is case-sensitive. Use uppercase ASC or DESC. Lowercase values will throw an error.

Ascending Sort

Ascending sort orders results from lowest to highest:

# Sort users by name (A to Z)
GET /users?sort=name,ASC

# Sort products by price (lowest to highest)
GET /products?sort=price,ASC

# Sort posts by date (oldest first)
GET /posts?sort=createdAt,ASC

Descending Sort

Descending sort orders results from highest to lowest:

# Sort users by name (Z to A)
GET /users?sort=name,DESC

# Sort products by price (highest to lowest)
GET /products?sort=price,DESC

# Sort posts by date (newest first)
GET /posts?sort=createdAt,DESC

Multiple Sort Fields

You can sort by multiple fields by adding multiple sort parameters:

# Sort by status (ASC), then by name (ASC)
GET /users?sort=status,ASC&sort=name,ASC

# Sort by priority (DESC), then by createdAt (DESC)
GET /tasks?sort=priority,DESC&sort=createdAt,DESC

The order of sort parameters matters:

• First sort parameter is the primary sort
• Second sort parameter is applied when primary values are equal
• And so on…

Example with Multiple Sorts

GET /users?sort=role,ASC&sort=lastName,ASC&sort=firstName,ASC

This sorts users:

1. First by role (alphabetically)
2. Within each role, by last name (alphabetically)
3. Within each last name, by first name (alphabetically)

Sorting Different Data Types

Strings

# Alphabetical sort
GET /users?sort=name,ASC

# Reverse alphabetical
GET /users?sort=email,DESC

String sorting is typically case-sensitive and follows lexicographic order.

Numbers

# Numeric sort (ascending)
GET /products?sort=price,ASC

# Numeric sort (descending)
GET /users?sort=age,DESC

Numbers are sorted numerically (e.g., 1, 2, 10, 100).

Dates

# Oldest first
GET /posts?sort=createdAt,ASC

# Newest first (most common)
GET /posts?sort=createdAt,DESC

# Sort by last update
GET /articles?sort=updatedAt,DESC

Dates are sorted chronologically.

Booleans

# false values first, then true
GET /users?sort=isActive,ASC

# true values first, then false
GET /users?sort=isVerified,DESC

Boolean sorting: false < true in ascending order.

Sorting with Other Parameters

Combine sorting with filtering, pagination, and field selection:

Sort with Filter

# Get active users sorted by name
GET /users?filter=isActive||eq||true&sort=name,ASC

# Get products under $100 sorted by price
GET /products?filter=price||lt||100&sort=price,ASC

Sort with Pagination

# Get first 10 users sorted by creation date
GET /users?sort=createdAt,DESC&limit=10&page=1

# Get next 10 users
GET /users?sort=createdAt,DESC&limit=10&page=2

Always use the same sort order across paginated requests to ensure consistent results.

Sort with Field Selection

# Get specific fields sorted
GET /users?fields=id,name,email&sort=name,ASC

Complete Example

GET /products?filter=category||eq||electronics&filter=inStock||eq||true&sort=price,ASC&fields=id,name,price&limit=20

This request:

1. Filters electronics products that are in stock
2. Sorts by price (lowest first)
3. Returns only id, name, and price fields
4. Limits results to 20 items

Sorting Nested Fields

You can sort by fields in related entities using dot notation:

# Sort users by profile city
GET /users?join=profile&sort=profile.city,ASC

# Sort posts by author name
GET /posts?join=author&sort=author.name,ASC

# Sort orders by customer email
GET /orders?join=customer&sort=customer.email,ASC

When sorting by nested fields, make sure to include the appropriate join parameter to load the relation.

Common Sorting Patterns

Latest First

# Most recent posts
GET /posts?sort=createdAt,DESC

# Latest user registrations
GET /users?sort=createdAt,DESC

Most Popular

# Most liked posts
GET /posts?sort=likesCount,DESC

# Most viewed articles
GET /articles?sort=viewCount,DESC

Alphabetical Lists

# User directory (A-Z)
GET /users?sort=lastName,ASC&sort=firstName,ASC

# Product catalog
GET /products?sort=name,ASC

Priority/Status Based

# High priority tasks first
GET /tasks?sort=priority,DESC&sort=dueDate,ASC

# Pending orders first
GET /orders?sort=status,ASC&sort=createdAt,DESC

Error Handling

Invalid sort parameters will throw a RequestQueryException:

# Missing order
GET /users?sort=name
# Error: Invalid sort order. ASC,DESC expected

# Invalid order (lowercase)
GET /users?sort=name,asc
# Error: Invalid sort order. ASC,DESC expected

# Invalid order value
GET /users?sort=name,ASCENDING
# Error: Invalid sort order. ASC,DESC expected

# Empty field
GET /users?sort=,ASC
# Error: Invalid sort field. String expected

Performance Considerations

Database Indexes

For optimal performance, create database indexes on frequently sorted fields:

// TypeORM example
@Entity()
@Index(['createdAt'])  // Index for sorting by creation date
export class Post {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  title: string;

  @CreateDateColumn()
  createdAt: Date;
}

Composite Indexes

For multi-field sorts, consider composite indexes:

@Entity()
@Index(['status', 'priority', 'createdAt'])  // Composite index
export class Task {
  @Column()
  status: string;

  @Column()
  priority: number;

  @CreateDateColumn()
  createdAt: Date;
}

Avoid Sorting Large Datasets

# Bad: Sort without limit
GET /users?sort=name,ASC

# Good: Sort with pagination
GET /users?sort=name,ASC&limit=50

Always combine sorting with pagination to limit the dataset size.

Practical Examples

User Management Dashboard

# Show newest users first
GET /users?sort=createdAt,DESC&limit=50

# Show users alphabetically
GET /users?sort=lastName,ASC&sort=firstName,ASC

# Show most active users
GET /users?sort=loginCount,DESC&filter=isActive||eq||true

E-commerce Product Listing

# Price: Low to High
GET /products?filter=category||eq||electronics&sort=price,ASC

# Price: High to Low
GET /products?filter=category||eq||electronics&sort=price,DESC

# Most Popular
GET /products?sort=salesCount,DESC&limit=10

# Newest Arrivals
GET /products?sort=createdAt,DESC&limit=20

Blog/Content Management

# Latest posts
GET /posts?filter=status||eq||published&sort=publishedAt,DESC

# Most commented posts
GET /posts?sort=commentsCount,DESC&limit=10

# Posts by category, then date
GET /posts?sort=category,ASC&sort=publishedAt,DESC

Task Management

# High priority tasks first, then by due date
GET /tasks?filter=status||eq||pending&sort=priority,DESC&sort=dueDate,ASC

# Recently updated tasks
GET /tasks?sort=updatedAt,DESC

# Overdue tasks first
GET /tasks?filter=dueDate||lt||2024-01-01&sort=dueDate,ASC

Best Practices

1. Always specify sort order: Include both field and order (ASC/DESC)
2. Use consistent sorting: Maintain the same sort order across paginated requests
3. Index sorted fields: Add database indexes to commonly sorted fields
4. Combine with pagination: Always limit results when sorting
5. Default to DESC for timestamps: Use sort=createdAt,DESC to show newest items first
6. Consider multiple sorts: Use multiple sort parameters for ties (e.g., same priority)
7. Document default sorting: Let API consumers know the default sort behavior

Next Steps

Pagination

Learn how to paginate sorted results

Filtering

Combine sorting with filters

Relations

Sort by fields in related entities

Query Parameters

Overview of all query parameters