POST /cmd


BigObject Remote API is designed to meet the minimum dependency requirements for most developers by providing RESTful contract with improved latency by WebSocket. Commands are curl-able and uncomplicated.

{
    "Stmt": "AS_SPECIFIED_IN_BOSH",
    "Workspace": "YOUR_WORK_SPACE",
    "Opts": `JSON-DOCUMENT-BY-CONTEXT`
}
Optional fields
Both `Workspace` and `Opts` may be omitted if empty.

The reply format is generally structured with two required fields

{
    "Content": `JSON-DOCUMENT-BY-CONTEXT`,
    "Err": "ERROR_MESSAGE_OR_EMPTY"
}

For any command that results in an error, Content field will be null, with Err field set to corresponding text.


Return Content by Context


CREATE, DROP, INSERT, UPDATE, TRIM

Returns null context

{
    "Content": null,
    "Err": "ERROR_MESSAGE_OR_EMPTY"
}

SHOW

Returns list context

{
    "Content": [
        "ITEM_1",
        "ITEM_2",
        "ITEM_3",
        ...
    ],
    "Err": "ERROR_MESSAGE_OR_EMPTY"
}

SELECT, FIND, GET

Returns chunked map context

{
    "Content": {
        "content": [
            [...],
            [...],
            ...
        ],
        "index": NEXT_POSITION_INT_64
    },
    "Err": "ERROR_MESSAGE_OR_EMPTY"
}
...
{
    "Content": {
        "content": [
            [...],
            [...],
            ...
        ],
        "index": -1
    },
    "Err": "ERROR_MESSAGE_OR_EMPTY"
}

The data stream ends when index is -1.

In some cases, it might be beneficial to keep the result set for later access. Users can do so by setting Handle in the Opts field:

{
    "Stmt": "AS_SPECIFIED_IN_BOSH",
    "Opts": {
        "Handle": true
    }
}

Returns map context, creating resource

{
    "Content": {
        "res": "RESOURCE_ID"
    },
    "Err": "ERROR_MESSAGE_OR_EMPTY"
}

See SCAN for details on how to access data in opend resource. Review GC for information on resource garbage collection.

DESC, HDESC

Returns map context, query metatdata in created resource

{
    "Content": {
        "create_stmt": "CREATE TABLE TABLE_NAME (ATTR_1 ATTR_1_TYPE, ATTR_2 ATTR_2_TYPE, KEY(ATTR_1))"
        "name": "TABLE_NAME",
        "schema": {
            "attr": [
                {
                    "name": "ATTR_1",
                    "type": "ATTR_1_TYPE"
                },
                {
                    "name": "ATTR_2",
                    "type": "ATTR_2_TYPE"
                }
            ],
            "key": [
                "ATTR_1"
            ]
        },
        "size": SIZE_OF_TABLE
    },
    "Err": "ERROR_MESSAGE_OR_EMPTY"
}
HDESC
HDESC is used to retrieve the schema for a resource_id handler

SCAN

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> <PAGE>

START and END positions are inclusive. PAGE defines the chunk size. The maximum allowed data chunk size is 1000.

White space handling
Users must make sure no duplicate white space in between string literates

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.
  • SCAN 12cf0a5dee76 1 -1 500
    Scan data from begin to end, adjusting chunk size to 500

Returns chunked map context

{
    "Content": {
        "content": [
            [...],
            [...],
            ...
        ],
        "index": NEXT_POSITION_INT_64
    },
    "Err": "ERROR_MESSAGE_OR_EMPTY"
}
...
{
    "Content": {
        "content": [
            [...],
            [...],
            ...
        ],
        "index": -1
    },
    "Err": "ERROR_MESSAGE_OR_EMPTY"
}

The data stream ends when index is -1.

GC

Resource allocated from SELECT, FIND, GET with Handle in Opts field set is subject to garbage collection after an extended idle session.

While default behavior by the aforementioned command will be released as soon as the the data stream ended, success or otherwise.

  • GC LIST:
    Retrieves a list of active resources opened.

    Returns list context

    {
        "Content": [
            "ITEM_1",
            "ITEM_2",
            "ITEM_3",
            ...
        ],
        "Err": "ERROR_MESSAGE_OR_EMPTY"
    }
  • GC DEL RESOURCE_ID:
    Marks resource to be recycled as soon as possible.

    Returns null context

    {
        "Content": null,
        "Err": "ERROR_MESSAGE_OR_EMPTY"
    }
  • GC ALL
    Marks all opended resource to be recycled as soon as possible

    Returns null context

    {
        "Content": null,
        "Err": "ERROR_MESSAGE_OR_EMPTY"
    }
Automatic GC timer
Users can set BO_GC_TIMER environment variable a minimum time (in seconds) allowed for a resource to be idle.