Query via http

Query via http

There are three different ways of executing SQL statement via HTTP. Those api support not only “SELECT” but also “CREATE TABLE”, “ALTER TABLE”, “INSERT”… all other SQL statements.


Request Params

qn/aSQL query string
formatjsonResult data format: json, csv, box
timeformatnsTime format: s, ms, us, ns
tzUTCTime Zone: UTC, Local and location spec
compressno compressioncompression method: gzip
rownumfalseincluding rownum: true, false
headingtrueshowing heading: true, false
precision-1precision of float value, -1 for no round, 0 for int

Use machbase-neo help tz and machbase-neo help timeformat to see more available options for timezone and timeformat options

machbase-neo» help timeformat;
      ns             nanoseconds
      us             microseconds
      ms             milliseconds
      s              seconds
      Default,-      2006-01-02 15:04:05.999
      Numeric        01/02 03:04:05PM '06 -0700
      Ansic          Mon Jan _2 15:04:05 2006
      Unix           Mon Jan _2 15:04:05 MST 2006
      Ruby           Mon Jan 02 15:04:05 -0700 2006
      RFC822         02 Jan 06 15:04 MST
      RFC822Z        02 Jan 06 15:04 -0700
      RFC850         Monday, 02-Jan-06 15:04:05 MST
      RFC1123        Mon, 02 Jan 2006 15:04:05 MST
      RFC1123Z       Mon, 02 Jan 2006 15:04:05 -0700
      RFC3339        2006-01-02T15:04:05Z07:00
      RFC3339Nano    2006-01-02T15:04:05.999999999Z07:00
      Kitchen        3:04:05PM
      Stamp          Jan _2 15:04:05
      StampMili      Jan _2 15:04:05.000
      StampMicro     Jan _2 15:04:05.000000
      StampNano      Jan _2 15:04:05.000000000
    custom format
      year           2006
      month          01
      day            02
      hour           03 or 15
      minute         04
      second         05 or with sub-seconds '05.999999999'

List of Time Zones

machbase-neo» help tz;
    location examples
    Time Coordinates examples

Response in JSON format (default)

Set query param format=json or omit it for the default value.

curl -o - \
    --data-urlencode "q=select * from EXAMPLE limit 2"

The server responses in Content-Type: application/json.

successbooltrue if query execution successed
reasonstringexecution result message, this will contains error message if success is false
elapsestringelapse time of the query execution
dataexists only when execution successed
data.columnsarray of stringsrepresents columns of result
data.typesarray of stringsrepresents data types of result
data.rowsarray of tuplesa tuple represents a record
  "success": true,
  "reason": "success",
  "elapse": "281.288µs",
  "data": {
    "columns": [ "NAME", "TIME", "VALUE" ],
    "types": [ "string", "datetime", "double" ],
    "rows": [
      [ "wave.sin", 1676337568, 0 ],
      [ "wave.sin", 1676337569, 0.406736 ]

Response in BOX format

Set query param format=box in the request.

curl -o - \
    --data-urlencode "q=select * from EXAMPLE limit 2" --data-urlencode "format=box"

The result data in plain text with ascii box. The Content-Type of the response is plain/text

| NAME     | TIME(UTC)           | VALUE    |
| wave.sin | 1676337568          | 0.000000 |
| wave.sin | 1676337569          | 0.406736 |

Response in CSV format

Set query param format=csv in the request.

curl -o - \
    --data-urlencode "q=select * from EXAMPLE limit 2" --data-urlencode "format=csv"

The response comes with Content-Type: text/csv



It is also possible to request query in JSON form as below example.

Request JSON message

qstringSQL query string
curl -o - -X POST \
    -H 'Content-Type: application/json' \
    -d '{ "q":"select * from EXAMPLE" }'

Post Form Data

HTML Form data format is available too. HTTP header Content-type should be application/x-www-form-urlencoded in this case.

curl -o - -X POST \
    --data-urlencode "q=select * from TAGDATA"


The HTTP “Query” API doesn’t accept only “SELECT” SQL but also DDL. So it is possible to create and drop tables via HTTP API

Create table

curl -o - \
    --data-urlencode \
    "q=create tag table EXAMPLE (name varchar(40) primary key, time datetime basetime, value double)"
  • response


Drop table

curl -o - \
    --data-urlencode "q=drop table EXAMPLE"
  • response

Last updated on