drill-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bridg...@apache.org
Subject [03/31] drill git commit: add rest api docs
Date Wed, 25 Nov 2015 22:02:51 GMT
add rest api docs


Project: http://git-wip-us.apache.org/repos/asf/drill/repo
Commit: http://git-wip-us.apache.org/repos/asf/drill/commit/16526046
Tree: http://git-wip-us.apache.org/repos/asf/drill/tree/16526046
Diff: http://git-wip-us.apache.org/repos/asf/drill/diff/16526046

Branch: refs/heads/gh-pages
Commit: 16526046e8d3e9d1add6746817467301606613f1
Parents: db9efbb
Author: Kristine Hahn <khahn@maprtech.com>
Authored: Fri Nov 20 14:14:08 2015 -0800
Committer: Kristine Hahn <khahn@maprtech.com>
Committed: Wed Nov 25 10:13:41 2015 -0800

----------------------------------------------------------------------
 _data/docs.json                             |  71 +++-
 _docs/developer-information/009-rest-api.md | 414 +++++++++++++++++++++++
 2 files changed, 475 insertions(+), 10 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/drill/blob/16526046/_data/docs.json
----------------------------------------------------------------------
diff --git a/_data/docs.json b/_data/docs.json
index 3f2fc11..4f0fd71 100644
--- a/_data/docs.json
+++ b/_data/docs.json
@@ -2671,8 +2671,8 @@
             "next_title": "Compiling Drill from Source", 
             "next_url": "/docs/compiling-drill-from-source/", 
             "parent": "Developer Information", 
-            "previous_title": "Developer Information", 
-            "previous_url": "/docs/developer-information/", 
+            "previous_title": "REST API", 
+            "previous_url": "/docs/rest-api/", 
             "relative_path": "_docs/developer-information/010-develop-drill.md", 
             "title": "Develop Drill", 
             "url": "/docs/develop-drill/"
@@ -2687,6 +2687,23 @@
                             "url": "/docs/developer-information/"
                         }
                     ], 
