Documentation Plugins MQTT Query editor

MQTT query editor

This document explains how to use the MQTT query editor to subscribe to topics and visualize streaming data in your Grafana panels.

Before you begin

• Ensure you have configured the MQTT data source.
• Verify the connection is working by checking that Save & test shows MQTT Connected.

Key concepts

If you’re new to MQTT, here are key terms used in this documentation.

Create a query

To subscribe to an MQTT topic:

1. Select the MQTT data source.
2. In the Topic field, enter the MQTT topic you want to subscribe to (for example, home/bedroom/temperature).
3. The panel begins streaming data as soon as the topic is set.

Each query subscribes to a single topic filter. To receive messages from multiple topics with one query, use wildcards (for example, home/#). To subscribe to unrelated topics, add additional queries to the panel.

Topic wildcards

The MQTT data source supports standard MQTT wildcard characters in topic filters.

For the full specification on topic names and filters, refer to the MQTT v3.1.1 specification.

Supported data types

The plugin automatically detects the data type of each incoming message and creates appropriate data frame fields. The following types are supported.

When the plugin receives a JSON object, it extracts each top-level key into a separate field. For example, a message with {"temperature": 23.5, "humidity": 60} creates two fields: temperature (Float64) and humidity (Float64).

Work with JSON data

For flat JSON objects, each top-level key becomes its own field automatically. Nested objects and arrays are stored as JSON-typed fields.

To extract values from nested JSON structures, use the Extract fields transformation:

1. Open the panel editor.
2. Click the Transform data tab.
3. Select Extract fields.
4. Choose the JSON field you want to extract values from.

For more information, refer to Transform data.

Understand timestamps

The plugin attaches a timestamp to each message when it arrives at the Grafana server. These timestamps reflect when Grafana received the message, not when the event occurred at the source.

If your message payloads include a timestamp field, use the Convert field type transformation to parse it:

1. Open the panel editor.
2. Click the Transform data tab.
3. Select Convert field type.
4. Choose the field that contains the timestamp.
5. Set the target type to Time.

For more information, refer to Convert field type.

Streaming behavior

The MQTT data source uses the Grafana Live streaming API to push data to panels in real time.

The data flow works as follows:

1. When a panel with an MQTT query is opened, Grafana subscribes to the specified MQTT topic on the broker.
2. Incoming messages accumulate in a buffer on the backend.
3. At each query interval, the buffered messages are converted into a data frame and pushed to the panel.
4. When the panel is closed or the query is removed, Grafana unsubscribes from the topic.

If multiple panels subscribe to the same topic, the plugin shares a single MQTT subscription and routes the data to each panel independently.