Define a query

Most data sources offer a way to query specific data. MySQL and PostgreSQL use SQL, while Prometheus has its own query language, called PromQL. No matter what query language your databases are using, Grafana lets you build support for it.

Add support for custom queries to your data source, by implementing a your own query editor, a React component that enables users to build their own queries, through a user-friendly graphical interface.

A query editor can be as simple as a text field where the user edits the raw query text, or it can provide a more user-friendly form with drop-down menus and switches, that later gets converted into the raw query text before it gets sent off to the database.

Define the query model

The first step in designing your query editor is to define its query model. The query model defines the user input to your data source.

We want to be able to control the frequency of the sine wave, so let’s add another property.

1. Add a new number property called frequency to the query model:

   src/types.ts

   export interface MyQuery extends DataQuery {
     queryText?: string;
     constant: number;
     frequency: number;
   }
   

2. Set a default value to the new frequency property:

   export const defaultQuery: Partial<MyQuery> = {
     constant: 6.5,
     frequency: 1.0,
   };
   

Bind the model to a form

Now that you’ve defined the query model you wish to support, the next step is to bind the model to a form. The FormField is a text field component from grafana/ui that lets you register a listener which will be invoked whenever the form field value changes.

1. Add a new form field to the query editor to control the new frequency property.

   QueryEditor.tsx

   const { queryText, constant, frequency } = query;
   

   <FormField
     width={4}
     value={frequency}
     onChange={this.onFrequencyChange}
     label="Frequency"
     type="number"
   />
   

2. Add a event listener for the new property.

   onFrequencyChange = (event: ChangeEvent<HTMLInputElement>) => {
     const { onChange, query, onRunQuery } = this.props;
     onChange({ ...query, frequency: parseFloat(event.target.value) });
     // executes the query
     onRunQuery();
   };
   

   The registered listener, onFrequencyChange, calls onChange to update the current query with the value from the form field.

   onRunQuery(); tells Grafana to run the query after each change. For fast queries, this is recommended to provide a more responsive experience.

Use the property

The new query model is now ready to use in our query method.

1. In the query method, use the frequency property to adjust our equation.

   frame.add({ time: from + t, value: Math.sin((2 * Math.PI * query.frequency * t) / duration) });
   

Configure your data source

To access a specific data source, you often need to configure things like hostname, credentials, or authentication method. A config editor lets your users configure your data source plugin to fit their needs.

The config editor looks similar to the query editor, in that it defines a model and binds it to a form.

Since we’re not actually connecting to an external database in our sine wave example, we don’t really need many options. To show you how you can add an option however, we’re going to add the wave resolution as an option.

The resolution controls how close in time the data points are to each other. A higher resolution means more points closer together, at the cost of more data being processed.

Define the options model

1. Add a new number property called resolution to the options model.

   types.ts

   export interface MyDataSourceOptions extends DataSourceJsonData {
     path?: string;
     resolution?: number;
   }
   

Bind the model to a form

Just like query editor, the form field in the config editor calls the registered listener whenever the value changes.

1. Add a new form field to the query editor to control the new resolution option.

   ConfigEditor.tsx

   <div className="gf-form">
     <FormField
       label="Resolution"
       onChange={this.onResolutionChange}
       value={jsonData.resolution || ''}
       placeholder="Enter a number"
     />
   </div>
   

2. Add a event listener for the new option.

   onResolutionChange = (event: ChangeEvent<HTMLInputElement>) => {
     const { onOptionsChange, options } = this.props;
     const jsonData = {
       ...options.jsonData,
       resolution: parseFloat(event.target.value),
     };
     onOptionsChange({ ...options, jsonData });
   };
   

   The onResolutionChange listener calls onOptionsChange to update the current options with the value from the form field.

Use the option

1. Create a property called resolution to the DataSource class.

   export class DataSource extends DataSourceApi<MyQuery, MyDataSourceOptions> {
     resolution: number;
   
     constructor(instanceSettings: DataSourceInstanceSettings<MyDataSourceOptions>) {
       super(instanceSettings);
   
       this.resolution = instanceSettings.jsonData.resolution || 1000.0;
     }
   
     // ...
   

2. In the query method, use the resolution property to calculate the step size.

   src/DataSource.ts

   const step = duration / this.resolution;