diff --git a/Readme.md b/Readme.md index a618ff6..8238e71 100644 --- a/Readme.md +++ b/Readme.md @@ -132,19 +132,6 @@ Queries are applied to a range. The following types of ranges ranges are support ## Query Data -### `compression`: compression of data can be enabled - -By default, no data is compressed when transferred from the server to the client. However, compression can be enabled by setting the `compression` attribute to a value other than `none`, i.e. to `gzip` or `deflate`. - -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: - -### `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. - - ### Query request endpoint ``` @@ -167,8 +154,20 @@ The following attributes can be specified: - **aggregationType**: Specifies the type of aggregation (see [here](https://git.psi.ch/sf_daq/ch.psi.daq.query/blob/master/src/main/java/ch/psi/daq/query/model/AggregationType.java)). The default type is *value* aggregation (e.g., sum([1,2,3])=6). Alternatively, it is possible to define *index* aggregation for multiple arrays in combination with binning (e.g., sum([1,2,3], [3,2,1]) = [4,4,4]). - **aggregateChannels**: Specifies whether the data of the requested channels should be combined together using the defined aggregation (values: true|**false**) - **dbMode**: Defines the database to access (values: **databuffer**|archiverappliance) -- **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)) +- **compression**: Defines the compression algorithm to use, default value is **none**, see all values [here](https://github.psi.ch/sf_daq/ch.psi.daq.query/blob/master/src/main/java/ch/psi/daq/query/model/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://github.psi.ch/sf_daq/ch.psi.daq.query/blob/master/src/main/java/ch/psi/daq/query/model/ResponseFormat.java)) + +### `compression`: compression of data can be enabled + +By default, no data is compressed when transferred from the server to the client. However, compression can be enabled by setting the `compression` attribute to a value other than `none`, i.e. to `gzip` or `deflate`. + +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: + +### `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 Queries @@ -232,96 +231,6 @@ 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 @@ -436,7 +345,94 @@ curl -H "Content-Type: application/json" -X POST -d '{"dbmode":"archiverapplian See JSON representation of the data above. +##### 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 +``` ##### Querying for Specific Fields