Skip to main content

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.

​
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

PrefixTypeExample
s:Select (single value)s:Athletics
sm:Select (multi-select)sm:Athletics or sm:Athletics,Swimming
n:Numericn:2000
b:Booleanb:true
i:Text inputi:search term
dp:Date presetdp:last_7_days
ds:Date (single)ds:2024-01-01
dr:Date rangedr:2024-01-01,2024-12-31

​
Examples

Single filter: 
<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): 
<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: 
<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

<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.
For setup instructions on configuring controlled filters in the Hub, see Controlled Filters.

​
URL Format

filter_{controlKey}={JSON-encoded value}
For Select Multi filter types, the value must be a JSON array, not a plain string. Plain strings cause chart load errors.

​
Examples

<!-- 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: 
<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).
If you are using the older /share/dashboard/{dashboardId} URL pattern (hub1), controlled filters work the same way with the filter_ prefix:
<iframe
  src="https://hub.upsolve.ai/share/dashboard/{dashboardId}?filter_region=North%20America&filter_department=Engineering"
  width="100%"
  height="600px"
/>
Differences from hub2:
  • Hub1 accepts plain string values (not just JSON arrays) for controlled filters
  • Hub1 does not support f_ prefix (omnibar) filters — only filter_ prefix
  • Hub1 uses the UpsolveDashboard component prop controlledFilterValues as an alternative to URL params
Migrating to hub2:Replace your iframe src from the hub1 pattern to hub2:
# Before (hub1)
https://hub.upsolve.ai/share/dashboard/{dashboardId}?filter_region=North%20America

# After (hub2)
https://ai-hub.upsolve.ai/share/application/{applicationId}?jwt={token}&filter_region=%5B%22North%20America%22%5D
Note: hub2 requires JSON-encoded values for Select Multi filters.

​
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.