From d912970aff3b9f26dae70ea6c68d9aae6b40f9aa Mon Sep 17 00:00:00 2001
From: achatterjee-grafana
 <70489351+achatterjee-grafana@users.noreply.github.com>
Date: Mon, 22 Feb 2021 13:44:24 -0500
Subject: [PATCH] Added section Query a time series database by id (#31337)

* Added new section Query a time series database by id

* Rearranged content.

* changed database to data source

* Updated note with the word Grafana

* fixed a few typos.

* Removed "time series" as per review.

* Update docs/sources/http_api/data_source.md

Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>

* Changes from Diana's review.

Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>
---
 docs/sources/http_api/data_source.md | 107 +++++++++++++++++++++++++++
 1 file changed, 107 insertions(+)

diff --git a/docs/sources/http_api/data_source.md b/docs/sources/http_api/data_source.md
index f4a7aa5fc1a..1d16e50a93f 100644
--- a/docs/sources/http_api/data_source.md
+++ b/docs/sources/http_api/data_source.md
@@ -497,3 +497,110 @@ Content-Type: application/json
 `GET /api/datasources/proxy/:datasourceId/*`
 
 Proxies all calls to the actual data source.
+
+## Query a data source by ID
+
+Queries a data source having backend implementation.
+
+`POST /api/tsdb/query`
+
+> **Note:** Most of Grafana's builtin data sources have 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"
+    }
+  ]
+}
+```
+> **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.
+
+In addition, each data source has its own specific properties that should be added in a request.
+
+**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"
+      },
+      "series": [
+        {
+          "name": "Opened",
+          "points": [
+            [
+              109,
+              1420070400000
+            ],
+            [
+              122,
+              1422748800000
+            ]
+          ]
+        },
+        {
+          "name": "Closed",
+          "points": [
+            [
+              89,
+              1420070400000
+            ]
+          ]
+        }
+      ]
+    }
+  }
+}
+```