Datasources & queries

Querying a datasource in Grafana involves three layers:

1. The datasource registry — the configured connection (URL, credentials, type). Lives in pkg/services/datasources/.
2. The plugin host — the runtime that loads the datasource's backend plugin. Lives in pkg/plugins/ (see Plugin host).
3. The query orchestrator — fans queries out to plugins, merges results, applies expressions. Lives in pkg/services/query/ and pkg/expr/.

Datasource registry

pkg/services/datasources/ handles datasource CRUD, secret encryption, and per-org isolation:

pkg/services/datasources/
├── datasource.go            # Service interface + types
├── service/                 # Implementation
├── api/                     # /api/datasources/* handlers
├── manager/                 # Higher-level helpers
└── models/                  # Persistence + DTO

Each datasource has:

• id (numeric, org-scoped) and uid (random string, org-scoped, the canonical reference).
• type matching a plugin id (e.g. prometheus, loki, mysql).
• url, access (proxy vs direct), basicAuth, …
• A jsonData blob (per-plugin settings) and a secureJsonData blob (encrypted secrets via pkg/services/secrets/).

Datasource secrets are encrypted at rest with a per-instance encryption key, optionally wrapped by an external KMS configured in pkg/services/kmsproviders/.

Query orchestration

pkg/services/query/query.go is the entry point for /api/ds/query. It:

1. Receives a list of Query objects (one per panel target).
2. Authorizes the user against each referenced datasource (datasources:query).
3. Groups queries by datasource and dispatches them to the corresponding backend plugin via the plugin host.
4. Resolves any expression queries through pkg/expr/.
5. Merges responses into a single QueryDataResponse.

sequenceDiagram
    participant UI as Panel/Explore
    participant Query as services/query
    participant Expr as expr engine
    participant Plug as plugin host
    participant TSDB as pkg/tsdb/<name>

    UI->>Query: POST /api/ds/query
    Query->>Query: authorize datasources
    Query->>Query: group by datasource
    Query->>Plug: QueryData(req)
    Plug->>TSDB: gRPC QueryData
    TSDB-->>Plug: QueryDataResponse (DataFrames)
    Plug-->>Query: response
    Query->>Expr: evaluate __expr__ queries (if any)
    Query-->>UI: merged QueryDataResponse

Expressions

pkg/expr/ implements server-side expressions: a small DSL that lets dashboards and alert rules combine, reduce, threshold, or transform results from one or more datasources before they hit the panel/condition.

• Math — arithmetic over series ($A * 2 + $B).
• Reduce — collapse a series to a scalar (mean, max, last).
• Resample — uniform sampling.
• Threshold — boolean comparison.
• Classic conditions — Grafana-style WHEN <reducer> OF query(<ref>) IS ABOVE <value>.
• SQL expression — newer SQL-over-frames experiment.

Used heavily in alerting and increasingly in dashboards through the __expr__ datasource type.

Datasource backends (pkg/tsdb/)

Each first-party datasource that needs server-side execution has a Go package under pkg/tsdb/<name>/ implementing the grafana-plugin-sdk-go QueryDataHandler interface:

• prometheus, loki, tempo, jaeger, zipkin — observability backends
• cloudwatch, azuremonitor, cloud-monitoring — cloud monitoring vendors
• mysql, mssql, grafana-postgresql-datasource, influxdb, opentsdb, graphite — database / TSDB
• parca, grafana-pyroscope-datasource — profiling
• grafana-testdata-datasource, grafanads — internal/test
• expr — the expression engine (registered as a "datasource" so the existing pipeline can run it)

These are compiled into the Grafana binary and loaded as in-process plugins. External datasource plugins follow the same SDK contract but run as separate processes spawned by the plugin host.

Datasource proxy

For datasources configured with access=proxy, the frontend doesn't talk to the datasource directly — it goes through /api/datasources/proxy/<id>/<path>. pkg/services/datasourceproxy/ and pkg/api/pluginproxy/ implement the proxy: they apply auth (e.g. inject API keys), enforce permissions, rewrite URLs, and forward.

This is mostly used by simple HTTP datasources that don't ship a backend plugin (e.g. simple JSON APIs).

Caching

pkg/services/caching/ is a hook point for caching query results — used by Grafana Cloud / Enterprise to cache expensive queries between dashboard renders. The OSS hook is a no-op pass-through.

Query history

User-issued Explore queries are persisted to pkg/services/queryhistory/ so users can review and re-run them.

Key source files

File	Purpose
pkg/services/query/query.go	/api/ds/query orchestrator
pkg/services/datasources/datasource.go	Datasource service
pkg/expr/	Server-side expression engine
pkg/services/datasourceproxy/	HTTP proxy for access=proxy datasources
pkg/api/pluginproxy/	Plugin proxy implementation
pkg/tsdb/<name>/	Per-datasource backends

See TSDB query backends for a tour of the individual pkg/tsdb/ packages and Plugin host for how plugins are loaded and dispatched.