---
title: Define DataHub Queries
slug: solutions/define-datahub-queries
docTags: 
createdAt: 2025-03-13T17:47:29.124Z
---

You can define a database query from your *Litmus Add-ins* in a structured, sequential way. The process resembles the syntax familiar to queries in dashboard tools like *Grafana *and executes within an **Excel-integrated query**.

# Before You Begin

- Ensure at least one DataHub connection is already created. See [Define DataHub Connections](docId:6O3gZwf3GM2lWncmEkBjw) for details.
- Confirm that your selected database includes the necessary measurements (tables). See [Configure an External DataHub Source](docId\:sE-CvzdrlEVKzoQLjMR5a) to learn more.

# Step 1: Navigate to Query Management Form 

1. Open a new Excel file with *Litmus Excel Add-ins *enabled. See [Step 4: Verify Litmus Excel Add-in Activation in Excel](docId\:GZDhBJ1xZZNDDThYOCuuu) to learn more.
2. Click on **Manage DataHub Queries**.

   ::Image[]{src="https://api.archbee.com/api/optimize/SSUUxKZUk9bFTEPNn_6Zo/wcxyQhF8XwyEztW9jZgbp_image.png" size="70" width="1381" height="599" position="center" showCaption="false"}
3. The *Litmus DataHub Queries* window pops up. You can take the following actions from this page:
   - **Add a New Queries: **See *Step 2 (Next Step)* below for detailed steps.
   - **Learn more: **This *Add-in* only supports *Queries* using *InfluxDB v1*. You can access the **InfluxDB Documentation **through this link.

     ::Image[]{src="https://api.archbee.com/api/optimize/SSUUxKZUk9bFTEPNn_6Zo/FaywHwlUuNRA_-tZpMPha_image.png" size="60" width="992" height="673" position="center" showCaption="false"}

# Step 2: Add a New Query 

:::hint{type="warning"}
**Note:** Verify the visibility of the **Add** button, which indicates readiness for query creation. If the Add button isn't visible, check the [Define DataHub Connections](docId:6O3gZwf3GM2lWncmEkBjw) guide.
:::

1. Click the **Add** button to begin the process.

   ::Image[]{src="https://api.archbee.com/api/optimize/SSUUxKZUk9bFTEPNn_6Zo/8pew_xFmFxkbAeI7W3fgj_image.png" size="60" width="833" height="578" position="center" showCaption="false"}
2. The system will prompt for a query name and connection selection.

::Image[]{src="https://api.archbee.com/api/optimize/SSUUxKZUk9bFTEPNn_6Zo/gRS_6wD_Dlm7-B-NI3HiJ-20251103-112849.png" size="70" width="1197" height="1028" position="center" showCaption="false"}

:::Paragraph{listStyleType="disc" indent="2"}
**Query Name: **The tool auto-generates a default query name that includes the creation date and time. 
*(Optionally) *Modify the default name to align with your internal naming standards.
:::

:::Paragraph{listStyleType="disc" listStart="2" indent="2"}
**Connection Name: **Choose the appropriate connection from the drop-down menu. 
See [Define DataHub Connections](docId:6O3gZwf3GM2lWncmEkBjw) if you don't see any defined connection. 
:::

:::hint{type="info"}
**Note:**

By default, the Query definition tool is always in Wizard Mode.

![](https://api.archbee.com/api/optimize/SSUUxKZUk9bFTEPNn_6Zo/vnpcE-oqxJ7XD_5XBQZ3e_image.png)
:::

# Step 3: Configure Query Parameters 

Configure the following fields:

1. **From: **Pick the desired table (from the drop-down menu) for the query. 
2. **Query Statement: **It displays only the query that the user configures using all the other tools.
3. **Time Range, Order By, Limit, SLimit, Select, Where: **The system constructs a default query that: 
   - Applies a mean calculation on the selected field.
   - Groups results by time.
   - Orders data in ascending order.
   - **Note:** The default time range is set to the last hour.
   - If the query syntax is correct, you will see the message "*Query is executable.*" in green at the bottom.

::Image[]{src="https://api.archbee.com/api/optimize/SSUUxKZUk9bFTEPNn_6Zo/4-yjOtRuNQJOOPzQtyvKu-20251103-112423.png" size="80" width="1200" height="1030" position="center" showCaption="false"}

# Step 4: Preview the Query Results 

1. Use the preview icon to display the first **10 **rows of query results. 
   The *Results for Action Execution* window appears. 

   ::Image[]{src="https://api.archbee.com/api/optimize/SSUUxKZUk9bFTEPNn_6Zo/oc-vnVCv60DF3RYg_qlvm-20251103-112236.png" darkSrc="https://archbee-image-uploads.s3.amazonaws.com/SSUUxKZUk9bFTEPNn_6Zo/T8l3yzrO86NdDWLs_uKPy-20251103-110952.png" size="70" width="1200" height="1030" darkWidth="1200" darkHeight="1030" position="center" showCaption="false"}
2. The preview serves as an initial data check. 

   ::Image[]{src="https://api.archbee.com/api/optimize/SSUUxKZUk9bFTEPNn_6Zo/pG-oKZRcWZDDcaFDrThX1_image.png" size="80" width="1045" height="379" position="center" showCaption="false"}

:::hint{type="danger"}
**Troubleshooting: **A lack of data may indicate:

- An incorrect query configuration.
- A combination of conditions that returns no data.
- No data available within the selected time range.
:::

# Step 5: Save and Finalize the Query 

1. After validating the query setup, click **Save **to save the query. 

   ::Image[]{src="https://api.archbee.com/api/optimize/SSUUxKZUk9bFTEPNn_6Zo/k4MSQNufCOtUsVb9AI9mx-20251103-112104.png" darkSrc="https://archbee-image-uploads.s3.amazonaws.com/SSUUxKZUk9bFTEPNn_6Zo/k4MSQNufCOtUsVb9AI9mx-20251103-112104.png" size="70" width="1200" height="1030" darkWidth="1200" darkHeight="1030" position="center" showCaption="false"}
2. When saved, a new *Excel* sheet with query details is added, and the dashboard updates accordingly.

   ![](https://api.archbee.com/api/optimize/SSUUxKZUk9bFTEPNn_6Zo/jzvuV9Esb3gBo3rc3y2m__image.png)

:::hint{type="info"}
**Note: **The query remains functional independently of the DataHub add-in and can be refreshed directly via Excel’s data refresh option. 
:::