Controls

A control object holds an input value, such as the selected region in a dropdown. Map it to one or more queries, and its value flows into those queries when the app runs.

There are two kinds of control:

• Filters hold a condition on a field, such as region is APAC.
• Date drills hold a date grain, such as month or week.

Creating and mapping a controlCopy Anchor Link

Create a filter control, map it to a query, then update the control when the user changes the dropdown:

const region = app.createFilter('region', { dataset: 'sales', field: 'users.region' })
app.mapControl(region, trend, { field: 'users.region' })

document.querySelector('#region').addEventListener('change', (event) => {
  region.setCondition({ operator: 'is', values: [event.target.value] })
  app.execute()
})

The dropdown is ordinary HTML. The control carries its selected value into the mapped query, and your subscription redraws the chart with the updated result.

Explicit mappingsCopy Anchor Link

A control affects only the queries it is mapped to. Nothing cascades implicitly, so you can tell which views a control changes by reading the mappings.

A filter on users.region affects no query until you map it to each query it should reach:

app.mapControl(region, byRegion, { field: 'users.region' })
app.mapControl(region, trend, { field: 'users.region' })

The mapped field does not need to be selected by the query.

Conditions on aggregatesCopy Anchor Link

Pass aggregation to apply the condition to the aggregate instead of to each row. anfra puts it in the query's having. aggregation accepts 'sum', 'avg', 'min', 'max', 'count', 'count distinct', 'median', 'stdev', 'stdevp', 'var' and 'varp'. Any other value throws a ValidationError.

A "revenue over 1000" filter looks like this:

app.mapControl(minRevenue, byRegion, { field: 'orders.amount', aggregation: 'sum' })

A mapping onto a bare dataset metric is an aggregate condition already, so it takes no aggregation.

Field namesCopy Anchor Link

field follows the field reference rules. A mapControl field is not checked until the query runs, so a typo arrives as a QueryError.

RelatedCopy Anchor Link

• Filters: operators, options and defaults.
• Date drill: switch a query's date grain.
• Cross-filtering: filter a query by rows selected in another.