Filter types and application layers
Cloud
26.5.0.clCloud (Latest)
26.4.0.clCloud
26.3.0.clCloud
26.2.0.clCloud
Software
26.3.0.swSoftware (Latest)
10.10.0.swSoftware
10.1.0.swSoftware
GitHub

Filter types and application layers

ThoughtSpot Embedded provides a robust filtering framework for Liveboards, Answers, visualizations, and other ThoughtSpot objects with multiple filter types and layered application logic. Filters can be configured using Visual Embed SDK events and parameters at embed time, applied at runtime, or set through UI-driven workflows.

Overview🔗

The behavior of each filter type and the mechanism for setting filters can differ widely. There are different types of filters, which can be applied in the following order:

  1. Row-level security (RLS) Rules
    Rules are defined at the table level and applied during query generation to all objects derived from that table. Rules can be defined based on the logged-in user, their group memberships, or custom variables.
    RLS rules secure data and cannot be altered by the logged-in user.
    RLS rules can also be used, along with custom variables and the JSON Web Token (JWT) generated for the user, to implement Attribute-Based Access Control (ABAC).

  2. Data Model filters
    Models can have parameters, formulas, and filters.
    Embedding application users cannot affect the formulas or filters, which are always applied, but parameters used in a formula can be set by other methods.
    If the user can edit the parameter, use the runtime parameters layer to programmatically set its value.

  3. Runtime filters and Runtime Parameters
    You can define runtime filters and runtime parameters in the browser for a given object at load time. Filters and parameters can be set using the Visual Embed SDK, REST API, or URL query parameters and updated via host events in the Visual Embed SDK.

    Note

    • Runtime filters do not display as UI filter components.

    • The SDK processes at most 49 entries per embed. Any objects at index 50 or beyond are silently dropped without an error or warning. See Runtime filter limit for more information.

  4. Liveboard filters
    Liveboard filters apply to all visualizations on the Liveboard and are visible as UI components at the top of a Liveboard page. When a filter is clicked, a modal with filter options appropriate for the data type is displayed.
    Liveboard users can add or modify filters as needed. If you are embedding a Liveboard that includes preset filters, you can programmatically update, reset, or remove filters using the HostEvent.UpdateFilters.

  5. Liveboard cross filters
    Cross filters are ad-hoc filters based on user selection. These filters are used for brushing and linking Liveboard visualizations.
    Cross filters are supported only on attribute columns.

  6. Search query filters
    Set via the search query string in Answers and visualizations, not visible as UI filter components on a Liveboard, but can be viewed in Explore or Edit modes.
    The lowest layer of filters is defined in the search query for a given Answer or visualization on a Liveboard.
    The filter terms are saved as part of the search_query of the object, visible in TML.

Filter attributes🔗

When specifying a column for filtering, you must use the exact column name as defined in the model. Filters can be applied to string, number, boolean, Date, Datetime, and time data types. For the DATE and DATE_TIME data types, some filter types may require the date and time values to be specified in epoch time format.

All operations result in a WHERE clause being applied to the queries generated by ThoughtSpot, or no query being issued if the logic is always false.

A data filter object in ThoughtSpot typically includes the following attributes:

column, columnName, or columnId

The name of the column to filter on. For example, item type or product. The column value must match the actual column name in the ThoughtSpot model. If the model uses column aliases, use the base column name, not the alias. This attribute is defined as col1, col2, col3 in the object URLs and REST API requests, as columnName in the runtimeFilters array in the Visual Embed SDK. The filter object for host events in the SDK allows column or columnName.

If there are multiple columns with the same name, you can use the WORKSHEET_NAME::COLUMN_NAME format; for example, "(Sample) Retail - Apparel::city".

operator, oper, or op

The supported operators include:

OperatorDescriptionNumber of Values

EQ

equals

1

NE

not equal to

1

LT

less than

1

LE

less than or equal to

1

GT

greater than

1

GE

greater than or equal to

1

CONTAINS

contains

2

