Filter Transform

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

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

Vega-Lite filter transforms must have the filter property describing the predicate for the filtering condition.

Filter Expression

For an 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.

Field Predicate

For a field predicate, a field must be provided along with one of the predicate properties: equal, lt (less than), lte (less than or equal), gt (greater than), gte(greater than or 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.

Field Equal Predicate

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"}}

Field Less Than Predicate

For example, to check if the height field’s value is less than 180, we can use the following filter:

{"filter": {"field": "height", "lt": 180}}

Field Less Than or Equals Predicate

For example, to check if the Year field’s value is less than or equals to "2000", we can use the following filter:

{"filter": {"timeUnit": "year", "field": "Year", "lte": "2000"}}

Field Greater Than Predicate

To check if the state field’s value is greater than "Arizona" by string comparison, we can use the following filter: (Note: Standard Javascript string comparison is done, ie., “A” < “B”, but “B” < “a”)

{"filter": {"field": "state", "gt": "Arizona"}}

Field Greater Than or Equals Predicate

For example, to check if the height field’s value is greater than or equals to 0, we can use the following filter:

{"filter": {"field": "height", "gte": 0}}

Field Range Predicate

Examples

• {"filter": {"field": "x", "range": [0, 5]}} checks if the x field’s value is in range [0,5] (0 ≤ 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.

Field One-Of Predicate

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

Field Valid Predicate

For example, {"filter": {"field": "car_color", "valid": true}} checks if the car_color field’s value is valid meaning it is both not null and not NaN.

Selection Predicate

For a selection predicate, a selection name must be provided.

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.

When you use a selection filter to dynamically filter the data, scale domains may change, which can lead to jumping titles. To prevent this, you can fix the minExtent of the axis whose scale domain changes. For example, to set the minimum extent to 30, add {"axis": {"minExtent": 30}} to the corresponding encoding.