Hydrolix Data Source Plugin for Grafana

Overview

The Hydrolix data source plugin for Grafana is a secure and high-performance way to query data from a Hydrolix cluster in Grafana. It includes:

• Autocompletion for data stores, tables, columns, and SQL syntax
• Support for template variables and macros
• Automatic SQL formatting

The plugin also improves query efficiency, reducing cluster load and query costs.

This page describes extra configuration options and plugin features you can use after you install and configure the plugin in Grafana.

Before you begin

If you haven't deployed Grafana, see the Grafana automatic installation to deploy it in a Hydrolix cluster.

To deploy Grafana outside the Hydrolix cluster, see Grafana manual installation.

You must have an organization administrator role to add or remove data sources.

Configure the data source

Configure the Hydrolix data source in Grafana, or with configuration files.

Server settings

TLS settings

Credentials settings

Additional settings (optional)

Set query options

Send Hydrolix query options with every query from the data source. They're wrapped as CustomSetting values.
Only a subset of query options are supported.

To add a query option:

1. Select a setting from the dropdown list.
2. Enter a value.

Use Grafana variables or dashboard template variables.
If a variable isn’t defined, it stays as-is.

Synthetic variables supported:

• ${__hydrolix.raw_query}- Raw query text before interpolation.
• ${__hydrolix.query_source}- Query source from the DataQueryRequest.app field. For example, use this variable to determine if the query came from Explore or another source.

Provision the data source

To provision the Hydrolix data source using Grafana’s provisioning system, define it in a YAML configuration file.

The following examples show how to provision the data source.

Use HTTPS protocol

apiVersion: 1
datasources:
  - name: "Hydrolix"
    type: "hydrolix-hydrolix-datasource"
    jsonData:
      host: localhost
      port: 443
      protocol: http
      secure: true
      username: username
      path: /query
    secureJsonData:
      password: password

Use native protocol

apiVersion: 1
datasources:
  - name: "Hydrolix"
    type: "hydrolix-hydrolix-datasource"
    jsonData:
      host: localhost
      port: 9440
      protocol: native
      secure: true
      username: username
    secureJsonData:
      password: password

Use HTTPS protocol with defaults and ad hoc filters

apiVersion: 1
datasources:
  - name: "Hydrolix"
    type: "hydrolix-hydrolix-datasource"
    jsonData:
      host: localhost
      port: 443
      protocol: http
      secure: true
      username: username
      path: /query
      defaultDatabase: database
      defaultRound: 60s
      adHocTableVariable: table
    secureJsonData:
      password: password

For more details about provisioning, see Grafana’s Provisioning documentation.

Query the data source

The query editor in Grafana supports SQL with syntax enhancements such as macros and templates.

SQL query editor

The editor provides extensive SQL capabilities:

• Autocompletion for databases, tables, columns, and SQL syntax.
• Template variable and macro support.
• Code formatting.

Keyboard shortcuts

• Cmd / Ctrl + Return: Run the query

Macros

Use macros to simplify syntax and add dynamic elements such as date range filters.

This example shows a query with the $__timeFilter macro:

SELECT $__timeInterval(log_time) AS time, avg(cpu_usage) AS value
FROM logs
WHERE $__timeFilter()
GROUP BY time
ORDER BY time

Ad hoc filters

Use ad hoc filters to dynamically filter column values.
Grafana injects these filters into queries with the $__adHocFilter macro. You must include the macro in the WHERE clause:

SELECT $__timeInterval(log_time) AS time, avg(cpu_usage) AS value
FROM logs
WHERE $__timeFilter() AND $__adHocFilter()
GROUP BY time
ORDER BY time

The plugin ensures filters are applied only when valid for the selected table.

Configure ad hoc filters

To enable ad hoc filters, configure both the data source and the dashboard:

1. In Data source settings > Additional Settings, add values for the following:

   • Ad hoc filter table variable name: the name of a dashboard variable that defines the table used to retrieve column names and their values for ad hoc filters.
   • Ad hoc filter default time range: a default time range to use when the dashboard time range is unavailable.

2. In the target dashboard, create variables using the exact names defined in the data source settings.

📘

Make sure the configuration and dashboard variable match

Ad hoc filters won't work unless both the data source and the dashboard are configured correctly. Be sure to match variable names exactly.

Limit ad hoc filter values

This plugin allows limiting ad hoc filter values based on a specified condition.
For example, if a dashboard only shows data from hosts with commercial domains, you can restrict the filter values using a condition like: host like '%.com'.

To apply the limit ad hoc filters, both the data source and the dashboard need additional configuration:

1. In Data source settings > Additional Settings, add values for the following:

   • Ad hoc filter values query condition variable name: the name of a dashboard variable that defines query condition to filter ad hoc filter values.

2. In the target dashboard, create a Constant (Const) variable with the name you set in Ad hoc filter values query condition variable name. For example, set its value to `host like %.com'.

Empty and null values

Ad hoc filters support two synthetic values to help identify and query rows with missing or blank data:

• __null__: matches rows where the column value is NULL.
• __empty__: matches rows where the column value is an empty string.

These synthetic values appear in the ad hoc filter suggestions only if the underlying data contains NULL or empty strings for the selected column and dashboard time range.

If the data contains literal values such as __null__ or __empty__, those will also be matched by the corresponding filters.

Wildcards

Ad hoc filters support wildcard filtering using the =~ and !~ operators. These operators allow matching or excluding values based on simple patterns that include the * wildcard character. Full regular expressions aren't supported.

The * symbol matches any sequence of characters, including an empty one. For example, *user* will match any value that contains the substring user, regardless of what comes before or after.

To match a literal asterisk (*), escape it with a backslash (\*). For example, to search for the exact string
*debug*, enter: \*debug\*.

To apply a wildcard filter:

1. On the dashboard, click inside the filter field.
2. Select the column you want to filter such as message.
3. Choose the operator =~ or !~.
4. Type your full wildcard pattern. For example: *user*.
5. Don't select any of the suggested values while typing.
6. As you type, an option appears at the bottom of the suggestion list: Use custom value: *user*.
7. Click this option to apply the filter.

Round timestamps

To control how time ranges are aligned, $from and $to timestamps can be rounded to the nearest multiple of the round value. This is set in the query editor or in the data source settings.

When a round value is set in the query editor, it takes precedence and is always used. If no round is set in the query editor, the data source falls back to the default round if it's configured and non-zero. If neither is set, or if the round value in the query editor is explicitly set to 0, no rounding occurs.

The supported time units for rounding are: ms (milliseconds), s (seconds), m (minutes), and h (hours).

Examples

Template variables

Hydrolix queries fully support Grafana's template variables to create dynamic and reusable dashboards.

For more details about template variables, see Grafana’s add variables documentation.