HTTP API to AsterixDB

Table of Contents

DDL API [Back to TOC]

End point for the data definition statements

Endpoint: /ddl

Parameters:

Parameter Description Required?
ddl String containing DDL statements to modify Metadata Yes

This call does not return any result. If the operations were successful, HTTP OK status code is returned.

Example

DDL Statements

    drop dataverse company if exists;
    create dataverse company;
    use dataverse company;

    create type Emp as open {
      id : int32,
      name : string
    };

    create dataset Employee(Emp) primary key id;

API call for the above DDL statements in the URL-encoded form.

[http://localhost:19002/ddl?ddl=drop%20dataverse%20company%20if%20exists;create%20dataverse%20company;use%20dataverse%20company;create%20type%20Emp%20as%20open%20{id%20:%20int32,name%20:%20string};create%20dataset%20Employee(Emp)%20primary%20key%20id;](http://localhost:19002/ddl?ddl=drop%20dataverse%20company%20if%20exists;create%20dataverse%20company;use%20dataverse%20company;create%20type%20Emp%20as%20open%20{id%20:%20int32,name%20:%20string};create%20dataset%20Employee(Emp)%20primary%20key%20id;)

Response

HTTP OK 200
<NO PAYLOAD>

Update API [Back to TOC]

End point for update statements (INSERT, DELETE and LOAD)

Endpoint: /update

Parameters:

Parameter Description Required?
statements String containing update (insert/delete) statements to execute Yes

This call does not return any result. If the operations were successful, HTTP OK status code is returned.

Example

Update Statements

    use dataverse company;

    insert into dataset Employee({ "id":123,"name":"John Doe"});

API call for the above update statement in the URL-encoded form.

[http://localhost:19002/update?statements=use%20dataverse%20company;insert%20into%20dataset%20Employee({%20%22id%22:123,%22name%22:%22John%20Doe%22});](http://localhost:19002/update?statements=use%20dataverse%20company;insert%20into%20dataset%20Employee({%20%22id%22:123,%22name%22:%22John%20Doe%22});)

Response

HTTP OK 200
<NO PAYLOAD>

Query API [Back to TOC]

End point for query statements

Endpoint: /query

Parameters:

Parameter Description Required?
query Query string to pass to ASTERIX for execution Yes
mode Indicate if call should be synchronous or asynchronous. mode = synchronous blocks the call until results are available; mode = asynchronous returns immediately with a handle that can be used later to check the query’s status and to fetch results when available No. default mode = synchronous

Result: The result is returned as a JSON object as follows

    {
       results: <result as a string, if mode = synchronous>
       error-code: [<code>, <message>] (if an error occurs)
       handle: <opaque result handle, if mode = asynchronous>
    }

Example

Select query with synchronous result delivery

    use dataverse company;

    for $l in dataset('Employee') return $l;

API call for the above query statement in the URL-encoded form.

[http://localhost:19002/query?query=use%20dataverse%20company;for%20$l%20in%20dataset(‘Employee’)%20return%20$l;](http://localhost:19002/query?query=use%20dataverse%20company;for%20$l%20in%20dataset('Employee')%20return%20$l;)

Response

HTTP OK 200
Payload

    {
      "results": [
          [
              "{ "id": 123, "name": "John Doe" }"
          ]
      ]
    }

Same select query with asynchronous result delivery

API call for the above query statement in the URL-encoded form with mode=asynchronous

[http://localhost:19002/query?query=use%20dataverse%20company;for%20$l%20in%20dataset(‘Employee’)%20return%20$l;&mode=asynchronous](http://localhost:19002/query?query=use%20dataverse%20company;for%20$l%20in%20dataset('Employee')%20return%20$l;&mode=asynchronous)

Response

HTTP OK 200
Payload

    {
        "handle": [45,0]
    }

Mixed API [Back to TOC]

End point for any/mixed statement

Endpoint: /aql

Parameters:

Parameter Description Required?
query Query string to pass to ASTERIX for execution Yes
mode Indicate if call should be synchronous or asynchronous. mode = synchronous blocks the call until results are available; mode = asynchronous returns immediately with a handle that can be used later to check the query’s status and to fetch results when available No. default mode = synchronous

Similar to /update but allows any arbitrary AQL statement rather than only modifications.

Asynchronous Result API [Back to TOC]

End point to fetch the results of an asynchronous query

Endpoint: /query/result

Parameters:

Parameter Description Required?
handle Result handle that was returned by a previous call to a /query call with mode = asynchronous Yes

Result: The result is returned as a JSON object as follows:

    {
       results: <result as a string, if mode = synchronous, or mode = asynchronous and results are available>
       error-code: [<code>, <message>] (if an error occurs)
    }

If mode = asynchronous and results are not available, the returned JSON object is empty: { }

Example

Fetching results for asynchronous query

We use the handle returned by the asynchronous query to get the results for the query. The handle returned was:

    {
        "handle": [45,0]
    }

API call for reading results from the previous asynchronous query in the URL-encoded form.

http://localhost:19002/query/result?handle=%7B%22handle%22%3A+%5B45%2C+0%5D%7D

Response

HTTP OK 200
Payload

    {
      "results": [
          [
              "{ "id": 123, "name": "John Doe" }"
          ]
      ]
    }

Query Status API [Back to TOC]

End point to check the status of the query asynchronous

Endpoint: /query/status

Parameters:

Parameter Description Required?
handle Result handle that was returned by a previous call to a /query call with mode = asynchronous Yes

Result: The result is returned as a JSON object as follows:

    {
       status: ("RUNNING" | "SUCCESS" | "ERROR")
    }

Error Codes [Back to TOC]

Table of error codes and their types:

Code Type
1 Invalid statement
2 Parse failures
99 Uncategorized error