Filter Transform

Edit this page

The filter transform removes objects from a data stream based on a provided filter expression or filter object.

{
  ...
  "transform": [
    {"filter": ...} // Filter Transform
     ...
  ],
  ...
}

Vega-Lite filter transforms must have the filter property.

Property Type Description
filter Filter

Required. The filter property must be either (1) a filter object for equal-filters, range-filters, one-of filters, or selection filters; (2) a Vega Expression string, where datum can be used to refer to the current data object; or (3) an array of filters (either objects or expression strings) that must all be true for a datum to pass the filter and be included.

Filter Expression

For a Vega Expression string, each datum object can be referred using bound variable datum. For example, setting filter to "datum.b2 > 60" would make the output data includes only items that have values in the field b2 over 60.

Filter Object

For a filter object, either a field or selection name must be provided. The former takes one of the filter operators (equal, range, or oneOf). Values of these operators can be primitive types (string, number, boolean) or a DateTime definition object to describe time. In addition, timeUnit can be provided to further transform a temporal field.

Equal Filter

Property Type Description
field String

Required. Field to be filtered.

equal String | Number | Boolean | DateTime

Required. The value that the field should be equal to.

timeUnit TimeUnit

Time unit for the field to be filtered.

For example, to check if the car_color field’s value is equal to "red", we can use the following filter:

{"filter": {"field": "car_color", "equal": "red"}}

Range Filter

Property Type Description
field String

Required. Field to be filtered

range Number[] | DateTime[]

Required. An array of inclusive minimum and maximum values for a field value of a data item to be included in the filtered data.

timeUnit TimeUnit

time unit for the field to be filtered.

Examples

  • {"filter": {"field": "x", "range": [0, 5]}} checks if the x field’s value is in range [0,5] (0 ≤ x ≤ 5).
  • {"filter": {"field": "x", "range": [null, 5]}} checks if the x field’s value is in range [-Infinity,5] (x ≤ 5).
  • {"filter": {"timeUnit": "year", "field": "date", "range": [2006, 2008] }} checks if the date’s value is between year 2006 and 2008.
  • {"filter": {"field": "date", "range": [{"year": 2006, "month": "jan", "date": 1}, {"year": 2008, "month": "feb", "date": 20}] }} checks if the date’s value is between Jan 1, 2006 and Feb 20, 2008.

One-Of Filter

Property Type Description
field String

Required. Field to be filtered

oneOf String[] | Number[] | Boolean[] | DateTime[]

Required. A set of values that the field’s value should be a member of, for a data item included in the filtered data.

timeUnit TimeUnit

time unit for the field to be filtered.

For example, {"filter": {"field": "car_color", "oneOf":["red", "yellow"]}} checks if the car_color field’s value is "red" or "yellow".

Selection Filter

Property Type Description
selection String | Object

Required. Filter using a selection name.

For example, with {"filter": {"selection": "brush"}}, only data values that fall within the selection named brush will remain in the dataset as shown below.

All selection composition can be used here as well. For instance, {"filter": {"selection": {"and": ["alex", "morgan"]}}} filters for data values that are within both the alex and morgan selections.