Skip to content

API

The following pre-configured APIs are available via q ipc or REST. For each API, the DAPs must implement the functions specified in the description of the API. If using the SG with the KX Insights Data Access microservice, these APIs are already implement and no further work is required to use them.

Below, we provide the following for each API:

  • A description of the API.
  • The parameters and response types
  • The corresponding function to be implemented on the DAP.
  • REST endpoint.
  • Examples (q-ipc and REST).

Note

All API names are prefix with .kxi even when not explicitly mentioned. All response come with a response header (see "header" and "interface" pages for details). Here, we document only the "payload" of the response.

For the purposes of examples, throughout this page we assume that the SG assembly is as follows.

name: mySG
labels:
  region: amer,emea,apac
elements:
  rc:
    host: rcHost
    port: 1234

And we also assume the DAPs that the SG fronts contain a table called trace, with the following schema:

Name Type Description
sensorID int Sensor identifier
readTS timestamp Timestamp of reading, and the column which determines HDB partition
valFloat float Reading measurment
qual short Quality of the reading
updateTS timestamp Update timestamp of reading

Finally, we assume that the REST server is address is stored in an environment variable URL (e.g. URL=localhost:5030) when making REST calls, and that we have an open handle h to a GW process when making q ipc requests.

Note that while not necessarily explicitly listed, all API calls must include startTS, endTS and all assembly labels in the parameters in order for the SG to route to the correct DAPs. In our examples here, with the assembly specified above, we therefore need to include region in all API calls. We may choose to target a single region, or multiple. Example:

params:`startTS`endTS`region!(-0Wp;0Wp;`amer) / Single region
params:`startTS`endTS`region!(-0Wp;0Wp;`amer`emea) / Multiple regions

getData

The getData API is a generic data retrieval API that can be executed against an arbitrary database table. It is intended to run on DAPs and retrieve records from a database table using specified parameters and aggregate the results.

Arguments

Name Type Description
table symbol Name of table to retrieve data from
startTS timestamp Inclusive start time of period of interest
endTS timestamp Inclusive end time of period of interest
filter string q-sql where clause defining filter
columns symbol[] Columns to return in response
opts dictionary Dictionary of additional options

Opts dictionary:

Name Type Description
tsCol symbol Timestamp column to apply startTS/endTS to. Default is the partition column of table
sortCols symbol[] Columns to sort response payload on

Response

The response is a table.

DAP implementation

The DAP must implement .kxi.getData. The response is a 3-element list containing * symbol[] - Columns to sort on or (::) for none. * symbol[] - Columns to select. * table - The table data, which contain at minimum the union of columns in the first two elements.

REST endpoint

http://${URL}/data

Examples

In this example we do a basic get call with only the table and time range specified.

q)args
table  | `trace
startTS| -0Wp
endTS  | 0Wp
region | amer

/ Sync.
q)res:h(`.kxi.getData;args;`;(0#`)!()) / Make API call and store the result in "res"
q)5#last res / Display only the first 5 records
sensorID readTS                        valFloat qual updateTS
----------------------------------------------------------------------------------
0        2021.02.09D00:00:00.000000000 283.0992 1    2021.02.10D19:02:25.332557500
0        2021.02.09D01:00:00.000000000 906.6764 5    2021.02.10D19:02:25.332557500
0        2021.02.09D02:00:00.000000000 546.6978 4    2021.02.10D19:02:25.332557500
0        2021.02.09D03:00:00.000000000 164.0931 4    2021.02.10D19:02:25.332557500
0        2021.02.09D04:00:00.000000000 663.1649 4    2021.02.10D19:02:25.332557500

/ Async.
q)f:{res::y} / Store only the payload in "res"
q)neg[h](`.kxi.getData;args;`f;(0#`)!()) / Make API call and invoke callback
q)5#res / Display only the first 5 records
sensorID readTS                        valFloat qual updateTS
----------------------------------------------------------------------------------
0        2021.02.09D00:00:00.000000000 283.0992 1    2021.02.10D19:02:25.332557500
0        2021.02.09D01:00:00.000000000 906.6764 5    2021.02.10D19:02:25.332557500
0        2021.02.09D02:00:00.000000000 546.6978 4    2021.02.10D19:02:25.332557500
0        2021.02.09D03:00:00.000000000 164.0931 4    2021.02.10D19:02:25.332557500
0        2021.02.09D04:00:00.000000000 663.1649 4    2021.02.10D19:02:25.332557500
curl -X POST\
    --header "Content-Type: application/json"\
    --data '{"table":"trace", "startTS":"2000.01.01D", "endTS":"2099.01.01D", "region": "amer"}'
    "http://${URL}/data"

In this example we refine the time range by specifying a startTS.

q)args
table  | `trace
startTS| 2021.02.09D01:00:00.000000000
endTS  | 0Wp
region | `emea

/ Sync.
q)res:h(`.kxi.getData;args;`;(0#`)!()) / Make the API call and store the result in "res"
q)5#last res / Display only the first 5 records
sensorID readTS                        valFloat qual updateTS
----------------------------------------------------------------------------------
0        2021.02.09D01:00:00.000000000 906.6764 5    2021.02.10D19:02:25.332557500
0        2021.02.09D02:00:00.000000000 546.6978 4    2021.02.10D19:02:25.332557500
0        2021.02.09D03:00:00.000000000 164.0931 4    2021.02.10D19:02:25.332557500
0        2021.02.09D04:00:00.000000000 663.1649 4    2021.02.10D19:02:25.332557500
0        2021.02.09D05:00:00.000000000 537.0982 4    2021.02.10D19:02:25.332557500

/ Async.
q)f:{res::y} / Store only payload in res
q)neg[h](`.kxi.getData;args;`f;(0#`)!()) / Make the API call and invoke callback
q)5#last res / Display only the first 5 records
sensorID readTS                        valFloat qual updateTS
----------------------------------------------------------------------------------
0        2021.02.09D01:00:00.000000000 906.6764 5    2021.02.10D19:02:25.332557500
0        2021.02.09D02:00:00.000000000 546.6978 4    2021.02.10D19:02:25.332557500
0        2021.02.09D03:00:00.000000000 164.0931 4    2021.02.10D19:02:25.332557500
0        2021.02.09D04:00:00.000000000 663.1649 4    2021.02.10D19:02:25.332557500
0        2021.02.09D05:00:00.000000000 537.0982 4    2021.02.10D19:02:25.332557500
curl -X POST\
    --header "Content-Type: application/json"\
    --data '{"table":"trace", "startTS":"2021.02.09D01", "endTS":"2099.01.01D", "region": "emea"}'
    "http://${URL}/data"

Here we specify select only a subset of the columns and multiple regions.

q)args
table  | `trace
startTS| -0Wp
endTS  | 0Wp
region | `amer`emea
columns| `sensorID`readTS`valFloat

/ Sync.
q)res:h(`.kxi.data;args;`;(0#`)!()) / Make the API call and store the result in "res"
q)5#last res / Display only the first 5 records
sensorID readTS                        valFloat
-----------------------------------------------
0        2021.05.12D00:00:00.000000000 278.1034
0        2021.05.12D01:00:00.000000000 256.3526
0        2021.05.12D02:00:00.000000000 73.38756
0        2021.05.12D03:00:00.000000000 911.9714
0        2021.05.12D04:00:00.000000000 171.8527

/ Async.
q)f:{res::y} / Store only the payload in "res"
q)res:neg[h](`.kxi.data;args;`f;(0#`)!()) / Make the API call and invoke callback
q)5#res / Display only the first 5 records
sensorID readTS                        valFloat
-----------------------------------------------
0        2021.05.12D00:00:00.000000000 278.1034
0        2021.05.12D01:00:00.000000000 256.3526
0        2021.05.12D02:00:00.000000000 73.38756
0        2021.05.12D03:00:00.000000000 911.9714
0        2021.05.12D04:00:00.000000000 171.8527
curl -X POST\
    --header "Content-Type: application/json"\
    --data '{"table":"trace", "startTS":"2000.01.01D", "endTS":"2099.01.01D", "region": ["amer", "emea"], "columns": ["sensorID", "readTS", "valFloat"]}'
    "http://${URL}/data"

Example using the filter argument. Here we ask for sensorIDs equal to 10i, as well as filtering for qual values between 1 and 3h.

q)args
table  | `trace
startTS| -0Wp
endTS  | 0Wp
region | apac
filter | "sensorID=10i,qual within 1 3h"

/ Sync.
q)res:h(`.kxi.getData;args;`;(0#`)!()) / Make the API call and store the result in "res"
q)5#last res / Display only the first 5 records
sensorID readTS                        valFloat qual updateTS
----------------------------------------------------------------------------------
10       2021.05.12D03:00:00.000000000 781.8174 3    2021.05.13D14:01:56.802276100
10       2021.05.12D04:00:00.000000000 951.9392 2    2021.05.13D14:01:56.802276100
10       2021.05.12D07:00:00.000000000 971.0995 3    2021.05.13D14:01:56.802276100
10       2021.05.12D13:00:00.000000000 103.5567 2    2021.05.13D14:01:56.802276100
10       2021.05.12D14:00:00.000000000 297.4721 1    2021.05.13D14:01:56.802276100