BEGINS_WITH

begins with

1

ENDS_WITH

ends with

1

BW_INC_MAX

between inclusive of the higher value

2

BW_INC_MIN

between inclusive of the lower value

2

BW_INC

between inclusive

2

BW

between non-inclusive

2

IN

is included in this list of values

multiple

NOT_IN

is not included in this list of values

multiple

values

An array of one or more values to filter by. The values must match the data type of the column.

type

Specifies the type for date filters. Supported types include YESTERDAY, TODAY, TOMORROW, EXACT_DATE, EXACT_DATE_RANGE, LAST_N_PERIOD, NEXT_N_PERIOD, THIS_PERIOD, PERIOD_TO_DATE, YEAR_ONLY, MONTH_YEAR, and QUARTER_YEAR.

Note

  • To specify the exact date or date range, you can use the date format such as YYYY-MM-DD, YYYY/MM/DD. If using epoch format, ensure that they are specified as numbers and not as strings. For example, [17423465599, 1754006399].

  • For PERIOD filters, you must include the datePeriod attribute in the date filter object.

  • For rolling date filters with Last <N> <Period> and Next <N> <Period>, you can specify whether to include or exclude the current period.

Applying filters before and after load🔗

Runtime filters can be applied at load via Visual Embed SDK, REST API, or URL parameters.

Liveboard filters cannot be applied at load. However, they can be updated using HostEvent.UpdateFilters in the SDK.

Search query filters can be applied at load by specifying them in the initial search query when embedding an Answer or Spotter session. For example, in Spotter embed, you can use the searchQuery property to set a pre-defined search (including filters) at load.

When you view an Answer or visualization in Edit mode, the filter UI for search query filters appears above the chart or table. These filters are not shown on a Liveboard. If a Liveboard filter is applied on the same column as a search query filter, the Liveboard filter overrides the search query filter values.

Cross filters🔗

Liveboard users can apply filters across all visualizations based on the current selection using the Filter menu option from the contextual menu. For more information, see Liveboard cross filter.

If the column already has a Liveboard filter and the user applies cross filters, the cross filter replaces the values in the currently applied Liveboard filter. If there is no Liveboard filter applied on a column and the user applies a cross filter, a new filter chip with cross filter values is displayed in the header area. This filter chip is removed when the cross filter is cleared.

Whenever any user action affects a cross filter, a EmbedEvent.CrossFilterChanged fires, which can then be used to trigger a specific action.

Updating filters using host events in Visual Embed SDK🔗

There is no programmatic way to adjust the filter values before loading the Liveboard, but there are events that can adjust the values after the Liveboard is rendered.

OpenFilter event🔗

If you have hidden the Liveboard header, you can trigger the action of opening a filter modal dialog using HostEvent.OpenFilter:

liveboardEmbed.trigger(HostEvent.OpenFilter,
 { columnId: '<column-GUID>'})

UpdateFilters event🔗

The HostEvent.UpdateFilters directly updates the values of an existing filter currently applied on a Liveboard:

liveboardEmbed.trigger(HostEvent.UpdateFilters, {
    filter: {
        column: "date",
        oper: "EQ",
        values: ["JULY","2023"],
        type: "MONTH_YEAR"
       }
   });

GetFilters and GetParameters events🔗

If you want to build your own filter UI within the embedding app, you can find out details of the Liveboard and runtime filters that are defined using the HostEvent.GetFilters. There is an equivalent HostEvent.GetParameters to get the currently set Parameter values:

const data = await liveboardEmbed.trigger(HostEvent.GetFilters);
console.log('data', data);

liveboardEmbed.trigger(HostEvent.GetParameters).then((parameter) => {
    console.log('parameters', parameter);
});

Note that HostEvent.GetFilters and HostEvent.GetParameters return a promise directly rather than taking a callback function as their second argument.

FilterChanged and ParameterChanged events🔗

You can also listen for the user’s interactions with the filters using the EmbedEvent.FilterChanged.

