8.12.0

Filter Visual Components

This article provides examples of filtering visual components by attribute, date, and measure values.

All visualization components can be filtered using the filters prop. The filters prop is an array of attribute filters and date filters. You can make the filters dynamic with the AttributeFilter, DateFilter, MeasureValueFilterDropdown, and RankingFilterDropdown components.

Both global filters and filters set on measures are always interpreted as an intersection of all individual filters (f1 AND f2 AND f3...).

You can conveniently create all the filters described here using the factory functions exported by the @gooddata/sdk-model package.

Attribute filter

All filters are defined using the displayForm identifiers. Attribute filters (both positiveAttributeFilter and negativeAttributeFilter) can be defined to match attribute elements by their value (this is the default) or by their URI - essentially a primary key.

When using text filters, remember to escape special characters " and \. If you want to filter out this exact string: Foo\", enter it as 'Foo\\"' or "Foo\\\"", which will result in "Foo\\\"". The browser will send "Foo\\\"" to the server where "Foo\\\"" will be queried as Foo\".

NOTE: Single quotes and double quotes behave differently while escaping characters.

Positive attribute filter

A positive attribute filter lists only those items whose attribute elements match the inElements array. Use the newPositiveAttributeFilter factory function to create a new positive attribute filter:

newPositiveAttributeFilter(displayFormId, inElements)

where:

  • displayFormId is the identifier of the display form to filter by. You can specify the identifier explictly as a string or pass an instance of IAttribute generated by catalog-export.

  • inElements is either an array of attribute element values to filter by or an object such as {uris: [<uri-1>, <uri-2>, ...]} containing the URI of the attribute element URIs.

Negative attribute filter

A negative attribute filter lists only those items whose attribute elements are not included in the notInElements array. Use the newNegativeAttributeFilter factory function to create a new negative attribute filter:

newNegativeAttributeFilter(displayFormId, notInElements)

where:

  • displayFormId is the identifier of the display form to filter by. You can specify the identifier explicitly as a string or pass an instance of IAttribute generated by catalog-export.

  • notInElements is either an array of attribute element values to filter by or an object such as {uris: [<uri-1>, <uri-2>, ...]} containing the URI of the attribute element URIs.

Date filter

Absolute date filter

An absolute date filter shows data that falls within a defined time range. Use the newAbsoluteDateFilter factory functions to create a new absolute date filter:

newAbsoluteDateFilter(dateDataSet, from, to)

where:

  • dateDataSet is the identifier of date dataset to use for filtering.
  • from is the start date in the format YYYY-MM-DD.
  • to is the end date in the format YYYY-MM-DD.

Relative date filter

A relative date filter shows data that falls within a time range defined relatively to the current date. Filter granularity (granularity) defines how a time range can be broken down to smaller time units (week, month, quarter, and so on).

granularity can be set to:

ValueDescription
"GDC.time.date"Days
"GDC.time.week"Weeks starting on Monday
"GDC.time.week_us"Weeks starting on Sunday
"GDC.time.month"Months
"GDC.time.quarter"Quarters of a year
"GDC.time.year"Years

The from and to properties set the number of granularity units (for example, weeks) before or after the current date. That is, from and to define the filter range.

  • 0 for the current day, week, month, quarter, or year (depending on the chosen granularity)
  • -1 for the previous period
  • -n for the nth previous period

Use the newRelativeDateFilter factory functions to create a new relative attribute filter:

newRelativeDateFilter(dateDataSet, granularity, from, to);

where:

  • dateDataSet is the identifier of date data set to use for filtering.
  • granularity is one of the supported values.
  • from is the relative start time.
  • to is the relative end time.

NOTE: If you use date filters by weeks and compare the data to the previous period or the same period of the last year in those filters, you have to enable the GoodData platform to properly process such week filters. To do so, complete the following steps:

  1. Switch the version of the Extensible Analytics Engine to 3.

    To do so, set the xae_version platform setting to 3 (see Configure Various Features via Platform Settings).

  2. Migrate the Date datasets in your workspace to the urn:custom_v2:date date dimension.

    To do so, see "Migrate from a Legacy Date Dimension to urn:custom_v2:date" in Manage Custom Date Dimensions.

Relative filter examples

Last 7 days (yesterday and 6 days before):

newRelativeDateFilter("<date-dataset-identifier>", "GDC.time.date", -7, -1);

Last 12 months including the current month

newRelativeDateFilter("<date-dataset-identifier>", "GDC.time.month", -11, 0);

Last quarter only

newRelativeDateFilter("<date-dataset-identifier>", "GDC.time.quarter", -1, -1);

