Merge pull request #146 from dai-chen/sql-plugin-basic-usage-docs

SQL plugin docs for basic usage

Author: aetter

docs/sql/endpoints.md

@@ -0,0 +1,119 @@
+---
+layout: default
+title: Endpoints
+parent: SQL
+nav_order: 4
+---
+
+
+# Endpoints
+
+---
+
+#### Table of contents
+- TOC
+{:toc}
+
+
+---
+
+## Introduction
+
+To send query request to SQL plugin, you can either use a request
+parameter in HTTP GET or request body by HTTP POST request. POST request
+is recommended because it doesn't have length limitation and allows for
+other parameters passed to plugin for other functionality such as
+prepared statement. And also the explain endpoint is used very often for
+query translation and troubleshooting.
+
+## GET
+
+### Description
+
+You can send HTTP GET request with your query embedded in URL parameter.
+
+### Example
+
+SQL query:
+
+```console
+    >> curl -H 'Content-Type: application/json' -X GET localhost:9200/_opendistro/_sql?sql=SELECT * FROM accounts
+```
+
+## POST
+
+### Description
+
+You can also send HTTP POST request with your query in request body.
+
+### Example
+
+SQL query:
+
+```console
+    >> curl -H 'Content-Type: application/json' -X POST localhost:9200/_opendistro/_sql -d '{
+      "query" : "SELECT * FROM accounts"
+    }'
+```
+
+## Explain
+
+### Description
+
+To translate your query, send it to explain endpoint. The explain output
+is Elasticsearch domain specific language (DSL) in JSON format. You can
+just copy and paste it to your console to run it against Elasticsearch
+directly.
+
+### Example
+
+Explain query:
+
+```console
+    >> curl -H 'Content-Type: application/json' -X POST localhost:9200/_opendistro/_sql/_explain -d '{
+      "query" : "SELECT firstname, lastname FROM accounts WHERE age > 20"
+    }'
+```
+
+Explain:
+
+```json
+    {
+      "from" : 0,
+      "size" : 200,
+      "query" : {
+        "bool" : {
+          "filter" : [
+            {
+              "bool" : {
+                "must" : [
+                  {
+                    "range" : {
+                      "age" : {
+                        "from" : 20,
+                        "to" : null,
+                        "include_lower" : false,
+                        "include_upper" : true,
+                        "boost" : 1.0
+                      }
+                    }
+                  }
+                ],
+                "adjust_pure_negative" : true,
+                "boost" : 1.0
+              }
+            }
+          ],
+          "adjust_pure_negative" : true,
+          "boost" : 1.0
+        }
+      },
+      "_source" : {
+        "includes" : [
+          "firstname",
+          "lastname"
+        ],
+        "excludes" : [ ]
+      }
+    }
+```

docs/sql/monitoring.md

@@ -0,0 +1,61 @@
+---
+layout: default
+title: Plugin Monitoring
+parent: SQL
+nav_order: 7
+---
+
+# Plugin Monitoring
+
+---
+
+#### Table of contents
+- TOC
+{:toc}
+
+
+---
+
+## Introduction
+
+By a stats endpoint, you are able to collect metrics for the plugin
+within the interval. Note that only node level statistics collecting is
+implemented for now. In other words, you only get the metrics for the
+node you're accessing. Cluster level statistics have yet to be
+implemented.
+
+## Node Stats
+
+### Description
+
+The meaning of fields in the response is as follows:
+
+|                 Field name|                                                    Description|
+| ------------------------- | ------------------------------------------------------------- |
+|              request_total|                                         Total count of request|
+|              request_count|                     Total count of request within the interval|
+|failed_request_count_syserr|Count of failed request due to system error within the interval|
+|failed_request_count_cuserr| Count of failed request due to bad request within the interval|
+|    failed_request_count_cb| Indicate if plugin is being circuit broken within the interval|
+
+
+### Example
+
+SQL query:
+
+```console
+    >> curl -H 'Content-Type: application/json' -X GET localhost:9200/_opendistro/_sql/stats
+```
+
+Result set:
+
+```json
+    {
+      "failed_request_count_cb" : 0,
+      "failed_request_count_cuserr" : 0,
+      "circuit_breaker" : 0,
+      "request_total" : 0,
+      "request_count" : 0,
+      "failed_request_count_syserr" : 0
+    }
+```