There is an equivalent EmbedEvent for Parameters called EmbedEvent.ParameterChanged.

UpdateCrossFilter event🔗

You can programmatically trigger an action to update a cross filter using HostEvent.UpdateCrossFilter:

liveboardEmbed.trigger(HostEvent.UpdateCrossFilter, {
     vizId: 'b535c760-8bbe-4e6f-bb26-af56b4129a1e',
     conditions: [
       { columnName: 'Category', values: ['mfgr#12','mfgr#14'] },
       { columnName: 'color', values: ['mint','hot'] },
   ],
});

Updating date filters via host events🔗

To update date filters in an embedded Liveboard, visualization, or saved answer, use HostEvent.UpdateFilters.

When updating filters using HostEvent.UpdateFilters, you must include the date filter type along with the time period to apply rolling or fixed time windows.

Note

  • For PERIOD filters, you must include the datePeriod attribute in the date filter object.

  • To specify the exact date or date range, you can use the date format such as YYYY-MM-DD, YYYY/MM/DD. If using epoch format, ensure that they are specified as numbers and not as strings. For example, [1743465599, 1754006399].

The following table lists the supported filter types and examples for each type:

TypeDescription

YESTERDAY

liveboardEmbed.trigger(HostEvent.UpdateFilters, {
    filter: {
        column: "date",
        oper: "EQ",
        values: [""],
        type: "YESTERDAY"
       }
   });

TODAY

liveboardEmbed.trigger(HostEvent.UpdateFilters, {
    filter: {
        column: "date",
        oper: "EQ",
        values: [""],
        type: "TODAY"
       }
   });

TOMORROW

liveboardEmbed.trigger(HostEvent.UpdateFilters, {
    filter: {
        column: "date",
        oper: "EQ",
        values: [""],
        type: "TOMORROW"
       }
   });

EXACT_DATE

Allows filtering column data to show details for the exact date, before or after the date. For example, to filter data for dates greater than 2023/07/31, specify 2023/07/31 as value, with the filter operator as GT.

liveboardEmbed.trigger(HostEvent.UpdateFilters, {
    filter: {
        column: "date",
        oper: "GT",
        values: ["2023-07-31"],
        type: "EXACT_DATE"
       }
   });

EXACT_DATE_RANGE

Specify the start date and end date in the values array. Ensure that the start date is lower than the end date. For example, "2023-01-31","2023-03-31".

liveboardEmbed.trigger(HostEvent.UpdateFilters, {
    filter: {
        column: "date",
        oper: "BW_INC",
        values: ["2023-01-31","2023-03-31"],
        type: "EXACT_DATE_RANGE"
       }
   });

LAST_N_PERIOD

Specify the period. You must include the datePeriod attribute based on the time period specified in the filter object. Valid values for datePeriod are SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, QUARTER, and YEAR. For example, to filter column data by last 2 weeks, set datePeriod to WEEK and values to 2.

liveboardEmbed.trigger(HostEvent.UpdateFilters, {
    filter: {
        column: "date",
        oper: "EQ",
        values: [2],
        datePeriod: "WEEK",
        type: "LAST_N_PERIOD",
        includeCurrentPeriod: true,
      }
   });

NEXT_N_PERIOD

Specify the period. You must include the datePeriod attribute based on the time period specified in the filter object. Valid values for datePeriod are SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, QUARTER, and YEAR. For example, to filter column data by next 2 months, set datePeriod to MONTH and values to 2.

liveboardEmbed.trigger(HostEvent.UpdateFilters, {
    filter: {
        column: "date",
        oper: "EQ",
        values: [2],
        datePeriod: "MONTH",
        type: "NEXT_N_PERIOD",
        includeCurrentPeriod: false,
      }
   });

THIS_PERIOD

Specify the period. You must include the datePeriod attribute based on the time period specified in the filter object. Valid values for datePeriod are SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, QUARTER, and YEAR.

