HTTP API to AsterixDB

Table of Contents

DDL API [Back to TOC]

End point for the data definition statements

Endpoint: /ddl

Parameters:

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;

Response

HTTP OK 200
<NO PAYLOAD>

Update API [Back to TOC]

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

Endpoint: /update

Parameters:

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});

Response

HTTP OK 200
<NO PAYLOAD>

Query API [Back to TOC]

End point for query statements

Endpoint: /query

Parameters:

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;

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

Response

HTTP OK 200
Payload

    {
        "handle": [45,0]
    }

Mixed API [Back to TOC]

End point for any/mixed statement

Endpoint: /aql

Parameters:

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:

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:

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: