Advanced Filtering Documentation

Overview

The task API now supports advanced filtering capabilities that match the frontend's requirements. This includes bracket notation filters, field-specific searches, and response field exclusion.

Filter Syntax

1. Multi-Value Filters

Use filters[field]=value1,value2 to filter by multiple values with OR logic:

filters[tags]=tasks:improvements,tasks:IOS
filters[priority]=low,medium
filters[status]=pending,in_progress

2. Field-Specific Searches

Use searches[field]=term to search within specific fields:

searches[name]=task
searches[unique_code]=TSK-2024
searches[description]=important

3. Field Exclusion

Use exclude=field1,field2 to remove fields from the response:

exclude=description,createdAt,updatedAt
exclude=participants.employee.departmentRole

4. Combined Example

GET /api/v1/tasks/projects/PIPE/tasks?
  filters[tags]=tasks:improvements,tasks:IOS&
  filters[priority]=low,medium&
  searches[unique_code]=abc&
  searches[name]=abc&
  exclude=description,createdAt,updatedAt&
  page=1&
  limit=20

Implementation Details

Components

  1. Query Parser (/internal/utils/query_parser.go)

    • Parses bracket notation parameters
    • Handles comma-separated values
    • Supports URL encoding

  2. Query Builder (/internal/repository/query_builder.go)

    • Builds GORM queries from parsed filters
    • Handles PostgreSQL array operations for tags
    • Applies WHERE IN clauses for multi-value filters

  3. Response Transformer (/internal/utils/response_transformer.go)

    • Excludes specified fields from responses
    • Handles nested field exclusion
    • Uses reflection for dynamic field removal

  4. Handler Updates (/internal/handlers/task_handler.go)

    • Parses advanced filters from query string
    • Applies field exclusion to responses

  5. Service Updates (/internal/services/task_service.go)

    • Accepts and applies advanced filters
    • Maintains backward compatibility

Backward Compatibility

The implementation maintains full backward compatibility with the legacy filter format:

// Legacy format still works
GET /tasks/projects/PIPE/tasks?status=pending&priority=low

// New format
GET /tasks/projects/PIPE/tasks?filters[status]=pending&filters[priority]=low

Supported Fields for Filtering

  • tags - PostgreSQL array field (uses array overlap operator)
  • priority - Enum field (low, medium, high, urgent)
  • status - Enum field (pending, in_progress, completed, etc.)
  • departmentId - String field
  • Any other field in snake_case format

Supported Fields for Searching

  • name - Task name
  • unique_code - Task unique code
  • description - Task description
  • Any other text field

Testing

Unit tests are provided for all components:

  • tests/unit/query_parser_test.go - Query parser tests
  • tests/unit/response_transformer_test.go - Response transformer tests
  • tests/integration/task_filtering_test.go - End-to-end filtering tests

Run tests with:

go test ./tests/unit/query_parser_test.go ./tests/unit/response_transformer_test.go -v