liveboardEmbed.trigger(HostEvent.UpdateFilters, {
    filter: {
        column: "date",
        oper: "EQ",
        values: [""],
        datePeriod: "MONTH",
        type: "THIS_PERIOD"
      }
   });

PERIOD_TO_DATE

Specify the period. You must include the datePeriod attribute based on the time period specified in the filter object. Valid values for datePeriod are WEEK, MONTH, QUARTER, and YEAR.

liveboardEmbed.trigger(HostEvent.UpdateFilters, {
    filter: {
        column: "date",
        oper: "EQ",
        values: [""],
        datePeriod: "QUARTER",
        type: "PERIOD_TO_DATE"
      }
   });

YEAR_ONLY

Specify the year. For example, 2023.

liveboardEmbed.trigger(HostEvent.UpdateFilters, {
    filter: {
        column: "date",
        oper: "EQ",
        values: ["2023"],
        type: "YEAR_ONLY"
      }
   });

MONTH_YEAR

Specify the month and year in the values array. For example, "July","2023".

liveboardEmbed.trigger(HostEvent.UpdateFilters, {
    filter: {
        column: "date",
        oper: "EQ",
        values: ["July","2023"],
        type: "MONTH_YEAR"
      }
   });

QUARTER_YEAR

Specify the quarter and year in the values array. For example, "Q1","2023".

liveboardEmbed.trigger(HostEvent.UpdateFilters, {
    filter: {
        column: "date",
        oper: "EQ",
        values: ["Q1","2023"],
        type: "QUARTER_YEAR"
      }
   });

Overriding filters during Liveboard export via REST API🔗

The override_filters parameter on the Liveboard report API (POST /api/rest/2.0/report/liveboard) lets you programmatically override filters when exporting a Liveboard report. Filters specified here override any existing filters that are applied on the same columns in the Liveboard.

The override_filters value is a JSON array of filter objects, with each object targeting one column.

"override_filters": [
  { ... },
  { ... }
]
Important

  • The override_filters accepts a JSON array directly, not an object that wraps the array.

  • Specifying two or more filter objects that target the same date column returns the error, more than one filter objects are not allowed for date type column <column_name>. However, columns with other data type do not have this restriction. Multiple filter objects on the same non-date column are merged.

Filter object fields🔗

Each filter object in the JSON array has the following top-level fields:

FieldDescription

column_name

Name of the column to filter. The column_name field accepts the display name of the column as it appears in the Liveboard’s underlying data source. Matching is case-insensitive, so "Order Date", "ORDER DATE", and "order date" are all equivalent.

+ If there are multiple columns with the same name, you can use the WORKSHEET_NAME::COLUMN_NAME format; for example, "Sales Metrics::Order Date".

Note
 Column names must be used as qualifiers. Column GUIDs are not supported in the override_filters object.

generic_filter

Attribute or measure filter for columns with data type other than date or datetime. The date_filter and generic_filter attributes are mutually exclusive.

date_filter

Date filter definition for the columns with date or datetime data type. For information about the supported attributes, see Date filter parameters.

negate

Boolean. When true, inverts the filter match condition. Instead of returning rows that match the filter condition, it returns rows that do not match it.

Date filter parameters🔗

For date_filter objects, use the following table attributes as needed:

FieldDescription

type

String. Valid values for fixed date filters include:

  • EXACT_DATE - A specific calendar date, or an inequality relative to a date.

  • EXACT_DATE_RANGE - A date range between two bounds (inclusive).
    date_range.low_epoch, date_range.high_epoch, op: BW_INC only.

  • MONTH_YEAR - A specific month in a specific year.

  • QUARTER_YEAR - A specific quarter in a specific year.

  • YEAR_ONLY - An entire calendar year.

Valid values for rolling date filters include:

  • YESTERDAY - For previous calendar day.

  • TODAY - The current calendar day.

  • TOMORROW - The next calendar day.

  • THIS_PERIOD - The current period (for example, this quarter).

  • NEXT_PERIOD - The next single period (for example, next month).

  • LAST_N_PERIOD - The last N complete periods.

  • NEXT_N_PERIOD - The next N complete periods.

  • PERIOD_TO_DATE - From the start of the current period to now (for example, month-to-date).

