Query Result Customization

Several aspects of the query resultset can be customized by the API client.

Resultset format

The resultset format can be specified by setting the Accept header or acceptContentType query parameter. Supported formats are:

Content type Format
application/json JSON
application/x-ndjson newline delimited JSON (http://ndjson.org/)
application/json-seq JSON text sequence (https://tools.ietf.org/html/rfc7464)
application/csv CSV
application/ccsv CSV, comma separated
application/tsv TSV

The default resultset format is JSON.

Example: use CSV resultset format.

Note

You must replace the value of the token in Authorization header with the one in User Properties and host/port if you have changed the wgui.host or wgui.port configuration parameters)

curl -XPOST -G \
    -H "Accept: application/csv" \
    -H "Authorization: Bearer 4d055ad820051448" \
    -d "scriptPath=%2Fuser%2Fexamples%2Faggr_functions.sx" \
    http://localhost:8388/API/v1.0/

Range Requests

The range of rows returned in a resultset for script execution, table fetching, async query result fetching can be specified by using Range requests.

The unit used is items.

Example

Note

You must replace the value of the token in Authorization header with the one in User Properties and host/port if you have changed the wgui.host or wgui.port configuration parameters)

curl http://127.0.0.1:8388/API/v1.0/queries/8df64214-41b1-4ec0-b8a0-deda1d29355c/result \
    -H "Authorization: Bearer 4d055ad820051448" \
    -H "Range: items=1-3, 49-"

HTTP Request:

GET /API/v1.0/queries/8df64214-41b1-4ec0-b8a0-deda1d29355c/result HTTP/1.1
Host: 127.0.0.1:8388
Authorization: Bearer 4d055ad820051448
Range: items=1-3, 49-

HTTP Response:

HTTP/1.1 206 Partial Content
Accept-Ranges: items
Content-Type: multipart/mixed; boundary=0000016d-4ea0-6190-f610-94c4e05fcceb
Content-Length: 506

--0000016d-4ea0-6190-f610-94c4e05fcceb
Content-Range: items 1-3/50
Content-Type: application/json

[
  {"i":1,"ip":"0.0.0.1","t":"2019-09-20 15:21:46.288 +0300"},
  {"i":2,"ip":"0.0.0.2","t":"2019-09-20 15:21:46.289 +0300"},
  {"i":3,"ip":"0.0.0.3","t":"2019-09-20 15:21:46.290 +0300"}
]
--0000016d-4ea0-6190-f610-94c4e05fcceb
Content-Range: items 49-49/50
Content-Type: application/json

[
  {"i":49,"ip":"0.0.0.49","t":"2019-09-20 15:21:46.336 +0300"}
]
--0000016d-4ea0-6190-f610-94c4e05fcceb--

Note that when using Inline Resultset Schema, the schema row is prepended to each of the returned ranges separately.

Inline Resultset Schema

The schema of a resultset can be fetched inline inside the resultset, passing true for the opt.includeHeader request parameter. This is useful for stored script execution and arbitrary script execution, where making a separate request to get the schema would cause the query to execute twice.

This functionality prepends a header row to the resultset. For CSV, TSC, CCSV formats, the row contains field names. For JSON-based formats, the row contains field names as keys and field types as values.

Example.

Note

You must replace the value of the token in Authorization header with the one in User Properties and host/port if you have changed the wgui.host or wgui.port configuration parameters)

curl -v 'http://localhost:8388/API/v1.0/?scriptPath=/system/&opt.includeHeader=true' \
    -H "Authorization: Bearer 4d055ad820051448" \
    -d "dual(1).select(ix, ip, t);"

HTTP Request:

POST /API/v1.0/?scriptPath=/system/&opt.includeHeader=true HTTP/1.1
Host: localhost:8388
Authorization: Bearer 4d055ad820051448
Content-Length: 26
Content-Type: application/x-www-form-urlencoded

dual(1).select(ix, ip, t);

HTTP Response:

HTTP/1.1 200 OK
Accept-Ranges: items
Content-Type: application/json
Content-Length: 116

[
  {"ix":"INTEGER","ip":"?IPADDR","t":"TIMESTAMP"},
  {"ix":0,"ip":"0.0.0.0","t":"2019-09-20 15:33:46.227 +0300"}
]

Example

curl -v 'http://localhost:8388/API/v1.0/?scriptPath=/system/&opt.includeHeader=true' \
    -H "Authorization: Bearer 4d055ad820051448" \
    -H "Accept: application/csv" \
    -d "dual(1).select(ix, ip, t);"

HTTP Request:

POST /API/v1.0/?scriptPath=/system/&opt.includeHeader=true HTTP/1.1
Host: localhost:8388
Authorization: Bearer 4d055ad820051448
Accept: application/csv
Content-Length: 26
Content-Type: application/x-www-form-urlencoded

dual(1).select(ix, ip, t);

HTTP Response:

HTTP/1.1 200 OK
Accept-Ranges: items
Content-Type: application/csv; charset=UTF-8
Content-Length: 44

"ix";"ip";"t"
0;0.0.0.0;2019-09-20 15:36:16

Setting Timezone

The timezone of TIMESTAMP type fields in query results can be set using opt.timezone query parameter - string specifying timezone name (as defined in IANA Time Zone Database). Default is timezone specified in User Properties.

Example

Note

You must replace the value of the token in Authorization header with the one in User Properties and host/port if you have changed the wgui.host or wgui.port configuration parameters)

curl -XPOST -G \
    -H "Accept: application/csv" \
    -H "Authorization: Bearer 4d055ad820051448" \
    -d "scriptPath=%2Fuser%2Fexamples%2Faggr_functions.sx" \
    -d "opt.timezone=America%2FLos_Angeles" \
    http://localhost:8388/API/v1.0/

TIMESTAMP format

The TIMESTAMP type field presentation can be customized using opt.timestampFormat query parameter. It specifies the format string using pattern letters from Java DateTimeFormatter Patterns for Formatting and Parsing

The default presentation format is resultset format specific:

Resultset format Presentation format string
CSV, TSV, CCSV yyyy-MM-dd HH:mm:ss
JSON* yyyy-MM-dd HH:mm:ss.SSS Z

Example

Note

You must replace the value of the token in Authorization header with the one in User Properties and host/port if you have changed the wgui.host or wgui.port configuration parameters)

curl -XPOST -G \
    -H "Accept: application/csv" \
    -H "Authorization: Bearer 4d055ad820051448" \
    -d "scriptPath=%2Fuser%2Fexamples%2Faggr_functions.sx" \
    -d "opt.timestampFormat=MMM/dd/yyyy%20HH:mm:ss%20VV" \
    http://localhost:8388/API/v1.0/