@ -960,117 +960,3 @@ In addition, specific properties of each data source should be added in a reques
| 403 | Access denied. |
| 404 | Either the data source or plugin required to fulfil the request could not be found. |
| 500 | Unexpected error. Refer to the body and/or server logs for more details. |
## 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).
Queries a data source having a backend implementation.
`POST /api/tsdb/query`
> **Note:** Grafana's built-in data sources usually have a backend implementation.
**Example Request**:
```http
POST /api/tsdb/query HTTP/1.1
Accept: application/json
Content-Type: application/json
{
"from": "1420066800000",
"to": "1575845999999",
"queries": [
{
"refId": "A",
"intervalMs": 86400000,
"maxDataPoints": 1092,
"datasourceId": 86,
"rawSql": "SELECT 1 as valueOne, 2 as valueTwo",
"format": "table"
}
]
}
```
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.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, 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:**
```http
POST /api/tsdb/query HTTP/1.1
Accept: application/json
Content-Type: application/json
{
"from": "1420066800000",
"to": "1575845999999",
"queries": [
{
"refId": "A",
"intervalMs": 86400000,
"maxDataPoints": 1092,
"datasourceId": 86,
"rawSql": "SELECT\n time,\n sum(opened) AS \"Opened\",\n sum(closed) AS \"Closed\"\nFROM\n issues_activity\nWHERE\n $__unixEpochFilter(time) AND\n period = 'm' AND\n repo IN('grafana/grafana') AND\n opened_by IN('Contributor','Grafana Labs')\nGROUP BY 1\nORDER BY 1\n",
"format": "time_series"
}
]
}
```
**Example MySQL time series query response:**
```http
HTTP/1.1 200
Content-Type: application/json
{
"results": {
"A": {
"refId": "A",
"meta": {
"rowCount": 0,
"sql": "SELECT\n time,\n sum(opened) AS \"Opened\",\n sum(closed) AS \"Closed\"\nFROM\n issues_activity\nWHERE\n time >= 1420066800 AND time <= 1575845999 AND\n period = 'm' AND\n repo IN('grafana/grafana') AND\n opened_by IN('Contributor','Grafana Labs')\nGROUP BY 1\nORDER BY 1\n"
"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`.",
"description":"Deprecated: DataResponse -- this structure is deprecated, all new work should use backend.QueryDataResponse",
"description":"A map of RefIDs (unique query identifers) to this type makes up the Responses property of a QueryDataResponse.\nThe Error property is used to allow for partial success responses from the containing QueryDataResponse.",
"type":"object",
"title":"DataResponse contains the results from a DataQuery.",
"properties":{
"message":{
"type":"string",
"x-go-name":"Message"
"Error":{
"description":"Error is a property to be set if the the corresponding DataQuery has an error.",
"description":"DateTime is a time but it serializes to ISO8601 format with millis\nIt knows how to read 3 different variations of a RFC3339 date time.\nMost APIs we encounter want either millisecond or second precision times.\nThis just tries to make it worry-free.",
"type":"string",
@ -10897,6 +10764,119 @@
"Failure":{
"$ref":"#/definitions/ResponseDetails"
},
"Field":{
"description":"A Field is essentially a slice of various types with extra properties and methods.\nSee NewField() for supported types.\n\nThe slice data in the Field is a not exported, so methods on the Field are used to to manipulate its data.",
"type":"object",
"title":"Field represents a typed column of data within a Frame.",
"properties":{
"config":{
"$ref":"#/definitions/FieldConfig"
},
"labels":{
"$ref":"#/definitions/Labels"
},
"name":{
"description":"Name is default identifier of the field. The name does not have to be unique, but the combination\nof name and Labels should be unique for proper behavior in all situations.",
"title":"FieldConfig represents the display properties for a Field.",
"properties":{
"color":{
"description":"Map values to a display color\nNOTE: this interface is under development in the frontend... so simple map for now",
"type":"object",
"additionalProperties":{
"type":"object"
},
"x-go-name":"Color"
},
"custom":{
"description":"Panel Specific Values",
"type":"object",
"additionalProperties":{
"type":"object"
},
"x-go-name":"Custom"
},
"decimals":{
"type":"integer",
"format":"uint16",
"x-go-name":"Decimals"
},
"description":{
"description":"Description is human readable field metadata",
"type":"string",
"x-go-name":"Description"
},
"displayName":{
"description":"DisplayName overrides Grafana default naming, should not be used from a data source",
"type":"string",
"x-go-name":"DisplayName"
},
"displayNameFromDS":{
"description":"DisplayNameFromDS overrides Grafana default naming in a better way that allows users to override it easily.",
"type":"string",
"x-go-name":"DisplayNameFromDS"
},
"filterable":{
"description":"Filterable indicates if the Field's data can be filtered by additional calls.",
"type":"boolean",
"x-go-name":"Filterable"
},
"interval":{
"description":"Interval indicates the expected regular step between values in the series.\nWhen an interval exists, consumers can identify \"missing\" values when the expected value is not present.\nThe grafana timeseries visualization will render disconnected values when missing values are found it the time field.\nThe interval uses the same units as the values. For time.Time, this is defined in milliseconds.",
"type":"number",
"format":"double",
"x-go-name":"Interval"
},
"links":{
"description":"The behavior when clicking on a result",
"type":"array",
"items":{
"$ref":"#/definitions/DataLink"
},
"x-go-name":"Links"
},
"mappings":{
"$ref":"#/definitions/ValueMappings"
},
"max":{
"$ref":"#/definitions/ConfFloat64"
},
"min":{
"$ref":"#/definitions/ConfFloat64"
},
"noValue":{
"description":"Alternative to empty string",
"type":"string",
"x-go-name":"NoValue"
},
"path":{
"description":"Path is an explicit path to the field in the datasource. When the frame meta includes a path,\nthis will default to `${frame.meta.path}/${field.name}\n\nWhen defined, this value can be used as an identifier within the datasource scope, and\nmay be used as an identifier to update values in a subsequent request",
"type":"string",
"x-go-name":"Path"
},
"thresholds":{
"$ref":"#/definitions/ThresholdsConfig"
},
"unit":{
"description":"Numeric Options",
"type":"string",
"x-go-name":"Unit"
},
"writeable":{
"description":"Writeable indicates that the datasource knows how to update this value",
"description":"Each Field is well typed by its FieldType and supports optional Labels.\n\nA Frame is a general data container for Grafana. A Frame can be table data\nor time series data depending on its content and field types.",
"type":"object",
"title":"Frame is a columnar data structure where each column is a Field.",
"properties":{
"Fields":{
"description":"Fields are the columns of a frame.\nAll Fields must be of the same the length when marshalling the Frame for transmission.",
"type":"array",
"items":{
"$ref":"#/definitions/Field"
}
},
"Meta":{
"$ref":"#/definitions/FrameMeta"
},
"Name":{
"description":"Name is used in some Grafana visualizations.",
"type":"string"
},
"RefID":{
"description":"RefID is a property that can be set to match a Frame to its originating query.",
"description":"https://github.com/grafana/grafana/blob/master/packages/grafana-data/src/types/data.ts#L11\nNOTE -- in javascript this can accept any `[key: string]: any;` however\nthis interface only exposes the values we want to be exposed",
"type":"object",
"title":"FrameMeta matches:",
"properties":{
"channel":{
"description":"Channel is the path to a stream in grafana live that has real-time updates for this data.",
"type":"string",
"x-go-name":"Channel"
},
"custom":{
"description":"Custom datasource specific values.",
"type":"object",
"x-go-name":"Custom"
},
"executedQueryString":{
"description":"ExecutedQueryString is the raw query sent to the underlying system. All macros and templating\nhave been applied. When metadata contains this value, it will be shown in the query inspector.",
"type":"string",
"x-go-name":"ExecutedQueryString"
},
"notices":{
"description":"Notices provide additional information about the data in the Frame that\nGrafana can display to the user in the user interface.",
"type":"array",
"items":{
"$ref":"#/definitions/Notice"
},
"x-go-name":"Notices"
},
"path":{
"description":"Path is a browsable path on the datasource.",
"type":"string",
"x-go-name":"Path"
},
"pathSeparator":{
"description":"PathSeparator defines the separator pattern to decode a hiearchy. The default separator is '/'.",
"type":"string",
"x-go-name":"PathSeparator"
},
"preferredVisualisationType":{
"$ref":"#/definitions/VisType"
},
"stats":{
"description":"Stats is an array of query result statistics.",
"description":"A FrameType string, when present in a frame's metadata, asserts that the\nframe's structure conforms to the FrameType's specification.\nThis property is currently optional, so FrameType may be FrameTypeUnknown even if the properties of\nthe Frame correspond to a defined FrameType.",
"description":"The embedded FieldConfig's display name must be set.\nIt corresponds to the QueryResultMetaStat on the frontend (https://github.com/grafana/grafana/blob/master/packages/grafana-data/src/types/data.ts#L53).",
"type":"object",
"title":"QueryStat is used for storing arbitrary statistics metadata related to a query and its result, e.g. total request time, data processing time.",
"properties":{
"color":{
"description":"Map values to a display color\nNOTE: this interface is under development in the frontend... so simple map for now",
"type":"object",
"additionalProperties":{
"type":"object"
},
"x-go-name":"Color"
},
"custom":{
"description":"Panel Specific Values",
"type":"object",
"additionalProperties":{
"type":"object"
},
"x-go-name":"Custom"
},
"decimals":{
"type":"integer",
"format":"uint16",
"x-go-name":"Decimals"
},
"description":{
"description":"Description is human readable field metadata",
"type":"string",
"x-go-name":"Description"
},
"displayName":{
"description":"DisplayName overrides Grafana default naming, should not be used from a data source",
"type":"string",
"x-go-name":"DisplayName"
},
"displayNameFromDS":{
"description":"DisplayNameFromDS overrides Grafana default naming in a better way that allows users to override it easily.",
"type":"string",
"x-go-name":"DisplayNameFromDS"
},
"filterable":{
"description":"Filterable indicates if the Field's data can be filtered by additional calls.",
"type":"boolean",
"x-go-name":"Filterable"
},
"interval":{
"description":"Interval indicates the expected regular step between values in the series.\nWhen an interval exists, consumers can identify \"missing\" values when the expected value is not present.\nThe grafana timeseries visualization will render disconnected values when missing values are found it the time field.\nThe interval uses the same units as the values. For time.Time, this is defined in milliseconds.",
"type":"number",
"format":"double",
"x-go-name":"Interval"
},
"links":{
"description":"The behavior when clicking on a result",
"type":"array",
"items":{
"$ref":"#/definitions/DataLink"
},
"x-go-name":"Links"
},
"mappings":{
"$ref":"#/definitions/ValueMappings"
},
"max":{
"$ref":"#/definitions/ConfFloat64"
},
"min":{
"$ref":"#/definitions/ConfFloat64"
},
"noValue":{
"description":"Alternative to empty string",
"type":"string",
"x-go-name":"NoValue"
},
"path":{
"description":"Path is an explicit path to the field in the datasource. When the frame meta includes a path,\nthis will default to `${frame.meta.path}/${field.name}\n\nWhen defined, this value can be used as an identifier within the datasource scope, and\nmay be used as an identifier to update values in a subsequent request",
"type":"string",
"x-go-name":"Path"
},
"thresholds":{
"$ref":"#/definitions/ThresholdsConfig"
},
"unit":{
"description":"Numeric Options",
"type":"string",
"x-go-name":"Unit"
},
"value":{
"type":"number",
"format":"double",
"x-go-name":"Value"
},
"writeable":{
"description":"Writeable indicates that the datasource knows how to update this value",
"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`.",
"description":"Deprecated: DataResponse -- this structure is deprecated, all new work should use backend.QueryDataResponse",
"description":"A map of RefIDs (unique query identifers) to this type makes up the Responses property of a QueryDataResponse.\nThe Error property is used to allow for partial success responses from the containing QueryDataResponse.",
"type":"object",
"title":"DataResponse contains the results from a DataQuery.",
"properties":{
"message":{
"type":"string",
"x-go-name":"Message"
"Error":{
"description":"Error is a property to be set if the the corresponding DataQuery has an error.",
"description":"A Field is essentially a slice of various types with extra properties and methods.\nSee NewField() for supported types.\n\nThe slice data in the Field is a not exported, so methods on the Field are used to to manipulate its data.",
"type":"object",
"title":"Field represents a typed column of data within a Frame.",
"properties":{
"config":{
"$ref":"#/definitions/FieldConfig"
},
"labels":{
"$ref":"#/definitions/Labels"
},
"name":{
"description":"Name is default identifier of the field. The name does not have to be unique, but the combination\nof name and Labels should be unique for proper behavior in all situations.",
"title":"FieldConfig represents the display properties for a Field.",
"properties":{
"color":{
"description":"Map values to a display color\nNOTE: this interface is under development in the frontend... so simple map for now",
"type":"object",
"additionalProperties":{
"type":"object"
},
"x-go-name":"Color"
},
"custom":{
"description":"Panel Specific Values",
"type":"object",
"additionalProperties":{
"type":"object"
},
"x-go-name":"Custom"
},
"decimals":{
"type":"integer",
"format":"uint16",
"x-go-name":"Decimals"
},
"description":{
"description":"Description is human readable field metadata",
"type":"string",
"x-go-name":"Description"
},
"displayName":{
"description":"DisplayName overrides Grafana default naming, should not be used from a data source",
"type":"string",
"x-go-name":"DisplayName"
},
"displayNameFromDS":{
"description":"DisplayNameFromDS overrides Grafana default naming in a better way that allows users to override it easily.",
"type":"string",
"x-go-name":"DisplayNameFromDS"
},
"filterable":{
"description":"Filterable indicates if the Field's data can be filtered by additional calls.",
"type":"boolean",
"x-go-name":"Filterable"
},
"interval":{
"description":"Interval indicates the expected regular step between values in the series.\nWhen an interval exists, consumers can identify \"missing\" values when the expected value is not present.\nThe grafana timeseries visualization will render disconnected values when missing values are found it the time field.\nThe interval uses the same units as the values. For time.Time, this is defined in milliseconds.",
"type":"number",
"format":"double",
"x-go-name":"Interval"
},
"links":{
"description":"The behavior when clicking on a result",
"type":"array",
"items":{
"$ref":"#/definitions/DataLink"
},
"x-go-name":"Links"
},
"mappings":{
"$ref":"#/definitions/ValueMappings"
},
"max":{
"$ref":"#/definitions/ConfFloat64"
},
"min":{
"$ref":"#/definitions/ConfFloat64"
},
"noValue":{
"description":"Alternative to empty string",
"type":"string",
"x-go-name":"NoValue"
},
"path":{
"description":"Path is an explicit path to the field in the datasource. When the frame meta includes a path,\nthis will default to `${frame.meta.path}/${field.name}\n\nWhen defined, this value can be used as an identifier within the datasource scope, and\nmay be used as an identifier to update values in a subsequent request",
"type":"string",
"x-go-name":"Path"
},
"thresholds":{
"$ref":"#/definitions/ThresholdsConfig"
},
"unit":{
"description":"Numeric Options",
"type":"string",
"x-go-name":"Unit"
},
"writeable":{
"description":"Writeable indicates that the datasource knows how to update this value",
"description":"Each Field is well typed by its FieldType and supports optional Labels.\n\nA Frame is a general data container for Grafana. A Frame can be table data\nor time series data depending on its content and field types.",
"type":"object",
"title":"Frame is a columnar data structure where each column is a Field.",
"properties":{
"Fields":{
"description":"Fields are the columns of a frame.\nAll Fields must be of the same the length when marshalling the Frame for transmission.",
"type":"array",
"items":{
"$ref":"#/definitions/Field"
}
},
"Meta":{
"$ref":"#/definitions/FrameMeta"
},
"Name":{
"description":"Name is used in some Grafana visualizations.",
"type":"string"
},
"RefID":{
"description":"RefID is a property that can be set to match a Frame to its originating query.",
"description":"https://github.com/grafana/grafana/blob/master/packages/grafana-data/src/types/data.ts#L11\nNOTE -- in javascript this can accept any `[key: string]: any;` however\nthis interface only exposes the values we want to be exposed",
"type":"object",
"title":"FrameMeta matches:",
"properties":{
"channel":{
"description":"Channel is the path to a stream in grafana live that has real-time updates for this data.",
"type":"string",
"x-go-name":"Channel"
},
"custom":{
"description":"Custom datasource specific values.",
"type":"object",
"x-go-name":"Custom"
},
"executedQueryString":{
"description":"ExecutedQueryString is the raw query sent to the underlying system. All macros and templating\nhave been applied. When metadata contains this value, it will be shown in the query inspector.",
"type":"string",
"x-go-name":"ExecutedQueryString"
},
"notices":{
"description":"Notices provide additional information about the data in the Frame that\nGrafana can display to the user in the user interface.",
"type":"array",
"items":{
"$ref":"#/definitions/Notice"
},
"x-go-name":"Notices"
},
"path":{
"description":"Path is a browsable path on the datasource.",
"type":"string",
"x-go-name":"Path"
},
"pathSeparator":{
"description":"PathSeparator defines the separator pattern to decode a hiearchy. The default separator is '/'.",
"type":"string",
"x-go-name":"PathSeparator"
},
"preferredVisualisationType":{
"$ref":"#/definitions/VisType"
},
"stats":{
"description":"Stats is an array of query result statistics.",
"description":"A FrameType string, when present in a frame's metadata, asserts that the\nframe's structure conforms to the FrameType's specification.\nThis property is currently optional, so FrameType may be FrameTypeUnknown even if the properties of\nthe Frame correspond to a defined FrameType.",
"description":"The embedded FieldConfig's display name must be set.\nIt corresponds to the QueryResultMetaStat on the frontend (https://github.com/grafana/grafana/blob/master/packages/grafana-data/src/types/data.ts#L53).",
"type":"object",
"title":"QueryStat is used for storing arbitrary statistics metadata related to a query and its result, e.g. total request time, data processing time.",
"properties":{
"color":{
"description":"Map values to a display color\nNOTE: this interface is under development in the frontend... so simple map for now",
"type":"object",
"additionalProperties":{
"type":"object"
},
"x-go-name":"Color"
},
"custom":{
"description":"Panel Specific Values",
"type":"object",
"additionalProperties":{
"type":"object"
},
"x-go-name":"Custom"
},
"decimals":{
"type":"integer",
"format":"uint16",
"x-go-name":"Decimals"
},
"description":{
"description":"Description is human readable field metadata",
"type":"string",
"x-go-name":"Description"
},
"displayName":{
"description":"DisplayName overrides Grafana default naming, should not be used from a data source",
"type":"string",
"x-go-name":"DisplayName"
},
"displayNameFromDS":{
"description":"DisplayNameFromDS overrides Grafana default naming in a better way that allows users to override it easily.",
"type":"string",
"x-go-name":"DisplayNameFromDS"
},
"filterable":{
"description":"Filterable indicates if the Field's data can be filtered by additional calls.",
"type":"boolean",
"x-go-name":"Filterable"
},
"interval":{
"description":"Interval indicates the expected regular step between values in the series.\nWhen an interval exists, consumers can identify \"missing\" values when the expected value is not present.\nThe grafana timeseries visualization will render disconnected values when missing values are found it the time field.\nThe interval uses the same units as the values. For time.Time, this is defined in milliseconds.",
"type":"number",
"format":"double",
"x-go-name":"Interval"
},
"links":{
"description":"The behavior when clicking on a result",
"type":"array",
"items":{
"$ref":"#/definitions/DataLink"
},
"x-go-name":"Links"
},
"mappings":{
"$ref":"#/definitions/ValueMappings"
},
"max":{
"$ref":"#/definitions/ConfFloat64"
},
"min":{
"$ref":"#/definitions/ConfFloat64"
},
"noValue":{
"description":"Alternative to empty string",
"type":"string",
"x-go-name":"NoValue"
},
"path":{
"description":"Path is an explicit path to the field in the datasource. When the frame meta includes a path,\nthis will default to `${frame.meta.path}/${field.name}\n\nWhen defined, this value can be used as an identifier within the datasource scope, and\nmay be used as an identifier to update values in a subsequent request",
"type":"string",
"x-go-name":"Path"
},
"thresholds":{
"$ref":"#/definitions/ThresholdsConfig"
},
"unit":{
"description":"Numeric Options",
"type":"string",
"x-go-name":"Unit"
},
"value":{
"type":"number",
"format":"double",
"x-go-name":"Value"
},
"writeable":{
"description":"Writeable indicates that the datasource knows how to update this value",
Will Browne
3 years ago
committed by