Filter by a measure value

You can filter a visualization by the value of a measure. You can filter only the measures that are present in the visualization, on the granularity defined by the attributes in the visualization.

NOTES:

  • The numbers rendered by a visualization are often rounded up/down. However, filters are applied to the original exact numbers (those before rounding), and that may lead to unexpected results. For example, the number 400.01 rounded to a whole number would be 400, but it will still be included in the visualization with a filter that filters out the values smaller than or equal to 400.
  • A rollup total is not supported in visualizations with measure value filters. Such visualizations are not rendered, and the error message is shown instead.

Filtering by comparing a measure value to a specific value

When you filter a measure by comparing its value to some predefined value, the filter shows only the data whose measure matches a comparison condition.

You can create comparative measure value filters using the newMeasureValueFilter factory function:

newMeasureValueFilter(measureOrLocalId, operator, value, treatNullValuesAs)

where:

  • measureOrLocalId is localIdentifier of the measure to filter. You can specify the localIdentifier explicitly or pass an instance of measure and the factory will extract the localIdentifier for you.

  • operator is one of the following:

    • "GREATER_THAN": The measure value is greater than value.
    • "GREATER_THAN_OR_EQUAL_TO": The measure value is greater than value or equal to value.
    • "LESS_THAN": The measure value is less than value.
    • "LESS_THAN_OR_EQUAL_TO": The measure value is less than value or equal to value.
    • "EQUAL_TO": The measure value is equal to value.
    • "NOT_EQUAL_TO": The measure value is not equal to value.

  • value is the measure value to filter against.

  • treatNullValuesAs is optional; by default, any filter condition filters out null values. If you want a filter condition to treat null values as a number and to include them in the filtering process, use this parameter.

Filtering by comparing a measure value to a value range

When you filter a measure by comparing its value against some predefined range of values, the filter shows only the data whose measure matches a range condition.

You can create comparative measure value filters using the newMeasureValueFilter factory function:

newMeasureValueFilter(measureOrLocalId, operator, from, to, treatNullValuesAs)

where:

  • measureOrLocalId is localIdentifier of the measure to filter. You can specify localIdentifier explicitly or pass an instance of the measure, and the factory will extract localIdentifier for you.

  • operator is one of the following:

    • "BETWEEN": The measure value is between the from and to values (including the boundaries).
    • "NOT_BETWEEN": The measure value is not between the from and to values (excluding the boundaries).

  • from is the start boundary.

  • to is the end boundary.

  • treatNullValuesAs is optional; by default, any filter condition filters out null values. If you want a filter condition to treat null values as a number and to include them in the filtering process, use this parameter.

Filtering by a percentage measure

You can use several methods to get measures to be rendered as a percentage. Depending on the method you used, measure value filters applied to such measures behave differently.

Measures shown in %

When a visualization is filtered by a measure that is shown in % (that is, the measure has computeRatio=true), the filter value is based on the range of the actual measure values and not on the percentage values rendered by the visualization.

For example, if the visualization renders the values 100, 200, and 700 as 10%, 20%, and 70%, the filter that filters out the first two values would use a comparison condition with the operator GREATER_THAN and the condition value 200. The result would contain only the value 700 rendered as 100% in the visualization.

The reason is that the percentage values are always computed for the current execution result. By applying the measure value filter, the result changes and so the percentage values will change as well. That would result in the filter and the values displayed to have a different scale which would be confusing. For instance, accepting only values lower than 50% could still produce insights with values higher than 50%.

Measures in charts stacked to 100%

When a visualization is filtered by a measure that is stacked to 100%, the filter value is based on the range of the actual measure values and not on the percentage values rendered by the visualization.

The example and the reason behind this behavior are similar to those described above for the measures shown in %.

Measures formatted in %

When a visualization is filtered by a measure that is formatted in %, the filter value is based on the percentage values rendered by the visualization and not on the range of the actual measure values.

For example, if the visualization renders the formatted values 100%, 20%, and 3%, the filter that filters out only one value would use the operator NOT_EQUAL_TO and the filter values 1, 0.2, or 0.03, respectively.

This applies to the following types of measures:

  • Measures that have the percentage format set by the format measure property
  • Calculated measures with the percentage format set in the metadata catalog
  • Arithmetic measures with the change operator that has the percentage property format set

Ranking filter

A ranking filter shows the data from a set of the highest or lowest ranked values of an attribute based on the ranking criteria that you establish. You can filter only the measures that are present in the visualization, on the granularity defined by the attributes in the visualization.