+                    "children": [], 
+                    "next_title": "Develop Drill", 
+                    "next_url": "/docs/develop-drill/", 
+                    "parent": "Developer Information", 
+                    "previous_title": "Developer Information", 
+                    "previous_url": "/docs/developer-information/", 
+                    "relative_path": "_docs/developer-information/009-rest-api.md", 
+                    "title": "REST API", 
+                    "url": "/docs/rest-api/"
+                }, 
+                {
+                    "breadcrumbs": [
+                        {
+                            "title": "Developer Information", 
+                            "url": "/docs/developer-information/"
+                        }
+                    ], 
                     "children": [
                         {
                             "breadcrumbs": [
@@ -2734,8 +2751,8 @@
                     "next_title": "Compiling Drill from Source", 
                     "next_url": "/docs/compiling-drill-from-source/", 
                     "parent": "Developer Information", 
-                    "previous_title": "Developer Information", 
-                    "previous_url": "/docs/developer-information/", 
+                    "previous_title": "REST API", 
+                    "previous_url": "/docs/rest-api/", 
                     "relative_path": "_docs/developer-information/010-develop-drill.md",

                     "title": "Develop Drill", 
                     "url": "/docs/develop-drill/"
@@ -2924,8 +2941,8 @@
                     "url": "/docs/design-docs/"
                 }
             ], 
-            "next_title": "Develop Drill", 
-            "next_url": "/docs/develop-drill/", 
+            "next_title": "REST API", 
+            "next_url": "/docs/rest-api/", 
             "parent": "", 
             "previous_title": "Troubleshooting", 
             "previous_url": "/docs/troubleshooting/", 
@@ -7541,6 +7558,23 @@
             "title": "REPEATED_COUNT", 
             "url": "/docs/repeated-count/"
         }, 
+        "REST API": {
+            "breadcrumbs": [
+                {
+                    "title": "Developer Information", 
+                    "url": "/docs/developer-information/"
+                }
+            ], 
+            "children": [], 
+            "next_title": "Develop Drill", 
+            "next_url": "/docs/develop-drill/", 
+            "parent": "Developer Information", 
+            "previous_title": "Developer Information", 
+            "previous_url": "/docs/developer-information/", 
+            "relative_path": "_docs/developer-information/009-rest-api.md", 
+            "title": "REST API", 
+            "url": "/docs/rest-api/"
+        }, 
         "RPC Overview": {
             "breadcrumbs": [
                 {
@@ -15686,6 +15720,23 @@
                             "url": "/docs/developer-information/"
                         }
                     ], 
+                    "children": [], 
+                    "next_title": "Develop Drill", 
+                    "next_url": "/docs/develop-drill/", 
+                    "parent": "Developer Information", 
+                    "previous_title": "Developer Information", 
+                    "previous_url": "/docs/developer-information/", 
+                    "relative_path": "_docs/developer-information/009-rest-api.md", 
+                    "title": "REST API", 
+                    "url": "/docs/rest-api/"
+                }, 
+                {
+                    "breadcrumbs": [
+                        {
+                            "title": "Developer Information", 
+                            "url": "/docs/developer-information/"
+                        }
+                    ], 
                     "children": [
                         {
                             "breadcrumbs": [
@@ -15733,8 +15784,8 @@
                     "next_title": "Compiling Drill from Source", 
                     "next_url": "/docs/compiling-drill-from-source/", 
                     "parent": "Developer Information", 
-                    "previous_title": "Developer Information", 
-                    "previous_url": "/docs/developer-information/", 
+                    "previous_title": "REST API", 
+                    "previous_url": "/docs/rest-api/", 
                     "relative_path": "_docs/developer-information/010-develop-drill.md",

                     "title": "Develop Drill", 
                     "url": "/docs/develop-drill/"
@@ -15923,8 +15974,8 @@
                     "url": "/docs/design-docs/"
                 }
             ], 
-            "next_title": "Develop Drill", 
-            "next_url": "/docs/develop-drill/", 
+            "next_title": "REST API", 
+            "next_url": "/docs/rest-api/", 
             "parent": "", 
             "previous_title": "Troubleshooting", 
             "previous_url": "/docs/troubleshooting/", 

http://git-wip-us.apache.org/repos/asf/drill/blob/16526046/_docs/developer-information/009-rest-api.md
----------------------------------------------------------------------
diff --git a/_docs/developer-information/009-rest-api.md b/_docs/developer-information/009-rest-api.md
new file mode 100644
index 0000000..ed775f8
--- /dev/null
+++ b/_docs/developer-information/009-rest-api.md
@@ -0,0 +1,414 @@
+---
+title: "REST API"
+parent: "Developer Information"
+---
+
+You can use RESTful requests for programmatically performing the same set of operations as
the [Drill Web Console](/starting-the-web-console/). For example, you can run queries, perform
storage plugin task, such as creating a storage plugin, obtain profiles of queries, and get
current memory metrics. 
+
+This document describes the Drill REST API commands. Commands having a .json suffix output
return a JSON response body. Generally, these commands return HTML when used without the .json
suffix.
+
+## Requests and Examples
+
+The REST requests connect to Drill using the familiar Web Console URI:
+
+http://<IP address or host name>:8047
+
+Examples using cURL are provided. Several examples use the donuts.json file. To download
this file, go to [Drill test resources](https://github.com/apache/drill/blob/master/exec/java-exec/src/test/resources)
page, locate donuts.json in the list of files, and download it. When using cURL, use unicode
\u0027 for the single quotation mark as shown in the Query example.
+
+Before running REST requests, [start Drill]({{site.baseurl}}/docs/starting-drill-on-linux-and-mac-os-x).
+
+## Links to HTTP Methods
+
+The following short description of methods link to more information and examples:
+
+* Submit a query to Drill and return query results. 
+* 
+
+## Options
+These methods get and set system options.
+
+### GET /options.json
+
+List the name, default, and data type of the system and session options.
+
+**Example**
+
+     curl http://localhost:8047/options.json
+
+**Response Body**
+
+        [ {
+          "name" : "planner.broadcast_factor",
+          "value" : 1.0,
+          "type" : "SYSTEM",
+          "kind" : "DOUBLE"
+        }, 
+
+        . . .
+
+        {
+          "name" : "store.parquet.compression",
+          "value" : "snappy",
+          "type" : "SYSTEM",
+          "kind" : "STRING"
+        },
+
+        . . .
+
+        {
+          "name" : "exec.enable_union_type",
+          "value" : false,
+          "type" : "SYSTEM",
+          "kind" : "BOOLEAN"
+        } ]
+
+### POST /option/{optionName}
+
+Change the value or session/system type of the named option.
+
+**Parameter**
+optionName--The name of a [Drill system option]({{site.baseurl}}/docs/configuration-options-introduction/#system-options).
+
+**Request Body**
+Enclose option values of kind STRING in double quotation marks.
+
+        {
+          "name" : "<option name>",
+          "value" : ["]<new value>["],
+          "type" : "<SYSTEM or SESSION>",
+          "kind" : "<option data type>"
+        }
+
+**Example**
+        curl -X POST -H "Content-Type: application/json" -d '{"name" : "store.json.all_text_mode",
"value" : true, "type" : "SYSTEM", "kind" : "BOOLEAN"}' http://localhost:8047/option/store.json.all_text_mode
+
+<!-- Not merged yet, need to test -->
+
+**Response Body**
+        {
+          "result" : "success"
+        }
+
+## Profile
+
+These methods get query profiles. 
+
+### GET /profiles.json
+
+Get the profiles of running and completed queries. 
+
+**Example**
+
+     curl http://localhost:8047/profiles.json
+
+**Response Body**
+
+        {
+          "runningQueries" : [ ],
+          "finishedQueries" : [ {
+            "queryId" : "29b2e988-35e7-4c85-3151-32c7d3347f15",
+            "time" : "11/18/2015 16:23:19",
+            "location" : "http://localhost:8047/profile/29b2e988-35e7-4c85-3151-32c7d3347f15.json",
+            "foreman" : "10.250.50.31",
+            "query" : "select * from dfs.`/Users/joe-user/apache-drill-1.3.0/sample-data/donuts.json`
where name= 'Cake'",
+            "state" : "COMPLETED",
+            "user" : "anonymous"
+          }, 
+          . . .
+
+### GET /profiles/{queryid}.json
+
+Get the profile of given queryid.
+
+**Parameter**
+queryid--The UUID of the query in [standard UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier)
format that Drill assigns to each query. 
+
+**Example**
+
+     curl http://localhost:8047/profiles/29b2e988-35e7-4c85-3151-32c7d3347f15.json
+
+**Response Body**
+
+        {"id":{"part1":3004720672638717061,"part2":3553677414795345685},"type":1,"start":1447892599827,"end":1447892599950,"query":"select
* from dfs.`/Users/joe-user/drill/apache-drill-1.3.0/sample-data/donuts.json` where name=
'Cake'","plan":"00-00    Screen : rowType = RecordType(ANY *): 
+        . . ."lastUpdate":1447892599950,"lastProgress":1447892599950}]}],"user":"anonymous"}
+
+### GET /profiles/cancel/{queryid}
+
+Cancel the query having the given queryid.
+
+**Parameter**
+queryid--The UUID of the query in [standard UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier)
format that Drill assigns to each query. 
+
+**Example**
+
+     curl http://localhost:8047/profiles/cancel/29b2e988-35e7-4c85-3151-32c7d3347f15
+
+**Response Body**
+
+        {
+          "result" : "success"
+        }
+
+## Query
+
+The query methods  
+
+### POST /query.json
+
+Submits a query, waits until the query completes, and then returns the results as single
JSON object.
+
+**Parameters**
+
+* queryType--SQL, PHYSICAL, or LOGICAL are valid types. Use only "SQL". Other types are for
internal use only.  
+* query--A SQL query that runs in Drill.
+
+**Request Body**
+        {
+          "queryType" : "SQL",
+          "query" : "<Drill query>"
+        }
+
+**Example**
+
+     curl -X POST -H "Content-Type: application/json" -d '{"queryType":"SQL", "query": "select
* from dfs.`/Users/joe-user/apache-drill-1.3.0/sample-data/donuts.json` where name= \u0027Cake\u0027"}'
http://localhost:8047/query.json
+
+**Response Body**
+
+     {
+       "columns" : [ "id", "type", "name", "ppu", "sales", "batters", "topping", "filling"
],
+       "rows" : [ {
+         "id" : "0001",
+         "sales" : "35",
+         "name" : "Cake",
+         "topping" : "[{\"id\":\"5001\",\"type\":\"None\"},{\"id\":\"5002\",\"type\":\"Glazed\"},{\"id\":\"5005\",\"type\":\"Sugar\"},{\"id\":\"5007\",\"type\":\"Powdered
Sugar\"},{\"id\":\"5006\",\"type\":\"Chocolate with Sprinkles\"},{\"id\":\"5003\",\"type\":\"Chocolate\"},{\"id\":\"5004\",\"type\":\"Maple\"}]",
+         "ppu" : "0.55",
+         "type" : "donut",
+         "batters" : "{\"batter\":[{\"id\":\"1001\",\"type\":\"Regular\"},{\"id\":\"1002\",\"type\":\"Chocolate\"},{\"id\":\"1003\",\"type\":\"Blueberry\"},{\"id\":\"1004\",\"type\":\"Devil's
Food\"}]}",
+         "filling" : "[]"
+       } ]
+     }
+
+## Storage
+
+The storage REST methods manage Drill storage plugin configurations.
+
+### GET /storage.json
+
+Get the list of storage plugin names and configurations.
+
+**Example**
+
+     curl http://localhost:8047/storage.json
+
+**Response Body**
+
+        [ {
+          "name" : "cp",
+          "config" : {
+            "type" : "file",
+            "enabled" : true,
+            "connection" : "classpath:///",
+            "workspaces" : null,
+            "formats" : {
+              "csv" : {
+                "type" : "text",
+                "extensions" : [ "csv" ],
+                "delimiter" : ","
+              },
+        . . .
+        {
+          "name" : "mongo",
+          "config" : {
+            "type" : "mongo",
+            "connection" : "mongodb://localhost:27017/",
+            "enabled" : false
+          }
+        } ]
+
+### GET /storage/{name}.json
+
+Get the named storage plugin name and configuration.
+
+**Parameter**
+name--The assigned name in the storage plugin definition.
+
+**Example**
+
+     curl http://localhost:8047/storage/mongo.json
+
+**Response Body**
+
+        {
+          "name" : "mongo",
+          "config" : {
+            "type" : "mongo",
+            "connection" : "mongodb://localhost:27017/",
+            "enabled" : false
+          }
+        }
+
+### Get /storage/{name}/enable/{val}
+
+Enable or disable the named storage plugin.
+
+**Parameters**
+* name--The assigned name in the storage plugin definition.
+* val--Either true (to enable) or false (to disable).
+
+**Example**
+
+     curl http://localhost:8047/storage/mongo/enable/true
+
+**Response Body**
+
+{
+  "result" : "success"
+}
+
+### POST /storage/{name}.json
+
+Create or update a storage plugin configuration.
+
+**Parameters**
+name--The name of the storage plugin configuration to create or update.
+
+**Request Body**
+
+     {
+        "name" : "<name of storage plugin configuration>",
+        "config" : {
+          "type" : "<type of storage plugin>",
+          "enabled" : <true or false>,
+            "connection" : "<type of distributed file system and address/path>",
+            "workspaces" : <null or unique workspace name>,
+            "formats" : <file format definitions> 
+        }
+     }
+
+Valid storage plugin types include file, hbase, hive, mongo, and jdbc. Construct the request
body using storage plugin [attributes and definitions]({{site.baseurl}}/docs/plugin-configuration-basics/#list-of-attributes-and-definitions).
The request body overwrites the existing configuration if there is any, and therefore, must
include all required attributes and definitions.
+
+**Example**
+
+     curl -X POST -H "Content-Type: application/json" -d '{"name":"myplugin", "config": {"type":
"file", "enabled": false, "connection": "file:///", "workspaces": { "root": { "location":
"/", "writable": false, "defaultInputFormat": null}}, "formats": null}}' http://localhost:8047/storage/myplugin.json
+
+**Response Body**
+
+{
+  "result" : "success"
+}
+
+### DELETE /storage/{name}.json
+
+Delete a storage plugin configuration.
+
+**Parameter**
+name--The name of the storage plugin configuration to delete.
+
+**Example**
+
+     curl -X DELETE -H "Content-Type: application/json" http://localhost:8047/storage/myplugin.json
+
+**Response Body**
+
+        {
+          "result" : "success"
+        }
+
+## Metrics
+
+Gets metric information.
+
+### GET /stats.json
+
+Returns Drillbit stats such as ports and max direct memory.
+
+**Example**
+
+     curl http://localhost:8047/stats.json
+
+**Response Body**
+
+        [ {
+          "name" : "Number of Drill Bits",
+          "value" : 1
+        }, {
+          "name" : "Bit #0",
+          "value" : "10.250.50.31 initialized"
+        }, {
+          "name" : "Data Port Address",
+          "value" : "10.250.50.31:31012"
+        }, {
+          "name" : "User Port Address",
+          "value" : "10.250.50.31:31010"
+        }, {
+          "name" : "Control Port Address",
+          "value" : "10.250.50.31:31011"
+        }, {
+          "name" : "Maximum Direct Memory",
+          "value" : 8589934592
+        } ]
+
+### GET /status
+
+Get the status of Drill. 
+
+**Example**
+
+     curl http://localhost:8047/status
+
+**Response Body**
+
+          <!DOCTYPE html>
+          . . .
+
+            <div class="alert alert-success">
+              <strong>Running!</strong>
+          . . .
+
+          </html>
+
+
+### GET /status/metrics
+
+Get the current memory metrics.
+
+**Example**
+
+     curl http://localhost:8047/status/metrics
+
+**Response Body**
+
+        {"version":"3.0.0","gauges":{"PS-MarkSweep.count":{"value":0},"PS-MarkSweep.time":{"value":0},"PS-Scavenge.count":{"value":1},"PS-Scavenge.time":{"value":74},"blocked.
+         . . .
+        ,"drill.allocator.normal.hist":{"count":84,"max":1024,"mean":273.6666666666667,"min":12,"p50":256.0,"p75":448.0,"p95":896.0,"p98":1024.0,"p99":1024.0,"p999":1024.0,"stddev":248.17013855555368}},"meters":{},"timers":{}}
+
+### GET /status/threads
+
+Get status of threads.
+
+**Example**
+
+     curl http://localhost:8047/status/threads
+
+**Response Body**
+
+        main id=1 state=RUNNABLE (running in native)
+            at java.io.FileInputStream.read0(Native Method)
+            at java.io.FileInputStream.read(FileInputStream.java:210)
+        . . .
+
+        threadDeathWatcher-2-1 id=49 state=TIMED_WAITING
+            at java.lang.Thread.sleep(Native Method)
+            at io.netty.util.ThreadDeathWatcher$Watcher.run(ThreadDeathWatcher.java:137)
+            at io.netty.util.concurrent.DefaultThreadFactory$DefaultRunnableDecorator.run(DefaultThreadFactory.java:137)
+            at java.lang.Thread.run(Thread.java:745)
+
+        Scheduler-1174655113 id=50 state=TIMED_WAITING
+            - waiting on <0x738fda67> (a java.util.concurrent.locks.AbstractQueuedSynchronizer$ConditionObject)
+            - locked <0x738fda67> (a java.util.concurrent.locks.AbstractQueuedSynchronizer$ConditionObject)
+        . . .
+
+
+
+
+


Mime
View raw message