/ Async.
q)f:{res::y} / Store only the payload in "res"
q)res:h(`.kxi.getData;args;`f;(0#`)!()) / Make the API call and store the result in "res"
q)5#last res / Display only the first 5 records
sensorID readTS                        valFloat qual updateTS
----------------------------------------------------------------------------------
10       2021.05.12D03:00:00.000000000 781.8174 3    2021.05.13D14:01:56.802276100
10       2021.05.12D04:00:00.000000000 951.9392 2    2021.05.13D14:01:56.802276100
10       2021.05.12D07:00:00.000000000 971.0995 3    2021.05.13D14:01:56.802276100
10       2021.05.12D13:00:00.000000000 103.5567 2    2021.05.13D14:01:56.802276100
10       2021.05.12D14:00:00.000000000 297.4721 1    2021.05.13D14:01:56.802276100
curl -X POST\
    --header "Content-Type: application/json"\
    --data '{"table":"trace", "startTS":"2000.01.01D", "endTS":"2099.01.01D", "region": "apac", "filter": "sensorID=10i,qual within 1 3h"}'
    "http://${URL}/data"

In this example we use the options dictionary to specify that the timestamp filter should apply to the updateTS column instead.

q)args
table  | `trace
startTS| 2021.05.13D14:05:00.000000000
region | amer
endTS  | 0Wp
opts   | (,`tsCol)!,`updateTS

/ Sync
q)res:h(`.kxi.getData;args;`;(0#`)!()) / Make the API call and store the result in "res"
q)5#last res / Display only the first 5 records
sensorID readTS                        valFloat qual updateTS
----------------------------------------------------------------------------------
0        2021.05.12D00:00:00.000000000 458.3568 5    2021.05.13D14:05:06.802253100
0        2021.05.12D01:00:00.000000000 919.25   3    2021.05.13D14:05:06.802253100
0        2021.05.12D02:00:00.000000000 465.7557 1    2021.05.13D14:05:06.802253100
0        2021.05.12D03:00:00.000000000 609.1758 2    2021.05.13D14:05:06.802253100
0        2021.05.12D04:00:00.000000000 349.6804 1    2021.05.13D14:05:06.802253100

/ Async.
q)f:{res::y} / Store only the payload in "res"
q)neg[h](`.kxi.getData;args;`f;(0#`)!()) / Make the API call and invoke callback
q)5#res / Display only the first 5 records
sensorID readTS                        valFloat qual updateTS
----------------------------------------------------------------------------------
0        2021.05.12D00:00:00.000000000 458.3568 5    2021.05.13D14:05:06.802253100
0        2021.05.12D01:00:00.000000000 919.25   3    2021.05.13D14:05:06.802253100
0        2021.05.12D02:00:00.000000000 465.7557 1    2021.05.13D14:05:06.802253100
0        2021.05.12D03:00:00.000000000 609.1758 2    2021.05.13D14:05:06.802253100
0        2021.05.12D04:00:00.000000000 349.6804 1    2021.05.13D14:05:06.802253100
curl -X POST\
    --header "Content-Type: application/json"\
    --data '{"table":"trace", "startTS":"2021.05.13D14:05", "endTS":"2099.01.01D", "region": "amer", "opts": {"tsCol": "updateTS"}}'
    "http://${URL}/data"

Again we make use of the options dictionary, but this time to return the result sorted by qual and valFloat.

q)args
table  | `trace
startTS| 2021.05.13D14:05:00.000000000
endTS  | 0Wp
region | `amer
opts   | (,`sortCols)!,`qual`valFloat

/ Sync.
q)res:h(`.kxi.getData;args;`;(0#`)!()) / Make the API call and store the result in "res"
q)5#last res / Display only the first 5 records
sensorID readTS                        valFloat   qual updateTS
------------------------------------------------------------------------------------
99       2021.05.12D08:00:00.000000000 0.00825664 0    2021.05.13D14:11:56.802232800
39       2021.05.12D12:00:00.000000000 0.09356276 0    2021.05.13D14:12:36.802253700
70       2021.05.12D02:00:00.000000000 0.1157809  0    2021.05.13D14:17:56.802235900
1        2021.05.12D01:00:00.000000000 0.197002   0    2021.05.13D14:17:46.804990700
33       2021.05.12D12:00:00.000000000 0.2034092  0    2021.05.13D14:13:16.803428200