The following types are not supported:

  • EXACT_TIME

  • EXACT_DATE_TIME

  • NOW

  • MONTH_ONLY

  • WEEKDAY_ONLY

  • QUARTER_ONLY

  • N_PERIOD_AGO

  • PERIOD_ONLY

datePeriod

For rolling date filters such as LAST_N_PERIOD, NEXT_N_PERIOD, LAST_PERIOD, NEXT_PERIOD, THIS_PERIOD, and PERIOD_TO_DATE, the datePeriod attribute is required. The datePeriod specifies the period.

Valid values for datePeriod include:

  • DAY - Calendar day

  • WEEK - Calendar week

  • MONTH - Calendar month

  • QUARTER - Calendar quarter

  • YEAR - Calendar year

  • HOUR - Hour (dateTime columns only)

  • MINUTE - Minute (datetime columns only)

  • SECOND - Second (datetime columns only)

    Note

    HOUR, MINUTE, and SECOND are valid only for columns that contain a time component. Use them only for the columns with DATE_TIME or TIME data type.

include_current_period

For LAST_N_PERIOD and NEXT_N_PERIOD, you can set the optional attribute include_current_period to include current day, week, month, quarter, year as specified in the datePeriod property. For example, if the current day is May 7, and you specify LAST_N_PERIOD with datePeriod: MONTH and number: 3, the include_current_period: true setting will include data for March, April, and May.

op

Comparison operator. Valid values depend on type.

  • Use EQ for YESTERDAY, TODAY, TOMORROW, PERIOD_TO_DATE, QUARTER_YEAR, MONTH_YEAR, YEAR_ONLY.

  • The LAST_PERIOD, NEXT_PERIOD, THIS_PERIOD, LAST_N_PERIOD, NEXT_N_PERIOD and EXACT_DATE filter types support EQ, LE, LT, GE, and GT.

  • For EXACT_DATE_RANGE, use BW_INC only.

number

Period count. Required when type is LAST_N_PERIOD or NEXT_N_PERIOD. Must be ≥ 0.

epoch

Required when type is EXACT_DATE.

low_epoch and high_epoch

Required for the EXACT_DATE_RANGE filter type. low_epoch must be lower than high_epoch.

year_name

Four-digit year as a string (for example, "2024"). Required for YEAR_ONLY, QUARTER_YEAR, and MONTH_YEAR.

quarter_name

Quarter identifier. Required for QUARTER_YEAR. Valid values are Q1, Q2, Q3, and Q4.

month_name

Name of the month in uppercase. Required for MONTH_YEAR.

Examples🔗

Generic filter example🔗

"override_filters":[
      {
         "column_name":"Item type",
         "generic_filter":{
            "op":"EQ",
            "values":[
               "Jackets",
               "Bags"
            ]
         },
         "negate":false
      },
      {
         "column_name":"Region",
         "generic_filter":{
            "op":"IN",
            "values":[
               "west",
               "midwest"
            ]
         },
         "negate":false
      }
   ]

Combining date and attribute filters🔗

"override_filters": [
  {
    "column_name": "Order Date",
    "date_filter": {
      "type": "LAST_N_PERIOD",
      "datePeriod": "MONTH",
      "number": 3,
      "op": "EQ"
    }
  },
  {
    "column_name": "Region",
    "generic_filter": {
      "op": "IN",
      "values": ["West", "East"]
    }
  }
]

Negated filter example🔗

"override_filters":[
   {
  "column_name": "Order Date",
  "negate": true,
  "date_filter": {
    "type": "QUARTER_YEAR",
    "op": "EQ",
    "quarter_name": "Q1",
    "year_name": "2026"
  }
}]

Datetime data type example🔗

"override_filters":[
   {
      "column_name":"Commit Date",
      "date_filter":{
         "datePeriod":"HOUR",
         "number":3,
         "type":"LAST_N_PERIOD",
         "op":"EQ"
      }
   }
]

