Add support for Explore queries

This guide explains how to improve support for Explore in an existing data source plugin.

This guide assumes that you’re already familiar with how to Build a data source plugin.

With Explore, users can make ad-hoc queries without the use of a dashboard. This is useful when users want to troubleshoot or to learn more about the data.

Your data source already supports Explore by default, and will use the existing query editor for the data source. If you want to offer extended Explore functionality for your data source however, you can define a Explore-specific query editor.

Add a query editor for Explore

The query editor for Explore is similar to the query editor for the data source itself. In fact, you’ll probably reuse the same components for both query editors.

  1. Create a file ExploreQueryEditor.tsx in the src directory of your plugin, with the following content:

    1. import React from 'react';
    3. import { QueryEditorProps } from '@grafana/data';
    4. import { QueryField } from '@grafana/ui';
    5. import { DataSource } from './DataSource';
    6. import { MyQuery, MyDataSourceOptions } from './types';
    8. export type Props = QueryEditorProps<DataSource, MyQuery, MyDataSourceOptions>;
    10. export default (props: Props) => {
    11.   return <h2>My query editor</h2>;
    12. };

  2. Configure the plugin to use the ExploreQueryEditor.

    1. import ExploreQueryEditor from './ExploreQueryEditor';
    1. export const plugin = new DataSourcePlugin<DataSource, MyQuery, MyDataSourceOptions>(DataSource)
    2.   .setConfigEditor(ConfigEditor)
    3.   .setQueryEditor(QueryEditor)
    4.   .setExploreQueryField(ExploreQueryEditor);

  3. Add a QueryField to ExploreQueryEditor.

    1. import { QueryField } from '@grafana/ui';
    1. export default (props: Props) => {
    2.   const { query } = props;
    4.   const onQueryChange = (value: string, override?: boolean) => {
    5.     const { query, onChange, onRunQuery } = props;
    7.     if (onChange) {
    8.       // Update the query whenever the query field changes.
    9.       onChange({ ...query, queryText: value });
    11.       // Run the query on Enter.
    12.       if (override && onRunQuery) {
    13.         onRunQuery();
    14.       }
    15.     }
    16.   };
    18.   return (
    19.     <QueryField
    20.       portalOrigin="mock-origin"
    21.       onChange={onQueryChange}
    22.       onRunQuery={props.onRunQuery}
    23.       onBlur={props.onBlur}
    24.       query={query.queryText || ''}
    25.       placeholder="Enter a query"
    26.     />
    27.   );
    28. };

Selecting preferred visualisation

Explore should by default select a reasonable visualization for your data so users do not have to tweak and play with the visualizations and just focus on querying. This usually works fairly well and Explore can figure out whether the returned data is time series data or logs or something else.

If this does not work for you or you want to show some data in a specific visualization, add a hint to your returned data frame using the preferredVisualisationType meta attribute.

You can construct a data frame with specific metadata:

  1. const firstResult = new MutableDataFrame({
  2.     fields: [...],
  3.     meta: {
  4.         preferredVisualisationType: 'logs',
  5.     },
  6. });

For possible options, refer to PreferredVisualisationType.