Grafana / Basic: sources, fields, and interpretation / Lesson 2

Data sources and query contracts

Read a panel query as a plugin-specific contract with a stable data-source identity, scope, response shape, and execution identity.

About 4 min readContent reviewed 2026-10-28

On this page

Lesson goals

Separate data-source type, name, and UID.
Identify query language and execution context.
Distinguish connection checks from measurement correctness.

The integration defines what a query means

A Grafana data source connects a supported plugin to a particular backend configuration. Prometheus expressions, SQL, log queries, and tracing searches have different languages and result semantics. Grafana does not make them interchangeable by putting them in one dashboard. Record the plugin type and version, backend version, source scope, and intended measurement. A reference named A identifies a query within a panel or expression chain; it is not the backend’s authentication identity. Keep backend errors, query results, and visualization interpretation separate when investigating a panel.

Use stable identity without confusing it with access

A data-source display name helps people recognize it, while its UID is used by dashboard references and provisioning contracts. Renaming a source should not be treated as proof that every consumer now points to the intended replacement. Copying a dashboard between environments can leave a UID unresolved or mapped to another backend. A UID does not contain permission to query. Review organization or stack scope and the actual access model, including any Enterprise or Cloud data-source permission capability. A visible dashboard restriction alone may not constrain all queries a user can issue through an accessible source.

Read a plugin-specific query fragment

The JSON fragment describes one illustrative Prometheus query target for a fictional transit delay gauge. It is not a complete dashboard, a data-source creation request, or an executable API call. The source UID must resolve to an appropriate configured integration in any real adaptation. The expression selects one route and returns seconds according to the fictional metric contract. A query editor accepting the text would not prove the route population, timestamp meaning, or backend permissions are correct. Other plugins use different query models; do not paste this target into a SQL or log integration.

json Illustrative Prometheus query-target JSON

{"refId":"A","datasource":{"type":"prometheus","uid":"transit-lab-prom"},"expr":"transit_departure_delay_seconds{route=\"r1\"}"}

This non-runnable fragment shows source identity and plugin-specific expression fields only. It is not imported, sent, queried, or validated by Grafana.

Keep the response contract explicit

The offline fixture filters synthetic route rows and computes a mean delay in seconds. It establishes the arithmetic for that fixed population, not the preceding PromQL query. The result depends on whether rows represent vehicles, departures, or already aggregated intervals; averaging averages can give the wrong population weighting. Record units, time scope, labels, null meaning, and aggregation before choosing a stat panel. A source can return valid rows with the wrong business boundary. Validate a small known case so a visually plausible number cannot silently substitute for the intended measurement.

python Offline route-query population model

rows = [("r1", 4.0), ("r1", 8.0), ("r2", 20.0)]
selected = [delay for route, delay in rows if route == "r1"]
print("selected_count", len(selected))
print("mean_seconds", sum(selected) / len(selected))

Expected output

selected_count 2
mean_seconds 6.0

Only fixed tuples are filtered. No Prometheus, SQL, log, Grafana data-source plugin, or external query is executed.

Connection success is narrower than end-to-end success

A configured source can pass a connection check while a particular query lacks access, uses unsupported syntax, or returns an unexpected shape. Dashboard browsing, Explore, and server-side alert evaluation may have different supported paths and identity requirements. Verify plugin capabilities and backend authorization rather than assuming the browser user’s identity is always forwarded. Shared source credentials can expose a broader backend scope than a panel suggests. This lesson accesses no account or source; it tests local filtering only and leaves actual connection, authentication, query execution, and plugin behavior unverified.

Common errors and fixes

A copied dashboard queries the wrong environment

Why it happens: Its source UID resolved differently.
How to fix it: Review the destination mapping and scope.
Prevent it next time: Version environment-specific source references.

A successful connection check is called a correct query

Why it happens: Connectivity was confused with authorization and semantics.
How to fix it: Test the intended query contract in the authorized environment.
Prevent it next time: Keep connection and measurement evidence distinct.

A query fragment is pasted into another plugin

Why it happens: Plugin-specific models were assumed universal.
How to fix it: Use the selected integration’s supported query model.
Prevent it next time: Record plugin type and version with examples.

Check your understanding

1. A panel and a server-side alert use the same data-source UID. Does that prove they execute with identical capabilities and identity?

Show worked solution

No. Plugin support, query model, backend execution, and authentication configuration can differ between interactive and server-side paths. Review the exact supported alerting capability and authorization. A shared UID identifies configuration but is not evidence that every consumer can run the same query successfully.

2. Why should a source response with rows still be checked against the measurement contract?