Command API

Commands can be submitted to BigObject via HTTP to /api endpoint.

POST /api

HTTP REQUEST

A command is described in the HTTP POST body as a JSON object. Possible values are:

• stmt : Statement to issue.
• params (optional): Additional parameters to control the responded JSON object. Possible values are:
  • size : Number of returned rows (from 1 to 1000). The default value is 1000.

Example request

{
    "stmt": "SELECT * FROM sales LIMIT 100000",
    "params": {
        "size": 25
    }
}

HTTP RESPONSE

Bigobject will response with HTTP status code 200

HTTP/1.1 200 OK
Content-Type: application/json

The message body will contain a JSON object of the following keys:

• retcode
  • 0 if successful, a negative number otherwise.
• errmsg (Optional)
  • Failed error message.
• meta
  • Description dict of the returned results.
• results
  • Returned data.

The returned JSON for each command is described below.

CREATE, DROP, INSERT, UPDATE, TRIM, GC(DEL, ALL)

• Returns
  • results: null

Example request:

{
    "stmt": "CREATE TABLE Pi (id INT64, method STRING, `estimated_pi` DOUBLE, KEY(id))"
}

Example response:

{
    "retcode": 0,
    "meta": {
    },
    "results": null
}

SHOW

• Returns
  • meta
    • size: number of data returned
  • results: list of data returned

Example request body:

{
    "stmt": "SHOW TABLES"
}

Example response:

{
    "retcode": 0,
    "meta": {
          "size": 20
    },
    "results": [
        ["Product"],
        ["Customer"],
        ["sales"],
        ...
        ["facebook_likes_2012"]
    ]
}

SELECT, FIND, GET

• Params
  • handle (bool): to return the handle id for later access
• Returns
  • meta
    • size: number of data returned
    • next: next starting index. -1 if no more data
  • results: list of data returned. Return handle ID if param is set

Example request body:

{
    "stmt": "SELECT * FROM Pi"
}

Example response:

{
    "retcode": 0,
    "meta": {
        "size": 1000,
        "next": 1001
    },
    "results": [
        [1, "cosine", 3.14],
        [2, "maple", 3.141],
        [3, "monte-carlo", 3.1415],
        ...
    ]
}

Example request body (using handle):

{
    "stmt": "SELECT * FROM Pi",
    "params": {
        "handle": true
    }
}

Example response:

{
    "retcode": 0,
    "meta": {},
    "results": {
        "res": "12cf0a5dee76"
    }
}

SCAN

• Params
  • None
• Returns
  • meta
    • size: number of data returned
    • next: next starting index. -1 if no more data
  • results: list of data returned

The syntax for retrieving data is specified in the following format (case insensitive). This is provided in the stmt field in the request payload.

SCAN <RESOURCE_ID> <START> <END>

START and END positions are inclusive.

Examples (case insensitive):

• SCAN 12cf0a5dee76 Scan all data, each data chunk will be the default page size
• SCAN 12cf0a5dee76 145 Scan data from index 145 to the end
• SCAN 12cf0a5dee76 100 9922 Scan data from index 100 to index 9922

Example request body:

{
    "stmt": "SCAN 12cf0a5dee76 5001 10000"
}

Example response:

{
    "retcode": 0,
    "meta": {
        "size": 1000,
        "next": 6001
    },
    "results": [
        [5001, "method5001", 3.14],
        [5002, "`method`5002", 3.141],
        [5003, "`method`5003", 3.1415],
        ...
        [6000, "`method6000`", 3.1415926...]
    ]
}

DESC, HDESC

• Returns
  • results: map context, query metatdata in created resource

Example request body:

{
    "stmt": "DESC Pi"
}

Example response:

{
    "retcode": 0,
    "meta": {},
    "results": {
        "create_stmt": "CREATE TABLE Pi (id INT64, method STRING, ``estimated_pi`` DOUBLE, KEY(id))"
        "name": "Pi",
        "schema": {
            "attr": [
                {   "name": "id", "type": "INT64" },
                {   "name": "method", "type": "STRING" },
                {   "name": "estimated_pi", "type": "DOUBLE" }
            ],
            "key": [ "id" ]
        },
        "size": 31415926
    }
}

GC LIST

• Returns
  • meta
    • size: number of data returned
  • results: list of data returned

Example request body:

{
    "stmt": "GC LIST"
}

Example response:

{
    "retcode": 0,
    "meta": {
          "size": 4
    },
    "results": ["aabbccddeeff0011", "0011223344556677", "6677889900aabbcc", "0123456789abcdef"]
}

GC

Resource allocated from SELECT, FIND and GET with handle in params field set is subject to garbage collection after an extended idle session. While the default behavior by the aforementioned command will be released as soon as the the data stream ended, success or otherwise.