diff --git a/docs/sources/http_api/data_source.md b/docs/sources/http_api/data_source.md index d9f96d411a7..a46ef3b2774 100644 --- a/docs/sources/http_api/data_source.md +++ b/docs/sources/http_api/data_source.md @@ -604,13 +604,106 @@ Content-Type: application/json Proxies all calls to the actual data source. -## Query a data source by ID +## Query a data source -Queries a data source having backend implementation. +Queries a data source having a backend implementation. + +`POST /api/ds/query` + +> **Note:** Grafana's built-in data sources usually have a backend implementation. + +**Example request for the Test data source**: + +```http +POST /api/ds/query HTTP/1.1 +Accept: application/json +Content-Type: application/json + +{ + "queries":[ + { + "refId":"A", + "scenarioId":"csv_metric_values", + "datasource":{ + "uid":"PD8C576611E62080A" + }, + "format": "table" + "maxDataPoints":1848, + "intervalMs":200, + "stringInput":"1,20,90,30,5,0", + } + ], + "from":"now-5m", + "to":"now" +} +``` + +JSON Body schema: + +- **from/to** – Specifies the time range for the queries. The time can be either epoch timestamps in milliseconds or relative using Grafana time units. For example, `now-5m`. +- **queries** – Specifies one or more queries. Must contain at least 1. +- **queries.datasource.uid** – Specifies the UID of data source to be queried. Each query in the request must have a unique `datasource`. +- **queries.refId** – Specifies an identifier of the query. Defaults to "A". +- **queries.format** – Specifies the format the data should be returned in. Valid options are `time_series` or `table` depending on the data source. +- **queries.maxDataPoints** - Species the maximum amount of data points that a dashboard panel can render. Defaults to 100. +- **queries.intervalMs** - Specifies the time series time interval in milliseconds. Defaults to 1000. + +In addition, specific properties of each data source should be added in a request (for example **queries.stringInput** as shown in the request above). To better understand how to form a query for a certain data source, use the Developer Tools in your browser of choice and inspect the HTTP requests being made to `/api/ds/query`. + +**Example Test data source time series query response:** + +```json +{ + "results": { + "A": { + "frames": [ + { + "schema": { + "refId": "A", + "fields": [ + { + "name": "time", + "type": "time", + "typeInfo": { + "frame": "time.Time" + } + }, + { + "name": "A-series", + "type": "number", + "typeInfo": { + "frame": "int64", + "nullable": true + } + } + ] + }, + "data": { + "values": [ + [1644488152084, 1644488212084, 1644488272084, 1644488332084, 1644488392084, 1644488452084], + [1, 20, 90, 30, 5, 0] + ] + } + } + ] + } + } +} +``` + +## Deprecated resources + +The following resources have been deprecated. They will be removed in a future release. + +### Query a data source by ID + +> **Warning:** This API is deprecated since Grafana v8.5.0 and will be removed in a future release. Refer to the [new data source query API](#query-a-data-source-by-id). + +Queries a data source having a backend implementation. `POST /api/tsdb/query` -> **Note:** Most of Grafana's builtin data sources have backend implementation. +> **Note:** Grafana's built-in data sources usually have a backend implementation. **Example Request**: @@ -635,17 +728,16 @@ Content-Type: application/json } ``` -> **Note:** The `from`, `to`, and `queries` properties are required. - JSON Body schema: -- **from/to** – Should be either absolute in epoch timestamps in milliseconds or relative using Grafana time units. For example, `now-1h`. -- **queries.refId** – Specifies an identifier of the query. Is optional and default to "A". -- **queries.datasourceId** – Specifies the data source to be queried. Each `query` in the request must have an unique `datasourceId`. -- **queries.maxDataPoints** - Species maximum amount of data points that dashboard panel can render. Is optional and default to 100. -- **queries.intervalMs** - Specifies the time interval in milliseconds of time series. Is optional and defaults to 1000. +- **from/to** – Specifies the time range for the queries. The time can be either epoch timestamps in milliseconds or relative using Grafana time units. For example, `now-5m`. +- **queries.refId** – Specifies an identifier of the query. Defaults to "A". +- **queries.format** – Specifies the format the data should be returned in. Valid options are `time_series` or `table` depending on the data source. +- **queries.datasourceId** – Specifies the data source to be queried. Each `query` in the request must have a unique `datasourceId`. +- **queries.maxDataPoints** - Species the maximum amount of data points that a dashboard panel can render. Defaults to 100. +- **queries.intervalMs** - Specifies the time series time interval in milliseconds. Defaults to 1000. -In addition, each data source has its own specific properties that should be added in a request. +In addition, specific properties of each data source should be added in a request. To better understand how to form a query for a certain data source, use the Developer Tools in your browser of choice and inspect the HTTP requests being made to `/api/tsdb/query`. **Example request for the MySQL data source:** diff --git a/pkg/api/api.go b/pkg/api/api.go index de7227dbf74..9d5c33cf134 100644 --- a/pkg/api/api.go +++ b/pkg/api/api.go @@ -401,6 +401,7 @@ func (hs *HTTPServer) registerRoutes() { apiRoute.Get("/search/", routing.Wrap(hs.Search)) // metrics + // Deprecated: use /ds/query API instead. apiRoute.Post("/tsdb/query", authorize(reqSignedIn, ac.EvalPermission(datasources.ActionQuery)), routing.Wrap(hs.QueryMetrics)) // DataSource w/ expressions diff --git a/pkg/api/docs/definitions/datasources.go b/pkg/api/docs/definitions/datasources.go index c31930756c4..c5eb1d54752 100644 --- a/pkg/api/docs/definitions/datasources.go +++ b/pkg/api/docs/definitions/datasources.go @@ -200,6 +200,8 @@ import ( // // Query metrics. // +// Please refer to [updated API](#/ds/queryMetricsWithExpressions) instead +// // Queries a data source having backend implementation. // // Most of Grafana’s builtin data sources have backend implementation. @@ -207,6 +209,8 @@ import ( // If you are running Grafana Enterprise and have Fine-grained access control enabled // you need to have a permission with action: `datasources:query`. // +// Deprecated: true +// // Responses: // 200: queryDatasourceResponse // 401: unauthorisedError diff --git a/pkg/api/dtos/models.go b/pkg/api/dtos/models.go index 81adfe5cc99..1d9ccaeee1b 100644 --- a/pkg/api/dtos/models.go +++ b/pkg/api/dtos/models.go @@ -63,7 +63,7 @@ type MetricRequest struct { // queries.maxDataPoints - Species maximum amount of data points that dashboard panel can render. Is optional and default to 100. // queries.intervalMs - Specifies the time interval in milliseconds of time series. Is optional and defaults to 1000. // required: true - // example: [ { "refId": "A", "intervalMs": 86400000, "maxDataPoints": 1092, "datasourceId": 86, "rawSql": "SELECT 1 as valueOne, 2 as valueTwo", "format": "table" } ] + // example: [ { "refId": "A", "intervalMs": 86400000, "maxDataPoints": 1092, "datasource":{ "uid":"PD8C576611E62080A" }, "rawSql": "SELECT 1 as valueOne, 2 as valueTwo", "format": "table" } ] Queries []*simplejson.Json `json:"queries"` // required: false Debug bool `json:"debug"` diff --git a/pkg/api/metrics.go b/pkg/api/metrics.go index db0cad5d71f..d2e1e5503a2 100644 --- a/pkg/api/metrics.go +++ b/pkg/api/metrics.go @@ -145,6 +145,7 @@ func (hs *HTTPServer) QueryMetricsFromDashboard(c *models.ReqContext) response.R // POST /api/tsdb/query //nolint: staticcheck // legacydata.DataResponse deprecated //nolint: staticcheck // legacydata.DataQueryResult deprecated +// Deprecated: use QueryMetricsV2 instead. func (hs *HTTPServer) QueryMetrics(c *models.ReqContext) response.Response { reqDto := dtos.MetricRequest{} if err := web.Bind(c.Req, &reqDto); err != nil { diff --git a/public/api-merged.json b/public/api-merged.json index 2771159da29..a7b2fd4826e 100644 --- a/public/api-merged.json +++ b/public/api-merged.json @@ -8299,10 +8299,11 @@ }, "/tsdb/query": { "post": { - "description": "Queries a data source having backend implementation.\n\nMost of Grafana’s builtin data sources have backend implementation.\n\nIf you are running Grafana Enterprise and have Fine-grained access control enabled\nyou need to have a permission with action: `datasources:query`.", + "description": "Please refer to [updated API](#/ds/queryMetricsWithExpressions) instead\n\nQueries a data source having backend implementation.\n\nMost of Grafana’s builtin data sources have backend implementation.\n\nIf you are running Grafana Enterprise and have Fine-grained access control enabled\nyou need to have a permission with action: `datasources:query`.", "tags": ["datasources"], "summary": "Query metrics.", "operationId": "queryDatasource", + "deprecated": true, "parameters": [ { "name": "Body", @@ -13100,7 +13101,9 @@ "x-go-name": "Queries", "example": [ { - "datasourceId": 86, + "datasource": { + "uid": "PD8C576611E62080A" + }, "format": "table", "intervalMs": 86400000, "maxDataPoints": 1092, diff --git a/public/api-spec.json b/public/api-spec.json index 0f77b8f8555..ca2d7f1d234 100644 --- a/public/api-spec.json +++ b/public/api-spec.json @@ -6868,10 +6868,11 @@ }, "/tsdb/query": { "post": { - "description": "Queries a data source having backend implementation.\n\nMost of Grafana’s builtin data sources have backend implementation.\n\nIf you are running Grafana Enterprise and have Fine-grained access control enabled\nyou need to have a permission with action: `datasources:query`.", + "description": "Please refer to [updated API](#/ds/queryMetricsWithExpressions) instead\n\nQueries a data source having backend implementation.\n\nMost of Grafana’s builtin data sources have backend implementation.\n\nIf you are running Grafana Enterprise and have Fine-grained access control enabled\nyou need to have a permission with action: `datasources:query`.", "tags": ["datasources"], "summary": "Query metrics.", "operationId": "queryDatasource", + "deprecated": true, "parameters": [ { "name": "Body", @@ -10425,7 +10426,9 @@ "x-go-name": "Queries", "example": [ { - "datasourceId": 86, + "datasource": { + "uid": "PD8C576611E62080A" + }, "format": "table", "intervalMs": 86400000, "maxDataPoints": 1092,