Hydrolix data source for Grafana

The Hydrolix data source plugin integrates Hydrolix with Grafana, enabling seamless querying, analysis, and visualization of Hydrolix data.

Install the plugin

To install the Hydrolix data source plugin:

1. Open the Grafana Plugin Catalog.
2. Search for Hydrolix Data Source.
3. Select the plugin and click Install Plugin.

After installation:

1. In Grafana, go to Connections > Data Sources > Add new data source.
2. Select Hydrolix from the list.

For more details about installation, see Grafana’s Plugin management documentation.

Configure the data source

You can configure the Hydrolix data source directly within Grafana or via configuration files.

Following is the list of Hydrolix configuration options:

Provision the data source

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

Below are some provisioning examples.

Using 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

Using 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

Using 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
      adHocTimeColumnVariable: timeColumn
      adHocKeysQuery: DESCRIBE $${table}
      adHocValuesQuery: >
        SELECT $${column}, COUNT(*) as count FROM $${table}
        WHERE $$__timeFilter($${timeColumn}) AND $$__adHocFilter()
        GROUP BY $${column}
        ORDER BY count DESC
        LIMIT 100
    secureJsonData:
      password: password

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

Querying the data source

The query editor in Grafana enables powerful SQL querying with convenient syntax enhancements through macros and templates.

SQL query editor

The editor provides extensive SQL capabilities, featuring:

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

Keyboard shortcuts

• Cmd/Ctrl + Return – Run the query.

Macros

To simplify syntax and to allow for dynamic parts, like date range filters, the query can contain macros.

Below is an example of a query with the $__timeFilter macro:

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

Ad hoc filters

Ad hoc filters allow flexible, key-value filtering dynamically applied across queries. These filters are injected into queries via the $__adHocFilter macro, which must be explicitly included in the WHERE clause:

SELECT $__timeInterval(log_time) AS time, avg(cpu_usage) AS value
FROM logs
WHERE $__timeFilter(log_time) 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, both the data source and the dashboard must be configured properly:

1. In the data source settings (under Advanced Settings):

   • Ad-hoc filter table variable name: the name of a dashboard variable that defines the table used for retrieving filter keys and values.
   • Ad-hoc filter time column variable name: the name of a dashboard variable that defines the time column used for time filtering in value queries.
   • Ad-hoc filter keys query: a query template for listing possible keys.
   • Ad-hoc filter values query: a query template for listing possible values.
   • Ad-hoc filter default time range: a default time range to use when the dashboard’s time range is unavailable.

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

   • A variable for the table name.
   • A variable for the time column.

Note: Ad hoc filters will not work unless both the data source and the dashboard are configured correctly. Be sure to match variable names precisely.

Query templates

These templates are used to dynamically generate the list of available keys and values for filtering.

Keys query:

DESCRIBE ${table}

Values query:

SELECT ${column}, COUNT(${column}) AS count
FROM ${table}
WHERE $__timeFilter(${timeColumn}) AND $__adHocFilter()
GROUP BY ${column}
ORDER BY count DESC
LIMIT 100

In the query templates, certain placeholders are dynamically replaced with real values at runtime. Here is what each variable represents:

For more details about ad hoc filters, see Grafana’s Ad hoc filters documentation.

Round timestamps

To control how time ranges are aligned, $from and $to timestamps can be rounded to the nearest multiple of the round value, 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 is configured and non-zero. If neither is set, or if the round value in the query editor is explicitly set to 0, no rounding is applied and the original timestamps are used as-is.

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, allowing the creation of dynamic and reusable dashboards.

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