Adhoc filters

Adhoc filters provide a very powerful way to dynamically change the scope or filtering of queries in your scene view. Unlike variables, which usually control a predefined label or dimension, with adhoc filters the user can control which keys (labels) to filter on.

Automically applied to queries

Adhoc filters are supported directly by many data sources. This means they handle automatically applying filters to all the queries that match the data source you specify on the AdHocFiltersVariable.

Step 1. Create the AdHocFiltersVariable

Start by defining the AdHocFiltersVariable.

const filtersVar = new AdHocFiltersVariable({
  name: 'Filters',
  datasource: {
    type: 'prometheus',
    uid: '<PROVIDE_GRAFANA_DS_UID>',
  },
  // You don't need to set baseFilters, but they're useful if you want to limit label suggestions to only those you deem relevant for the scene.
  // These are not shown in the UI.
  baseFilters: [{ key: '__name__', operator: '=', value: 'ALERTS', condition: '' }],
  // If you want to have any default filters added by default, you can specify those here.
  filters: [],
});

Next, you add this filtersVar to variables array of your SceneVariableSet.

Example:

const scene = new EmbeddedScene({
  $variables: new SceneVariableSet({ variables: [filterVar] }),
  ...
});

How automatic mode works

The behavior of AdHocFiltersVariable is controlled by the applyMode option. When set to auto, which is the default, any change to any filter will automatically re-trigger all SceneQueryRunners in the scene that are configured with the same data source UID as the one of the AdHocFiltersVariable. The data source implementation will handle modifying all the queries to include the current filters.

Customize the tag and value suggestions

By default the tag (label) suggestions will come from the data source implementation of getTagKeys. You should take existing filters and baseFilters into account when fetching suggestions so that filters can also impact the suggested tags and values of other filters. This behavior that other filters are taken into account is new and not all data sources support it yet.

Values are fetched from the data source implementation of getTagValues. Both tag keys and tag values can be customized with the two state properties: getTagKeysProvider and getTagValuesProvider.

Example:

const filterSet = new AdHocFiltersVariable({
  name: 'Filters',
  datasource: {
    type: 'prometheus',
    uid: '<PROVIDE_GRAFANA_DS_UID>',
  },
  getTagKeysProvider: () => {
    return Promise.resolve({
      replace: true,
      values: [
        { text: 'service_namespace', value: 'service_namespace' },
        { text: 'technology', value: 'technology' },
      ],
    });
  },
  getTagValuesProvider: (set: AdHocFilterSet, filter: AdHocVariableFilter) => {
    // Customize value look up
    return Promise.resolve({ replace: false, values: [] });
  },
});

With these two functions, you can completely customize the key and value look up. With the replace property on the return object, you can control if the result should either replace the default implementation (results) or augment the default result with, for example, keys/labels from another data source.

Manual mode

If you don't want filters to be applied to all queries of the same data source as that of the AdHocFiltersVariable and want more control over which queries it's applied to, you can set applyMode to manual and then use the filters however you want. You could, for example, subscribe to the AdHocFiltersVariable state and then use the filters to modify the scene in some interesting way.

An alternative way to the filters as a normal variable inside query expressions.

Example:

$variables: new SceneVariableSet({
  variables: [
    new AdHocFiltersVariable({
      name: 'filters',
      applyMode: 'manual',
      datasource: { uid: 'gdev-prometheus' },
      filters: [{ key: 'job', operator: '=', value: 'grafana', condition: '' }],
    }),
  ],
}),

With this variable, you can now use the filters easily in specific queries by using it as a normal variable.

Example:

new SceneQueryRunner({
  datasource: { uid: 'gdev-prometheus' },
  queries: [
    {
      refId: 'A',
      expr: 'ALERTS{$filters}',
      format: 'table',
      instant: true,
    },
  ],
});

Such configured query contains the variable expression $filters. You can change the name of the variable. By default, the AdHocFiltersVariable will render the filters to valid Prometheus label filter expressions separated by a comma.