Knack Filter Sort

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