Filters & Parameters

Filters let dashboard viewers interact with the data by selecting values that dynamically update query cells. GradientHarbor supports 12 filter types covering text, numbers, dates, and selections.

How Filters Work

┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│   Input Cell     │     │   Query Cell     │     │   Query Cell     │
│  (Region Filter) │────▶│  (Sales Table)   │     │  (Revenue Chart) │
│                  │     │                  │     │                  │
│  Value: "EMEA"   │────▶│ WHERE region =   │────▶│ WHERE region =   │
│                  │     │   {{region}}     │     │   {{region}}     │
└──────────────────┘     └──────────────────┘     └──────────────────┘

1. Add an input cell with a unique inputId (e.g., region)
2. Reference in your query cells' SQL
3. When the viewer changes the filter value, all connected query cells re-execute

Filter Types

Selection Filters

Type	Description	SQL Pattern
List	Dropdown with single or multi-select	column IN ()
Segmented	Button group selector	column IN ()

Value sources:

• Static — Define options manually (e.g., "North America", "EMEA", "APAC")
• SQL — Fetch options dynamically from a query (e.g., SELECT DISTINCT region FROM customers)

Text Filters

Type	Description	SQL Pattern
Text	Single-line text input	column =
Textarea	Multi-line text area	column =

Date Filters

Type	Description	SQL Pattern
Date	Date picker (with optional time)	column =
Date Range	Start/end date picker	column BETWEEN

Date range filters include preset shortcuts: 7 days, 1 month, 3 months, 6 months, 1 year, and month-to-date.

Number Filters

Type	Description	SQL Pattern
Number	Number input with min/max/step	column =
Number Range	Dual min-max number input	column BETWEEN
Slider	Single-handle slider	column =
Range Slider	Dual-handle range slider	column BETWEEN

Toggle Filters

Type	Description	SQL Pattern
Switch	On/off toggle	column =
Checkbox	Checkbox control	column =

Using Filters in SQL

Reference filter values in your query cells using the placeholder syntax:

SELECT product, SUM(revenue) as total_revenue
FROM sales
WHERE region IN ({{region}})
  AND order_date BETWEEN {{date_range}}
  AND revenue >= {{min_revenue}}
GROUP BY product
ORDER BY total_revenue DESC

The Full-Screen SQL Editor

When editing query cells, the SQL editor provides a dedicated Available Filters panel:

┌─────────────────────────────────────────────────────────┐
│ Full-Screen SQL Editor                                  │
├───────────────────────────────┬──────────────────────────┤
│                               │  📂 Data Explorer       │
│   SELECT *                    │  🔽 Available Filters    │
│   FROM orders                 │  ┌────────────────────┐ │
│   WHERE region IN             │  │ region (list)      │ │
│     ({{region}})              │  │ Current: "EMEA"    │ │
│   AND date BETWEEN            │  │ SQL: IN ({{region}})│ │
│     {{date_range}}            │  │ [Copy placeholder] │ │
│                               │  └────────────────────┘ │
│                               │  ┌────────────────────┐ │
│                               │  │ date_range (range) │ │
│                               │  │ SQL: BETWEEN       │ │
│                               │  │   {{date_range}}   │ │
│                               │  │ [Copy placeholder] │ │
│                               │  └────────────────────┘ │
│   [▶ Run]  [Cancel]           │                          │
└───────────────────────────────┴──────────────────────────┘

The filters panel shows:

• All available input cells on the current page
• Type-aware SQL clause examples for each filter
• Current values for preview
• Copy buttons for quickly inserting placeholders into your SQL

TIP

The full-screen editor opens automatically for cells narrower than half the dashboard width. You can also access it via the expand button on any query cell.

The right panel also includes a Data Explorer tab for browsing your data catalog — search for tables, view columns, and reference schemas while writing SQL.

Best Practices

• Name filters descriptively — Use start_date instead of param1
• Set sensible defaults — Ensure dashboards load with meaningful data
• Use SQL value sources — Keep dropdown options in sync with actual data
• Combine filters — Use multiple filters for drill-down (region + date + product)
• Place filters at the top — Viewers expect controls above the data they affect