Filters overview
26.4.0.cl
Cloud (Latest)
26.3.0.cl
Cloud
26.2.0.cl
Cloud
10.15.0.cl
Cloud
10.10.0.sw
Software (Latest)
10.1.0.sw
Software

Filters overview

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 the Visual Embed SDK events and parameters when embedding, applied at runtime, or via UI-driven workflows.

Filter types and application layers🔗

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

  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 the 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".

oper or operator

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, [1743465599, 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 to the same column as a search query filter, the Liveboard filter will override 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 to 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🔗

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 the target of an existing filter that’s 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🔗

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 a 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:

TypeDescriptionExample

YESTERDAY

Specify the type as YESTERDAY.

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

TODAY

Specify the type as TODAY.

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

TOMORROW

Specify the type as 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"
      }
   });

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", // columnName is also a valid parameter.
        oper: "EQ",
        values: [] // set an empty array to clear filters
       }]
   });

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

© 2026 ThoughtSpot Inc. All Rights Reserved.