> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upsolve.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# URL Filter Parameters

> Pre-filter shared dashboards via URL query parameters

## Overview

When embedding dashboards in iframes or sharing application links, you can pre-set filter values directly in the URL. This lets you:

* Show different data views to different users without building separate dashboards
* Deep-link to a specific filtered state
* Control filters programmatically from your host application

## Omnibar Filters (`f_` prefix)

The primary way to pass filter values via URL. These filters show as interactive pills in the filter bar — users can see what's filtered and modify or remove them.

### URL Format

```
f_{sourceType}.{tableName}.{columnName}={typePrefix}:{value}
```

**Source types:**

* `Raw` — a column from a raw database table
* `Output` — a computed/output column from chart SQL
* `Variable` — an RLS variable filter

### Value Types

| Prefix | Type                  | Example                                   |
| ------ | --------------------- | ----------------------------------------- |
| `s:`   | Select (single value) | `s:Athletics`                             |
| `sm:`  | Select (multi-select) | `sm:Athletics` or `sm:Athletics,Swimming` |
| `n:`   | Numeric               | `n:2000`                                  |
| `b:`   | Boolean               | `b:true`                                  |
| `i:`   | Text input            | `i:search term`                           |
| `dp:`  | Date preset           | `dp:last_7_days`                          |
| `ds:`  | Date (single)         | `ds:2024-01-01`                           |
| `dr:`  | Date range            | `dr:2024-01-01,2024-12-31`                |

### Examples

**Single filter:**

```html theme={null}
<iframe
  src="https://ai-hub.upsolve.ai/share/application/{appId}?jwt={token}&f_Raw.orders.status=sm:shipped"
  width="100%"
  height="600px"
/>
```

**Multiple filters (AND logic):**

```html theme={null}
<iframe
  src="https://ai-hub.upsolve.ai/share/application/{appId}?jwt={token}&f_Raw.orders.status=sm:shipped&f_Raw.orders.region=sm:APAC"
  width="100%"
  height="600px"
/>
```

**Date range filter:**

```html theme={null}
<iframe
  src="https://ai-hub.upsolve.ai/share/application/{appId}?jwt={token}&f_Raw.orders.created_at=dr:2024-01-01,2024-12-31"
  width="100%"
  height="600px"
/>
```

### Behavior

* Filters appear as pills in the omnibar — users can see what's active
* Multiple filters combine with AND logic
* Users can remove or modify filters using the pill controls
* Non-existent columns are silently ignored (no error)
* Works with both JWT-authenticated and public (anonymous) access

### Dynamic Filters from JavaScript

```html theme={null}
<script>
  function updateDashboardFilter(column, value) {
    const base = 'https://ai-hub.upsolve.ai/share/application/{appId}';
    const jwt = '{token}';
    const iframe = document.getElementById('dashboard');
    iframe.src = `${base}?jwt=${jwt}&f_Raw.orders.${column}=sm:${value}`;
  }

  // Example: filter by region when user selects from a dropdown
  document.getElementById('regionSelect').addEventListener('change', (e) => {
    updateDashboardFilter('region', e.target.value);
  });
</script>
```

***

## Controlled Filters (`filter_` prefix)

Controlled filters are configured in the Upsolve Hub with a **control key**. They're designed for server-side or host-app control — typically hidden from end users.

<Info>
  For setup instructions on configuring controlled filters in the Hub, see [Controlled Filters](/embedded-bi/filters/controlled-filters).
</Info>

### URL Format

```
filter_{controlKey}={JSON-encoded value}
```

<Warning>
  For **Select Multi** filter types, the value **must** be a JSON array, not a plain string. Plain strings cause chart load errors.
</Warning>

### Examples

```html theme={null}
<!-- Correct: JSON array value (URL-encoded) -->
<iframe
  src="https://ai-hub.upsolve.ai/share/application/{appId}?jwt={token}&filter_region=%5B%22North%20America%22%5D"
  width="100%"
  height="600px"
/>

<!-- Multiple controlled filters -->
<iframe
  src="https://ai-hub.upsolve.ai/share/application/{appId}?jwt={token}&filter_region=%5B%22APAC%22%5D&filter_department=%22Engineering%22"
  width="100%"
  height="600px"
/>
```

### Combining Both Filter Types

You can use omnibar (`f_`) and controlled (`filter_`) filters together in the same URL:

```html theme={null}
<iframe
  src="https://ai-hub.upsolve.ai/share/application/{appId}?jwt={token}&f_Raw.orders.status=sm:shipped&filter_region=%5B%22APAC%22%5D"
  width="100%"
  height="600px"
/>
```

The omnibar filter shows as an interactive pill; the controlled filter is applied silently (unless configured as visible).

## Troubleshooting

### Filter Not Applying

* **Check the column name**: The `f_` prefix requires the exact table and column name from your database. Misspelled names are silently ignored.
* **Check the source type**: Use `Raw` for database columns, `Output` for computed columns.
* **Check value encoding**: For `f_` filters, include the type prefix (`sm:`, `s:`, `n:`, etc.). For `filter_` controlled filters, use URL-encoded JSON.

### Controlled Filter Causes Chart Errors

* **Use JSON arrays for Select Multi**: `filter_key=%5B%22value%22%5D` (which is `["value"]` URL-encoded), not `filter_key=value`.
* **Verify the control key matches**: The `filter_` suffix must match the exact `controlKey` configured in the Hub filter settings.

### Filters Visible When They Should Be Hidden (or Vice Versa)

* Omnibar (`f_`) filters are always visible as pills
* Controlled (`filter_`) filters are hidden by default. Set `isVisible: true` in the Hub filter configuration to make them visible.