User & Content Filter Parameters

The combination of content filters (both at user level and shared URL level) and parameters allow admin users to control user access to a subset of available data on the same dashboard or widget. Filters are replaced at runtime for direct queries, or applied on top of the data returned by a query.

User Level Filters

User-level filters limit data based on criteria associated to that user. For example, a national manager may be allowed to see data for all regions, but a Regional manager is only allowed to see data for their specific region for the same dashboard.

To set the user level filters, set the User Filter either during user invitation or if the user is already in the system, via the Edit User From the Team Menu.

Following example limits a user to a specific organizationid, applied on top of the results of the query. Note that the organizationid must be present in the dataset for the filter to take effect.

Also note the second filter is a query parameter called $c9_region$ passed into the query.

For more details on query parameters, please read /docs/embedSSO.html

Content Filters in Share URLs

The contentFilters URL parameter filters a dashboard or widget when it loads. This lets you send one shared dashboard to different audiences, each seeing only their own customer, region or date range.

contentFilters works with:

Note: On a plain Shareable URL, the filter values are visible and can be edited by anyone with the link. Use content filters in a plain URL for convenience, not security. To restrict the data a viewer can see, use User Level Filters or Secure URL Embed.

Syntax

contentFilters takes a JSON array. Each object in the array is one filter:

[{"fieldName":"customer","values":["Costco"],"operator":"="}]
Key Type Description
fieldName string The field to filter on. Must match the field name in the dataset exactly, including case.
values array The value(s) to compare against. Always an array, even for a single value. Quote strings (["Costco"]) and leave numbers unquoted ([90000]).
operator string The comparison to apply. Case sensitive. See Supported Operators.

Important: A fieldName that does not match a field on the dataset is ignored, and the dashboard shows unfiltered data. There is no error, and a dropped filter looks the same as a working one. Before sending a link that is meant to narrow the data, open it and check that the row count matches what you expect.

To use the filter in a link, URL encode the whole JSON string and append it to the share URL:

<share URL>?contentFilters=<URL-encoded JSON>

For example, the filter above becomes:

https://www.knowi.com/d/<dashboardShareId>?contentFilters=%5B%7B%22fieldName%22%3A%22customer%22%2C%22values%22%3A%5B%22Costco%22%5D%2C%22operator%22%3A%22%3D%22%7D%5D

