Add support for Explore queries
This guide explains how to improve support for Explore to 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.
-
Create a file
ExploreQueryEditor.tsx
in thesrc
directory of your plugin, with the following content:import React from 'react'; import { ExploreQueryFieldProps } from '@grafana/data'; import { QueryField } from '@grafana/ui'; import { DataSource } from './DataSource'; import { MyQuery, MyDataSourceOptions } from './types'; export type Props = ExploreQueryFieldProps<DataSource, MyQuery, MyDataSourceOptions>; export default (props: Props) => { return ( <h2>My query editor</h2> ); };
-
Configure the plugin to use the
ExploreQueryEditor
.import ExploreQueryEditor from './ExploreQueryEditor';
export const plugin = new DataSourcePlugin<DataSource, MyQuery, MyDataSourceOptions>(DataSource) .setConfigEditor(ConfigEditor) .setQueryEditor(QueryEditor) .setExploreQueryField(ExploreQueryEditor);
-
Add a QueryField to
ExploreQueryEditor
.import { QueryField } from '@grafana/ui';
export default (props: Props) => { const { query } = props; const onQueryChange = (value: string, override?: boolean) => { const { query, onChange, onRunQuery } = props; if (onChange) { // Update the query whenever the query field changes. onChange({ ...query, queryText: value }); // Run the query on Enter. if (override && onRunQuery) { onRunQuery(); } } }; return ( <QueryField portalOrigin="mock-origin" onChange={onQueryChange} onRunQuery={props.onRunQuery} onBlur={props.onBlur} query={query.queryText || ''} placeholder="Enter a query" /> ); };
Support multiple Explore modes
Explore lets you query any data source, regardless of whether it returns metrics or logs. You can change which type of query you want to make, by setting the Explore mode.
The query modes that the plugin supports are defined in the plugin.json file.
The query mode is available on the props
object for both the query editor and the start page. For example, here’s how you can change the query editor based on the currently selected mode:
export default (props: Props) => {
const { query, exploreMode } = props;
switch (exploreMode) {
case ExploreMode.Metrics:
return <MetricsQueryField query={query} />;
case ExploreMode.Logs:
return <LogsQueryField query={query} />;
default:
return <p>Unsupported mode</p>;
}
}
For possible options, refer to PreferredVisualisationType.
Related Grafana video resources
Getting started with Grafana
Take a guided tour of Grafana and learn how to monitor a web service using Prometheus and Loki in this beginner-friendly webinar.
All about Grafana plugins: Visualizing disparate data sources in one place
Grafana Enterprise plugins are integrations with other commercial monitoring tools (such as Datadog, Splunk, New Relic, ServiceNow, Oracle, and Dynatrace) that are created, maintained, and supported by the Grafana Labs team.
Demo: Getting started with Grafana Enterprise and observability
Join the Grafana Labs team for a 30-minute demo of how to get started with the Grafana Stack, so you can go from zero to observability in just a few minutes.