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
,
AttributeElements
,
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 ofIAttribute
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 ofIAttribute
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 formatYYYY-MM-DD
.to
is the end date in the formatYYYY-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:
Value | Description |
---|---|
"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:
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).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 be400
, but it will still be included in the visualization with a filter that filters out the values smaller than or equal to400
.- 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
islocalIdentifier
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 thanvalue
."GREATER_THAN_OR_EQUAL_TO"
: The measure value is greater thanvalue
or equal tovalue
."LESS_THAN"
: The measure value is less thanvalue
."LESS_THAN_OR_EQUAL_TO"
: The measure value is less thanvalue
or equal tovalue
."EQUAL_TO"
: The measure value is equal tovalue
."NOT_EQUAL_TO"
: The measure value is not equal tovalue
.
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
islocalIdentifier
of the measure to filter. You can specifylocalIdentifier
explicitly or pass an instance of the measure, and the factory will extractlocalIdentifier
for you.operator
is one of the following:"BETWEEN"
: The measure value is between thefrom
andto
values (including the boundaries)."NOT_BETWEEN"
: The measure value is not between thefrom
andto
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 propertyformat
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
islocalIdentifier
of the measure to filter. You can specifylocalIdentifier
explicitly or pass an instance of the measure, and the factory will extractlocalIdentifier
for you.attributesOrLocalIds
is an array oflocalIdentifier
strings of the attributes that defines the ranking granularity. You can specifylocalIdentifier
explicitly or pass an instance of the attribute, and the factory will extractlocalIdentifier
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 modifySimpleMeasure
function:
modifyMeasure(measure, modifications)
- When both the measure filter of the
DateFilter
type and the global filter of theDateFilter
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 theDateFilter
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 Ldm from "./ldm/full";
const californiaSales = modifySimpleMeasure(
Ldm.$TotalSales,
m => m.filters(newPositiveAttributeFilter(Ldm.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 Ldm from "./ldm/full";
const filters = [
newPositiveAttributeFilter(Ldm.StateName, ["California"]),
newPositiveAttributeFilter(Ldm.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 thefilters
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 Ldm from "./ldm/full";
const style = { height: 300 };
<div style={style}>
<ColumnChart
measures={[Ldm.$TotalSales]}
filters={[
newNegativeAttributeFilter(
Ldm.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.
Attribute Elements component filter
Pass a custom children function to the Attribute Elements component. This function will receive a parameter with a list of attribute values for the selected attribute. You can use it to render any custom attribute filter.
See the live example.