Tip: Write the JSON in plain text first, then run it through a URL encoder. Spaces in field names, apostrophes in values (such as Macy's) and other special characters need no extra escaping beyond normal URL encoding.

URL Length

Keep the full URL under 6,000 characters. Longer URLs fail with an HTTP 413 (Request Entity Too Large) error page. Browser cookies count toward the same limit, so a long link can work for a signed-out viewer and fail for a signed-in one.

As a rough guide, an in filter fits about:

Value Type Approximate Number of Values
Short codes (8 characters) 350
Company names (12 characters) 275
Email addresses (25 characters) 170
UUIDs (36 characters) 125

Supported Operators

Important: Operators are case sensitive and must match exactly. An operator that is not recognized, such as IN, LIKE, <> or a typo, does not cause an error. It is treated as =, so the dashboard loads normally but shows the wrong rows.

Operator Field Types Description
= string, number, date Exact match, case sensitive. With several values, matches any of them (same as in).
!= string, number, date Excludes rows that match the value.
in string, number Matches any value in the array.
not in string, number Excludes every value in the array.
like string Contains the value, case insensitive. For example, Ma matches Macy's. On datasets stored in an external SQL data store, case sensitivity follows that database.
not like string Excludes rows that contain the value, case insensitive. On datasets stored in an external SQL data store, case sensitivity follows that database.
Starts With string Begins with the value. Must be written in title case. Not supported on datasets stored in an external PostgreSQL, MySQL, Redshift or Snowflake data store, where this filter is ignored. Use like there instead.
> number, date Greater than.
>= number, date Greater than or equal to.
< number, date Less than.
<= number, date Less than or equal to.
range date Between a start date and an end date, including both days in full: "values":["2026-07-25","2026-07-28"]. For number ranges, use >= and <= instead.
is null any Field is empty. Use an empty values array: "values":[].
is not null any Field has a value. Use an empty values array: "values":[].

Symbol and lowercase word operators are written as shown, with single spaces (not in, is null). For >, >=, < and <=, only the first value in the array is used. The spelled-out forms Equals, Not Equals, Contains, Does Not Contain, Greater than, Greater than or equals, Less than and Less than or equals are also accepted, with exactly that capitalization.

Note: Operator support can differ by datasource type. If a filter does not seem to apply, test the link against your own datasource before sharing it.

Examples:

{"fieldName":"customer","values":["Costco"],"operator":"="}
{"fieldName":"customer","values":["Costco","Target"],"operator":"in"}
{"fieldName":"customer","values":["Costco","Target"],"operator":"not in"}
{"fieldName":"customer","values":["Ma"],"operator":"like"}
{"fieldName":"opened","values":[90000],"operator":">"}
{"fieldName":"customer","values":[],"operator":"is not null"}

Combining Filters

All filters in the array are combined with AND. For example, the following returns only Marketing rows for Costco and Target:

[{"fieldName":"customer","values":["Costco","Target"],"operator":"in"},
 {"fieldName":"message_type","values":["Marketing"],"operator":"="}]

To match one value OR another on the same field, put all the values in a single filter with in. Two separate filters on the same field must both be true, so the following returns no data:

[{"fieldName":"customer","values":["Costco"],"operator":"="},
 {"fieldName":"customer","values":["Target"],"operator":"="}]

There is no way to combine filters on different fields with OR.

Filtering by Date Range

Use the range operator with a start date and an end date. Both dates are included:

[{"fieldName":"Sent Date","values":["2026-07-25","2026-07-28"],"operator":"range"}]

This returns July 25 through July 28, including rows from any time on July 28.

You can also use two filters on the same field, a lower bound and an upper bound. In that case, use < with the day after your last day as the upper bound:

[{"fieldName":"Sent Date","values":["2026-07-25"],"operator":">="},
 {"fieldName":"Sent Date","values":["2026-07-29"],"operator":"<"}]

An upper bound of <= with "2026-07-28" leaves out most of July 28. A date without a time is read as midnight at the start of that day, so rows timestamped later on July 28 fall outside the filter. You can also pass exact timestamps as epoch milliseconds, for example [1784966400000].

With a single date, = matches the whole day, regardless of time: "values":["2026-07-27"] returns every row from July 27. This does not apply to Direct Query datasets, where = matches only rows timestamped exactly at midnight. Use range with the same start and end date instead, which works everywhere.

For a number range, use two filters with >= and <=:

[{"fieldName":"opened","values":[1000],"operator":">="},
 {"fieldName":"opened","values":[5000],"operator":"<="}]

Timezones: On a dashboard Shareable URL, dates in contentFilters are read in the dashboard owner's timezone (see Changing the Default Timezone). The viewer's own timezone has no effect, so the same link returns the same rows for everyone. On a widget Shareable URL, the widget owner's timezone is used for viewers who are not signed in to Knowi, but a signed-in viewer's own timezone is used instead, so results near day boundaries can differ between viewers. The _tz parameter changes the timezone on Secure URL Embed and embed links only. It is ignored on Shareable URLs.

Troubleshooting

  • The dashboard shows all the data, unfiltered. Check that fieldName matches the field name in the dataset exactly, including case. An unknown field name is ignored. If you used Starts With, check that the dataset is not stored in an external SQL data store.
  • The dashboard shows the wrong rows. Check the spelling and case of the operator. An unrecognized operator, such as IN or <>, is treated as =.
  • The dashboard is empty. A value that does not exist in the data returns no rows, with no error. Check that the value matches the data exactly, including capitalization when using =, in or !=.
  • Numbers are not filtering correctly. Make sure numeric values are unquoted: [90000], not ["90000"].
  • A date range is missing the last day. Use range, or < with the following day as the upper bound. See Filtering by Date Range.
  • The link returns a 413 error. The URL is too long. See URL Length.
  • The link value is not applied to a dashboard filter. If a dashboard filter has a fixed default value, it can conflict with the value passed in the link. Set the dashboard filter to Require Value and leave the default value blank.