Filtering Data

Learn how to filter and sort data in GraphQL queries to retrieve exactly what you need.

Overview

GraphQL allows you to filter and sort data directly in your queries using input arguments. This enables you to retrieve specific subsets of data without fetching everything and filtering on the client side.

Filtering

Filtering allows you to narrow down results based on specific criteria. Most list queries accept filter arguments to specify conditions.

Basic Filtering

query {
  items(filters: { status: ACTIVE }) {
    items {
      _id
      title
    }
  }
}

Multiple Filter Conditions

You can combine multiple filter conditions:

query {
  items(
    filters: {
      status: ACTIVE
      category: "electronics"
      priceRange: { min: 10, max: 100 }
    }
  ) {
    items {
      _id
      title
      price
    }
  }
}

Filter Types

Common filter types include:

• Equality filters: Match exact values
• Range filters: Match values within a range (numbers, dates)
• Text filters: Match text patterns (contains, starts with, etc.)
• Array filters: Match items in arrays (contains, in, etc.)
• Boolean filters: Match true/false conditions

Using Variables for Filters

Always use variables for dynamic filtering:

query GetFilteredItems($filters: ItemFilters) {
  items(filters: $filters) {
    items {
      _id
      title
    }
  }
}

Variables:

{
  "filters": {
    "status": "ACTIVE",
    "category": "electronics"
  }
}

Sorting

Sorting allows you to order results by specific fields. Sorting is typically combined with pagination.

Basic Sorting

query {
  items(
    pagination: {
      page: 1
      limit: 20
      sort: "createdAt"
      order: -1
    }
  ) {
    items {
      _id
      title
      createdAt
    }
  }
}

Sort Order

• 1 or ASC: Ascending order (A-Z, 1-9, oldest to newest)
• -1 or DESC: Descending order (Z-A, 9-1, newest to oldest)

Common Sort Fields

Common fields you can sort by:

• createdAt - Creation date
• updatedAt - Last update date
• title - Alphabetical by title
• price - By price value
• name - Alphabetical by name

Available sort fields depend on the specific query and API. Check the API documentation for supported sort fields.

Sorting with Variables

query GetSortedItems($pagination: PaginationInput) {
  items(pagination: $pagination) {
    items {
      _id
      title
    }
    pagination {
      sort
      order
    }
  }
}

Variables:

{
  "pagination": {
    "page": 1,
    "limit": 20,
    "sort": "price",
    "order": 1
  }
}

Combining Filtering and Sorting

You can combine filtering and sorting in a single query:

query GetFilteredAndSortedItems(
  $filters: ItemFilters
  $pagination: PaginationInput
) {
  items(filters: $filters, pagination: $pagination) {
    items {
      _id
      title
      price
    }
    pagination {
      page
      pages
      count
      sort
      order
    }
  }
}

Variables:

{
  "filters": {
    "status": "ACTIVE",
    "category": "electronics"
  },
  "pagination": {
    "page": 1,
    "limit": 20,
    "sort": "price",
    "order": 1
  }
}

Best Practices

• Use variables - Always use variables for filters and sorting to make queries reusable and secure
• Combine with pagination - When filtering large datasets, always combine with pagination to limit results
• Validate filter inputs - Validate filter values on the client side before sending queries
• Handle empty results - Always handle cases where filters return no results
• Cache filter state - Store filter and sort state in your application to maintain user preferences

Common Patterns

Search with Filters

query SearchItems($search: String, $filters: ItemFilters) {
  items(
    search: $search
    filters: $filters
    pagination: { page: 1, limit: 20 }
  ) {
    items { ... }
  }
}

Dynamic Sorting

query GetItems($sortField: String, $sortOrder: Int) {
  items(
    pagination: {
      page: 1
      limit: 20
      sort: $sortField
      order: $sortOrder
    }
  ) {
    items { ... }
  }
}

Multiple Sort Criteria

Some APIs support sorting by multiple fields. Check the API documentation for support:

query {
  items(
    pagination: {
      sort: "category,price"
      order: 1
    }
  ) {
    items { ... }
  }
}

API-Specific Notes

Filter and sort capabilities vary by API and endpoint:

• Filter syntax: Different APIs may use different filter input types
• Available filters: Not all fields are filterable
• Sort fields: Only certain fields support sorting
• Performance: Complex filters may impact query performance

Always refer to the specific API documentation for:

• Available filter fields and types
• Supported sort fields
• Filter syntax and operators
• Performance considerations

Summary

• Use filters to narrow down results based on criteria
• Use sorting to order results by specific fields
• Always use variables for dynamic filtering and sorting
• Combine filtering and sorting with pagination for large datasets
• Validate inputs and handle empty results gracefully
• Check API documentation for available filters and sort fields