Date filter examples🔗

Refer to the following table for examples of JSON object for date filters:

Date filter typeExample

YESTERDAY

"override_filters":[
   {
      "column_name":"Order Date",
      "date_filter":{
         "type":"YESTERDAY",
         "op":"EQ"
      }
   }
]

TODAY

"override_filters":[
   {
      "column_name":"Order Date",
      "date_filter":{
         "type":"TODAY",
         "op":"EQ"
      }
   }
]

TOMORROW

"override_filters":[
   {
      "column_name":"Order Date",
      "date_filter":{
         "type":"TOMORROW",
         "op":"EQ"
      }
   }
]

EXACT_DATE

"override_filters":[
   {
  "column_name": "Order Date",
  "date_filter": {
    "type": "EXACT_DATE",
    "op": "EQ",
    "epoch": 1710460800
  }
}]

EXACT_DATE_RANGE

"override_filters":[
{
  "column_name": "Order Date",
  "date_filter": {
    "type": "EXACT_DATE_RANGE",
    "op": "BW_INC",
    "date_range": {
      "low_epoch": 1704067200,
      "high_epoch": 1735689599
    }
  }
}]

LAST_N_PERIOD

"override_filters":[
   {
  "column_name": "Order Date",
  "date_filter": {
    "type": "LAST_N_PERIOD",
    "datePeriod": "MONTH",
    "number": 3,
    "op": "EQ",
    "include_current_period": true
  }
}]

NEXT_N_PERIOD

"override_filters":[
   {
  "column_name": "Order Date",
  "date_filter": {
    "type": "NEXT_N_PERIOD",
    "datePeriod": "MONTH",
    "number": 3,
    "op": "EQ",
    "include_current_period": true
  }
}]

THIS_PERIOD

"override_filters":[
   {
  "column_name": "Order Date",
  "date_filter": {
    "type": "THIS_PERIOD",
    "datePeriod": "QUARTER",
    "op": "EQ"
  }
}]

PERIOD_TO_DATE

"override_filters":[
   {
  "column_name": "Order Date",
  "date_filter": {
    "type": "PERIOD_TO_DATE",
    "datePeriod": "MONTH",
    "op": "EQ"
  }
}]

YEAR_ONLY

"override_filters":[
{
  "column_name": "Order Date",
  "date_filter": {
    "type": "YEAR_ONLY",
    "op": "EQ",
    "year_name": "2024"
  }
}]

MONTH_YEAR

"override_filters":[
{
  "column_name": "Order Date",
  "date_filter": {
    "type": "MONTH_YEAR",
    "op": "EQ",
    "month_name": "MARCH",
    "year_name": "2026"
  }
}]

QUARTER_YEAR

"override_filters":[
{
  "column_name": "Order Date",
  "date_filter": {
    "type": "QUARTER_YEAR",
    "op": "EQ",
    "quarter_name": "Q1",
    "year_name": "2024"
  }
}]

Updating runtime filters🔗

For information about runtime filters update, see Runtime filters documentation.

Removing filters🔗

To remove a specific filter, pass the empty values array, as shown in the following examples:

Runtime filters

liveboardEmbed.trigger(HostEvent.UpdateRuntimeFilters, [{
    columnName: "item type",
    operator: RuntimeFilterOp.EQ,
    values: [] // set an empty array to clear runtime filters
}]);

Liveboard filters

liveboardEmbed.trigger(HostEvent.UpdateFilters, {
    filters: [{
        column: "state",
        oper: "EQ",
        values: [] // set an empty array to clear filters
       }]
   });
Note

  • Setting empty values via HostEvent.UpdateFilters removes only the filter values; it does not remove or hide the filter chips from the Liveboard.

  • Clearing date filters by passing an empty values array is not supported.

Additional resources🔗

Refer to the following documentation for more information:

© 2026 ThoughtSpot Inc. All Rights Reserved.