NOTES:

  • A rollup total and measures that are shown in % (that is, the measures with computeRatio=true property) are not supported in visualizations with ranking filters. Such visualizations are not rendered, and the error message is shown instead.
  • Ranking filters do not affect visualization sorting. For example, when you filter to get top three highest values of a measure, the visualization keeps its sorting order, which may or may not have been applied to the filtered measure.

When you apply a ranking filter to a measure, the filter shows only the data whose measure values match the condition. More records than requested can be returned if they share the same value.

You can create ranking filters using one of the following newRankingFilter factory functions:

newRankingFilter(measureOrLocalId, operator, value)

newRankingFilter(measureOrLocalId, attributesOrLocalIds, operator, value)

where:

  • measureOrLocalId is localIdentifier of the measure to filter. You can specify localIdentifier explicitly or pass an instance of the measure, and the factory will extract localIdentifier for you.

  • attributesOrLocalIds is an array of localIdentifier strings of the attributes that defines the ranking granularity. You can specify localIdentifier explicitly or pass an instance of the attribute, and the factory will extract localIdentifier for you. This parameter is optional. If it is not specified, the ranking behaves as if you would enter the list of all attributes in the visualization.

  • operator is one of the following:

    • "TOP" returns records with the highest values of the filtered measure for the granularity specified by the filter attributes.
    • "BOTTOM" returns records with the lowest values of the filtered measure for the granularity specified by the filter attributes.

  • value is the number of the ranked records to return. The number must be a positive integer (1, 2, 3, ...).

Filter set on a specific measure

Applying a filter to a specific measure is helpful when you have duplicate measures with different filters. You can apply filters to measures created from facts or MAQL metrics using the modifySimpleMeasurefunction:

modifyMeasure(measure, modifications)
  • When both the measure filter of the DateFilter type and the global filter of the DateFilter type are set with the same date dimension, the measure date filter overrides the global date filter for this measure (global date filters are still applied to other measures that do not have a measure date filter defined).
  • When the measure filter of the DateFilter type and the global filter of the DateFilter type are set with different date dimensions, the filters are interpreted as an intersection of those filters (f1 AND f2).
import { ColumnChart } from "@gooddata/sdk-ui-charts";
import { modifySimpleMeasure, newPositiveAttributeFilter } from "@gooddata/sdk-model";
import * as Md from "./md/full";

const californiaSales = modifySimpleMeasure(
                            Md.$TotalSales,
                            m => m.filters(newPositiveAttributeFilter(Md.StateName, ["California"])).alias("California Sales")
                        );

const style = { height: 300 };

<div style={style}>
    <ColumnChart
        measures={[ californiaSales ]}
    />
</div>

Filter examples

InsightView component filter

import "@gooddata/sdk-ui-ext/styles/css/main.css";
import { InsightView } from "@gooddata/sdk-ui-ext";
import { newPositiveAttributeFilter } from "@gooddata/sdk-model";
import * as Md from "./md/full";

const filters = [
    newPositiveAttributeFilter(Md.StateName, ["California"]),
    newPositiveAttributeFilter(Md.IsKidsItem, ["true"])
];

<div style={{ height: 400, width: 600 }}>
    <InsightView
        insight="<visualization-identifier>"
        filters={filters}
    />
</div>

If you reference a saved visualization with active filters and set the filters prop on the InsightView component, both sets of filters will be merged using the following rules:

  • If the active filter in the saved visualization and the filter defined with the filters prop have the same object qualifier (identifier or URI), the filter defined with the filters prop overwrites the active filter in the saved visualization.
  • All other filters, both saved and from the filters prop, will be added.

Chart component filter

import { ColumnChart } from "@gooddata/sdk-ui-charts";
import { newNegativeAttributeFilter } from "@gooddata/sdk-model";
import * as Md from "./md/full";

const style = { height: 300 };

<div style={style}>
    <ColumnChart
        measures={[Md.$TotalSales]}
        filters={[
            newNegativeAttributeFilter(
                Md.StateName,
                { uris: ["/gdc/md/xms7ga4tf3g3nzucd8380o2bev8oeknp/obj/2210/elements?id=6340116"] })
        ]}
    />
</div>

Attribute Filter component filter

The Attribute Filter component renders a dropdown list of all values of the selected attribute. The Attribute Filter component has the onApply function property. This function is called when the user clicks the Apply button in the filter dropdown. The function receives an attribute filter with either selected attribute values (positive filter) or not selected attribute values (negative filter).

See the live example.

← Specify Table TotalsCreate a Custom Attribute Filter →