From c6f2010d674737992e753622534e37dc617278d8 Mon Sep 17 00:00:00 2001 From: Zellweger Christof Ralf Date: Tue, 22 Dec 2015 08:22:32 +0100 Subject: [PATCH] sf_daq/ch.psi.daq.queryrest#1: - updating docs, rearranging a little --- Readme.md | 195 +++++++++++++++++++++++++----------------------------- 1 file changed, 90 insertions(+), 105 deletions(-) diff --git a/Readme.md b/Readme.md index b3ad2c4..a618ff6 100644 --- a/Readme.md +++ b/Readme.md @@ -138,44 +138,12 @@ By default, no data is compressed when transferred from the server to the client If compression is enabled, we have to tell `curl` that the data is compressed so that it is being decompressed automatically. `curl` decompresses the response when the `--compressed` parameter is set: -#### Example - -```bash -curl --compressed -H "Content-Type: application/json" -X POST -d '{"compression":"gzip","range":{"startPulseId":0,"endPulseId":3},"channels":["Channel_01"]}' http://data-api.psi.ch/sf/query -``` - - ### `responseFormat`: data is in JSON by default Responses can be formatted as CSV or JSON using the `responseFormat` field. The returned data is JSON-formatted per default. CSV export does not support `index` and `extrema` aggregations. -#### Example - -```bash -curl -H "Content-Type: application/json" -X POST -d '{"responseFormat":"csv","range":{"startPulseId":0,"endPulseId":4},"channels":["channel1","channel2"],"fields":["channel","pulseId","iocMillis","iocNanos","globalMillis","globalNanos","shape","eventCount","value"]}' http://data-api.psi.ch/sf/query -``` - -#### Response example - -The response is in CSV. - -```text -channel;pulseId;iocMillis;iocNanos;globalMillis;globalNanos;shape;eventCount;value -testChannel1;0;0;0;0;0;[1];1;0 -testChannel1;1;10;0;10;0;[1];1;1 -testChannel1;2;20;0;20;0;[1];1;2 -testChannel1;3;30;0;30;0;[1];1;3 -testChannel1;4;40;0;40;0;[1];1;4 -testChannel2;0;0;0;0;0;[1];1;0 -testChannel2;1;10;0;10;0;[1];1;1 -testChannel2;2;20;0;20;0;[1];1;2 -testChannel2;3;30;0;30;0;[1];1;3 -testChannel2;4;40;0;40;0;[1];1;4 -``` - - ### Query request endpoint @@ -202,79 +170,6 @@ The following attributes can be specified: - **compression**: Defines the compression algorithm to use, default value is **none**, see all values [here](https://git.psi.ch/sf_daq/ch.psi.daq.domain/blob/master/src/main/java/ch/psi/daq/domain/Compression.java)) - **responseFormat**: Specifies the format the response of the requested data is in, either in JSON or CSV format, default value **json**, see all values [here](https://git.psi.ch/sf_daq/ch.psi.daq.domain/blob/master/src/main/java/ch/psi/daq/domain/ResponseType.java)) -### Example - -Compressed data but uncompressed by `curl`: - -```bash -curl --compressed -H "Content-Type: application/json" -X POST -d '{"compression":"deflate","range":{"startPulseId":0,"endPulseId":4},"channels":["channel1","channel2"]}' http://data-api.psi.ch/sf/query -``` - -Raw, uncompressed data (returns non-human-readable data): - -```bash -curl -H "Content-Type: application/json" -X POST -d '{"range":{"startPulseId":0,"endPulseId":4},"channels":["channel1","channel2"]}' http://data-api.psi.ch/sf/query -``` - -### Response example - -The response is in JSON. - -```json -[ - { - "channel":"channel1", - "data":[ - { - "pulseId":0, - "iocMillis":0, - "iocNanos":0, - "globalMillis":0, - "globalNanos":0, - "value":0 - }, - { - "pulseId":2, - "iocMillis":2, - "iocNanos":2, - "globalMillis":2, - "globalNanos":2, - "value":2 - }, - { - "pulseId":4, - "iocMillis":4, - "iocNanos":4, - "globalMillis":4, - "globalNanos":4, - "value":4 - } - ] - }, - { - "channel":"channel2", - "data":[ - { - "pulseId":1, - "iocMillis":1, - "iocNanos":1, - "globalMillis":1, - "globalNanos":1, - "value":1 - }, - { - "pulseId":3, - "iocMillis":3, - "iocNanos":3, - "globalMillis":3, - "globalNanos":3, - "value":3 - } - ] - } -] -``` - ### Example Queries The following examples build on waveform data (see below). They also work for scalars (consider it as a waveform of length = 1) and images (waveform of length = dimX * dimY). @@ -337,6 +232,96 @@ The following examples build on waveform data (see below). They also work for sc ### Query Examples +##### Query using compression + +```json +{ + "compression":"gzip", + "range":{ + "startPulseId":0, + "endPulseId":3 + }, + "channels":[ + "Channel_01" + ] +} +``` + +or `deflate` can be used too: + +```json +{ + "compression":"deflate", + "range":{ + "startPulseId":0, + "endPulseId":3 + }, + "channels":[ + "Channel_01" + ] +} +``` + +###### Command (gzip) + +The `curl` command has a `--compressed` option to decompress data automatically. + +```bash +curl --compressed -H "Content-Type: application/json" -X POST -d '{"compression":"gzip","range":{"startPulseId":0,"endPulseId":3},"channels":["Channel_01"]}' http://data-api.psi.ch/sf/query +``` + +##### Query setting CSV response format + +```json +{ + "responseFormat":"csv", + "range":{ + "startPulseId":0, + "endPulseId":4 + }, + "channels":[ + "channel1", + "channel2" + ], + "fields":[ + "channel", + "pulseId", + "iocMillis", + "iocNanos", + "globalMillis", + "globalNanos", + "shape", + "eventCount", + "value" + ] +} +``` + +###### Command + +```bash +curl -H "Content-Type: application/json" -X POST -d '{"responseFormat":"csv","range":{"startPulseId":0,"endPulseId":4},"channels":["channel1","channel2"],"fields":["channel","pulseId","iocMillis","iocNanos","globalMillis","globalNanos","shape","eventCount","value"]}' http://data-api.psi.ch/sf/query +``` + +###### Response + +The response is in CSV. + +```text +channel;pulseId;iocMillis;iocNanos;globalMillis;globalNanos;shape;eventCount;value +testChannel1;0;0;0;0;0;[1];1;0 +testChannel1;1;10;0;10;0;[1];1;1 +testChannel1;2;20;0;20;0;[1];1;2 +testChannel1;3;30;0;30;0;[1];1;3 +testChannel1;4;40;0;40;0;[1];1;4 +testChannel2;0;0;0;0;0;[1];1;0 +testChannel2;1;10;0;10;0;[1];1;1 +testChannel2;2;20;0;20;0;[1];1;2 +testChannel2;3;30;0;30;0;[1];1;3 +testChannel2;4;40;0;40;0;[1];1;4 +``` + + ##### Query by Pulse-Id Range ```json