Skip to content

Add backend expansion for Grafana $__interval and $__interval_ms macros - #122

Merged
JackieTien97 merged 2 commits into
apache:masterfrom
CoollZzz:feat/support-dynamic-interval-macros
Aug 12, 2026
Merged

Add backend expansion for Grafana $__interval and $__interval_ms macros#122
JackieTien97 merged 2 commits into
apache:masterfrom
CoollZzz:feat/support-dynamic-interval-macros

Conversation

@CoollZzz

@CoollZzz CoollZzz commented Aug 11, 2026

Copy link
Copy Markdown
Contributor

This pull request adds support for Grafana's $__interval and $__interval_ms macros in IoTDB table-model SQL queries. It expands both macros using Grafana's runtime query interval and adds input validation, identifier-safe macro replacement, and unit tests for the new behavior.

Interval Macro Expansion

  • Expands $__interval to an IoTDB fixed-width duration literal using ms, s, m, h, d, or w.
  • Expands $__interval_ms directly to the query interval in milliseconds, following Grafana's standard macro semantics.
  • Uses backend.DataQuery.Interval as the runtime interval source.

Macro Matching

  • Replaces only standalone macro names.
  • Handles $__interval and $__interval_ms independently when both appear in the same SQL statement.
  • Preserves identifiers such as $__intervalish and $__interval_ms_extra.

Query Parameter Handling

  • Adds a runtime-only IntervalMS field to the table query model.
  • Populates IntervalMS from backend.DataQuery.Interval after JSON unmarshalling.
  • Excludes the runtime interval field from JSON serialization and deserialization.

Error Handling

  • Rejects non-positive intervals when an interval macro is used.
  • Validates the interval before acquiring an RPC session.
  • Retains input validation in the macro expansion helper for direct callers.
  • Preserves existing behavior for queries that do not contain interval macros.

Tests

Unit tests cover:

  • Expansion of $__interval and $__interval_ms
  • Expansion of both macros in the same SQL statement
  • Fixed-width duration formatting
  • Millisecond semantics of $__interval_ms
  • Zero and negative intervals
  • Identifier-boundary handling
  • Runtime-only query parameter behavior
  • Early validation before RPC session acquisition
  • Existing Grafana time macro behavior

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi, this is your first pull request in IoTDB project. Thanks for your contribution! IoTDB will be better because of you.

@JackieTien97 JackieTien97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are two blocking correctness and compatibility issues in the current interval macro implementation.

}

if hasIntervalMS {
scaled, err := scaleIntervalMS(intervalMS, timestampPrecision)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P1] Preserve Grafana's millisecond contract for $__interval_ms. Grafana defines this macro as the query interval in milliseconds, independent of the data source's timestamp precision; the Grafana SDK likewise expands it directly from query.Interval.Milliseconds(). Scaling it here changes a 120-second interval from 120000 to 120000000/120000000000 on us/ns servers and can silently change query results. Please expand it directly with strconv.FormatInt(intervalMS, 10) and update the precision-scaling tests accordingly. If raw IoTDB timestamp units are needed, that should be a separately named, plugin-specific macro rather than changing the standard Grafana macro.

}
timestampPrecision := "ms"
if hasStandaloneMacro(qp.Sql, intervalMSRe) {
timestampPrecision, err = readTimestampPrecision(session, &timeout)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P1] Avoid issuing privileged metadata SQL from the normal query path. In IoTDB's table dialect, SHOW VARIABLES requires the global SYSTEM privilege, so a normal Grafana service account with only database/table read access will fail before its actual query runs. The standard $__interval_ms macro does not need server precision and this lookup should be removed. If timestamp precision is still needed for a separate raw-server-unit feature before the Go client exposes the precision already returned by the session handshake, please add an explicit validated datasource setting (ms/us/ns) as a temporary solution instead of executing SHOW VARIABLES for every query.

@CoollZzz
CoollZzz force-pushed the feat/support-dynamic-interval-macros branch from 0bd0b0f to 1199c74 Compare August 12, 2026 07:16
@JackieTien97
JackieTien97 merged commit a811f62 into apache:master Aug 12, 2026
14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants