Knack Filter Sort

Purpose

Dynamic filtering, sorting, and query optimization for HTI dashboards and compliance reports. Reduces API payload size and improves dashboard performance.

Filter Syntax

Basic Structure

{
  "match": "and",
  "rules": [
    {
      "field": "field_123",
      "operator": "is",
      "value": "Ready for Donation"
    }
  ]
}

Multiple Conditions

{
  "match": "and",
  "rules": [
    {
      "field": "field_status",
      "operator": "is",
      "value": "Ready"
    },
    {
      "field": "field_county",
      "operator": "is",
      "value": "Wake"
    }
  ]
}

Operators

Text Fields

• is

  - Exact match

• is not

  - Exclusion

• contains

  - Substring match

• starts with

  - Prefix match

• ends with

  - Suffix match

Number Fields

• is

  - Equal to

• is not

  - Not equal

• >

  - Greater than

• <

  - Less than

• >=

  - Greater than or equal

• <=

  - Less than or equal

Date Fields

• is

  - Specific date

• is before

  - Earlier than

• is after

  - Later than

• is during

  - Date range

• is today

• is this week

• is this month

• is this year

Boolean Fields

• is

  - True/False

Core Functions

build_filter

Purpose: Construct Knack-compatible filter objects

Example:

const filter = build_filter({
  match: "and",
  rules: [
    { field: "field_5", operator: "is", value: "Converted" },
    { field: "field_12", operator: "is after", value: "2025-01-01" }
  ]
});

apply_sort

Purpose: Sort results by field and direction

Parameters:

• sort_field

  (string): Field identifier (e.g., "field_7")

• sort_order

  (string): "asc" or "desc"

Example:

const sort = apply_sort({
  sort_field: "field_acquisition_date",
  sort_order: "desc"
});

combine_filters

Purpose: Merge multiple filter sets (AND/OR logic)

Example:

const combined = combine_filters({
  operator: "or",
  filters: [wake_filter, durham_filter, vance_filter]
});

HTI-Specific Filters

Grant Reporting Filters

Acquired This Quarter

const q1_acquired = build_filter({
  match: "and",
  rules: [
    {
      field: "field_acquisition_date",
      operator: "is during",
      range: { start: "2025-01-01", end: "2025-03-31" }
    }
  ]
});

Ready for Donation

const ready_devices = build_filter({
  match: "and",
  rules: [
    { field: "field_status", operator: "is", value: "Ready for Donation" },
    { field: "field_tested", operator: "is", value: true }
  ]
});

By County (15-County Coverage)

const wake_county = build_filter({
  match: "and",
  rules: [
    { field: "field_target_county", operator: "is", value: "Wake" }
  ]
});

Recurring Donors (2026 Goal: 6+ with 50+ laptops)

const recurring_donors = build_filter({
  match: "and",
  rules: [
    { field: "field_donation_count", operator: ">=", value: 3 },
    { field: "field_total_laptops", operator: ">=", value: 50 }
  ]
});

Training Sessions (156+ Hours Goal)

const training_hours = build_filter({
  match: "and",
  rules: [
    { field: "field_session_date", operator: "is this year", value: "2025" },
    { field: "field_session_status", operator: "is", value: "Completed" }
  ]
});

Dashboard Filters

Devices Needing Action

const needs_action = build_filter({
  match: "or",
  rules: [
    { field: "field_status", operator: "is", value: "Acquired - Needs Testing" },
    { field: "field_status", operator: "is", value: "Failed Testing" },
    { field: "field_status", operator: "is", value: "Awaiting Parts" }
  ]
});

High-Value Donors (>$500)

const major_donors = build_filter({
  match: "and",
  rules: [
    { field: "field_donation_value", operator: ">", value: 500 }
  ]
});

Sort Configurations

Common Sorts

Most Recent First

apply_sort({
  sort_field: "field_acquisition_date",
  sort_order: "desc"
});

Alphabetical by County

apply_sort({
  sort_field: "field_county",
  sort_order: "asc"
});

Highest Donation Value

apply_sort({
  sort_field: "field_donation_value",
  sort_order: "desc"
});

Query Optimization

Best Practices

1. Filter at API level (not client-side) to reduce payload
2. Use indexed fields for faster queries
3. Combine filters rather than chaining requests
4. Cache filtered results for repeated dashboard loads

Performance Comparison

// ❌ BAD: Fetch all, filter client-side
const all = await get_records("object_1"); // 3,500+ records
const ready = all.filter(d => d.status === "Ready"); // Slow, wasteful

// ✅ GOOD: Filter at API level
const ready = await get_records("object_1", {
  filters: build_filter({
    rules: [{ field: "field_status", operator: "is", value: "Ready" }]
  })
}); // Only returns ~200 records

Integration with Pagination

// Filter + paginate for large result sets
const all_wake_devices = await fetch_all_pages("object_1", {
  filters: build_filter({
    rules: [{ field: "field_county", operator: "is", value: "Wake" }]
  }),
  sort: apply_sort({ sort_field: "field_date", sort_order: "desc" })
});

Error Handling

try {
  const filtered = await get_records("object_1", { filters: my_filter });
} catch (error) {
  if (error.message.includes("invalid field")) {
    console.error("Filter references non-existent field");
  }
}

Integration Points

• knack_reader: Apply filters to get_records calls
• knack_pagination: Consistent filters across paginated requests
• knack_dashboard_ai: Dynamic filter generation based on user input
• knack_reporting_sync: Quarterly report filtering (dates, counties, statuses)
• knack_goal_tracker: Filter by goal-relevant criteria

NCDIT Compliance

• Filter by reporting period (quarterly)
• Exclude test/dummy records
• Include only grant-funded devices
• Separate operational vs. financial data