Skip to content

FAQ

Jump to bottom
leoswing edited this page May 25, 2026 · 1 revision
  1. Migration-Guide
  2. FAQ

Migration-Guide page content

Migration Guide

This guide helps you migrate dashboards from the legacy RefId workflow to the recommended Target Datasource workflow.

Who should migrate?

  • You are using Grafana 13+.
  • Your existing CompareQueries rows still use Reference Query refId.
  • You want better long-term compatibility and easier maintenance.

Legacy vs Recommended

Legacy RefId workflow:

  • CompareQueries references another query in the same -- Mixed -- panel by refId.
  • Existing Grafana 11/12 dashboards can still work this way.

Recommended Target Datasource workflow:

  • Configure the target datasource directly inside CompareQueries.
  • Build the target query inline in CompareQueries Query Editor.
  • Required for all new dashboards, especially Grafana 13+.

Migration steps

  1. Open the dashboard panel that contains the legacy CompareQueries query.
  2. Edit the CompareQueries row where Reference Query refId is set.
  3. Click Migrate to Target Datasource.
  4. Select the original target datasource.
  5. Rebuild the target query inline in CompareQueries.
  6. Keep your existing Time-shift rows and alias settings.
  7. Save the panel and dashboard.
  8. Verify chart output and legends.

What is preserved during migration

  • CompareQueries query refId
  • Time-shift rows (Amount, aliases)
  • Delimiter settings
  • Process TimeShift option

Rollback

If results are not as expected:

  1. Open Dashboard settings.
  2. Go to Versions.
  3. Restore a previous version.

Validation checklist

  • Panel datasource is -- Mixed --.
  • CompareQueries row uses Target Datasource (not legacy refId mode).
  • Base series and shifted series are both present.
  • Legend aliases are correct.
  • Alert rules (if any) still evaluate as expected.

Related pages

———

FAQ page content

FAQ

Does CompareQueries store metrics by itself?

No. CompareQueries does not store data. It executes queries against your selected target datasource (Prometheus, Loki, Elasticsearch, SQL, etc.).

Which Grafana versions are supported?

CompareQueries supports Grafana 11, 12, and 13+.

Is legacy RefId mode still supported?

Yes, for existing Grafana 11/12 dashboards. For Grafana 13+ and all new dashboards, use the Target Datasource workflow.

Why do I need -- Mixed -- in dashboard panels?

In dashboards, CompareQueries is typically used as a query row inside a panel whose datasource is set to -- Mixed --. This lets you combine CompareQueries with native datasource queries in one panel.

Does CompareQueries support Grafana Alerting?

Yes. Alerting is supported through backend query execution.

Alert preview fails with authentication errors. What should I do?

  1. Keep datasource auth mode as No Authentication first.
  2. If backend/auth errors occur, switch to Basic authentication.
  3. Configure a Grafana Service Account token (Viewer or above).
  4. Set Grafana URL only if auto-detection is incorrect.

Why are shifted series not aligned with the current time window?

Enable Process TimeShift to align shifted series timestamps with the current window when needed.

Can I compare multiple shifts in one query?

Yes. Add multiple Time-shift rows (for example 1d, 1w, 30m) in one CompareQueries query.

Where can I report issues or request features?

Use the GitHub repository issues page: https://github.com/leoswing/comparequeries-datasource-rc/issues

Related pages

CompareQueries Wiki

More

Clone this wiki locally