/ Async.
q)f:{res::y} / Store only the payload in "res"
q)neg[h](`.kxi.getData;args;`f;(0#`)!()) / Make the API call and invoke callback
q)5#res / Display only the first 5 records
sensorID readTS                        valFloat   qual updateTS
------------------------------------------------------------------------------------
99       2021.05.12D08:00:00.000000000 0.00825664 0    2021.05.13D14:11:56.802232800
39       2021.05.12D12:00:00.000000000 0.09356276 0    2021.05.13D14:12:36.802253700
70       2021.05.12D02:00:00.000000000 0.1157809  0    2021.05.13D14:17:56.802235900
1        2021.05.12D01:00:00.000000000 0.197002   0    2021.05.13D14:17:46.804990700
33       2021.05.12D12:00:00.000000000 0.2034092  0    2021.05.13D14:13:16.803428200
curl -X POST\
    --header "Content-Type: application/json"\
    --data '{"table":"trace", "startTS":"2021.05.13D14:05", "endTS":"2099.01.01D", "region": "amer", "opts": {"sortCols": ["qual", "valFloat"]}}'
    "http://${URL}/data"

qsql

This API is intended to run on a data access process and execute the command sent in from the client.

Arguments

Name Type Description
query string The q-sql command to run on a target data access process

Response

The response is dependant on the query parameter itself, but would typically be a table.

DAP implementation

The DAP must implement .kxi.qsql. The function should return the execution of query string.

REST endpoint

http://${URL}/ping

Examples

In this example we do a simple select from the trace table for the sensorID of 4.

q)args
startTS| -0Wp
endTS  | 0Wp
region | `amer
query  | "select from trace where sensorID=4"

/ Sync
q)res:h(`.kxi.qsql;args;`;(0#`)!()) / Make the API call and
q)5#last res / Display only the first 5 records
sensorID readTS                        valFloat qual updateTS
----------------------------------------------------------------------------------
4        2021.02.09D00:00:00.000000000 283.0992 1    2021.02.10D19:02:25.332557500
4        2021.02.09D01:00:00.000000000 906.6764 5    2021.02.10D19:02:25.332557500
4        2021.02.09D02:00:00.000000000 546.6978 4    2021.02.10D19:02:25.332557500
4        2021.02.09D03:00:00.000000000 164.0931 4    2021.02.10D19:02:25.332557500
4        2021.02.09D04:00:00.000000000 663.1649 4    2021.02.10D19:02:25.332557500

/ Async.
q)f:{res::y} / Store only the payload in "res"
q)neg[h](`.kxi.qsql;args;`f;(0#`)!()) / Make the API call and invoke callback
q)5#res / Display only the first 5 records
sensorID readTS                        valFloat qual updateTS
----------------------------------------------------------------------------------
4        2021.02.09D00:00:00.000000000 283.0992 1    2021.02.10D19:02:25.332557500
4        2021.02.09D01:00:00.000000000 906.6764 5    2021.02.10D19:02:25.332557500
4        2021.02.09D02:00:00.000000000 546.6978 4    2021.02.10D19:02:25.332557500
4        2021.02.09D03:00:00.000000000 164.0931 4    2021.02.10D19:02:25.332557500
4        2021.02.09D04:00:00.000000000 663.1649 4    2021.02.10D19:02:25.332557500
curl -X POST\
    --header "Content-Type: application/json"\
    --data '{"startTS":"2000.01.01D", "endTS":"2099.01.01D", "region": "amer", "query": "select from trace where sensorID=4"}'
    "http://${URL}/ping"

ping

This API is intended to run on a data access process and returns true if it reaches a target. This is intended to be used as a diagnostic tool do determine system health.

Arguments

This API requires no arguments (aside from the purview arguments to determine routing).

Response

The response is a boolean[]. The values should all be true, and there is one element for each DAP hit.

DAP implementation

The DAP must implement .kxi.ping. The function should return 1b.

REST endpoint

http://${URL}/ping

Examples

In a system with an RDB/IDB/HDB, a call to one region for all time should hit all three.

q)args
startTS| -0Wp
endTS  | 0Wp
region | `amer

/ Sync
q)res:h(`.kxi.ping;args;`;(0#`)!()) / Make the API call and store the result in "res"
q)5#res

/ Async.
q)f:{res::y} / Store only the payload in "res"
q)neg[h](`.kxi.getData;args;`f;(0#`)!()) / Make the API call and invoke callback
q)res
111b
curl -X POST\
    --header "Content-Type: application/json"\
    --data '{"startTS":"2000.01.01D", "endTS":"2099.01.01D", "region": "amer"}'
    "http://${URL}/ping"