ATEST-371
This commit is contained in:
Fabian Märki
181
Readme.md
181
Readme.md
@ -61,7 +61,14 @@ POST http://<host>:<port>/channels
|
||||
#### Data
|
||||
|
||||
```json
|
||||
{"regex": "TRFCA|TRFCB","backends": ["sf-databuffer"],"ordering":"asc","reload":true}
|
||||
{
|
||||
"regex":"TRFCA|TRFCB",
|
||||
"backends":[
|
||||
"sf-databuffer"
|
||||
],
|
||||
"ordering":"asc",
|
||||
"reload":true
|
||||
}
|
||||
```
|
||||
|
||||
##### Explanation
|
||||
@ -116,16 +123,46 @@ GET http://<host>:<port>/query
|
||||
|
||||
A request is performed by sending a valid JSON object in the HTTP request body. The JSON query defines the channels to be queried, the range, and how the data should be aggregated (this is optional but highly recommended).
|
||||
|
||||
The following attributes can be specified:
|
||||
#### Data
|
||||
|
||||
```json
|
||||
{
|
||||
"channels":[
|
||||
"Channel_01"
|
||||
],
|
||||
"range":{
|
||||
"startPulseId":0,
|
||||
"endPulseId":3
|
||||
},
|
||||
"ordering":"asc",
|
||||
"fields":[
|
||||
"pulseId",
|
||||
"globalDate",
|
||||
"value"
|
||||
],
|
||||
"aggregation":{
|
||||
"aggregationType":"value",
|
||||
"aggregations":[
|
||||
"min",
|
||||
"mean",
|
||||
"max"
|
||||
],
|
||||
"nrOfBins":2
|
||||
},
|
||||
"response":{
|
||||
"format":"json",
|
||||
"compression":"none"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
##### Explanation
|
||||
|
||||
- **channels**: Array of channels to be queried (see [here](Readme.md#query_channel_names) and [here](Readme.md#define_channel_names)).
|
||||
- **range**: The range of the query (see [here](Readme.md#query_range)).
|
||||
- **ordering**: The ordering of the data (see [here](https://github.psi.ch/sf_daq/ch.psi.daq.common/blob/master/src/main/java/ch/psi/daq/common/ordering/Ordering.java) for possible values).
|
||||
- **fields**: The requested fields (see [here](https://github.psi.ch/sf_daq/ch.psi.daq.domain/blob/master/src/main/java/ch/psi/daq/domain/query/operation/QueryField.java) for possible values).
|
||||
- **nrOfBins**: Activates data binning. Specifies the number of bins the pulse/time range should be divided into.
|
||||
- **binSize**: Activates data binning. Specifies the number of pulses per bin for pulse-range queries or the number of milliseconds per bin for time-range queries (using number of pulses and number of milliseconds makes this binning strategy consistent between channel with different update frequencies).
|
||||
- **aggregations**: Activates data aggregation. Array of requested aggregations (see [here](https://github.psi.ch/sf_daq/ch.psi.daq.domain/blob/master/src/main/java/ch/psi/daq/domain/query/operation/Aggregation.java) for possible values). These values will be added to the *data* array response.
|
||||
- **aggregationType**: Specifies the type of aggregation (see [here](https://github.psi.ch/sf_daq/ch.psi.daq.domain/blob/master/src/main/java/ch/psi/daq/domain/query/operation/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]).
|
||||
- **ordering**: The ordering of the data (see [here](Readme.md#data_ordering)).
|
||||
- **fields**: Array of requested fields (see [here](Readme.md#requested_fields)).
|
||||
- **aggregation**: Setting this attribute activates data aggregation (see [here](Readme.md#data_aggregation) for its specification).
|
||||
- **response**: Specifies the format of the response of the requested data (see [here](Readme.md#response_format)). If this value is not set it defaults to JSON.
|
||||
|
||||
<a name="define_channel_names"/>
|
||||
@ -203,6 +240,59 @@ Queries are applied to a range. The following types of ranges are supported.
|
||||
- **endSeconds**: The end time of the range in seconds.
|
||||
|
||||
|
||||
<a name="data_ordering"/>
|
||||
|
||||
### Data Ordering
|
||||
|
||||
```json
|
||||
"ordering":"asc"
|
||||
```
|
||||
|
||||
- **ordering**: Defines the ordering of the requested data (values: **asc**|desc|none). Use *none* in case ordering does not matter (allows for server side optimizations).
|
||||
|
||||
|
||||
<a name="requested_fields"/>
|
||||
|
||||
### Requested Fields
|
||||
|
||||
```json
|
||||
"fields":[
|
||||
"pulseId",
|
||||
"globalDate",
|
||||
"value"
|
||||
]
|
||||
```
|
||||
|
||||
- **fields**: Array of requested fields (see [here](https://github.psi.ch/sf_daq/ch.psi.daq.domain/blob/master/src/main/java/ch/psi/daq/domain/query/operation/QueryField.java) for possible values).
|
||||
|
||||
It is possible to request the time in seconds (since January 1, 1970 (the UNIX epoch) as a decimal value including fractional seconds - using fields *globalSeconds* and *iocSeconds*), in milliseconds (since January 1, 1970 (the JAVA epoch) - using fields *globalMillis* and *iocMillis*) or as a ISO8601 formatted String - using fields *globalDate* and *iocDate* (such as 1997-07-16T19:20:30.123456789+02:00).
|
||||
|
||||
|
||||
<a name="data_aggregation"/>
|
||||
|
||||
### Data Aggregation
|
||||
|
||||
It is possible (and recommended) to aggregate queried data.
|
||||
|
||||
```json
|
||||
"aggregation":{
|
||||
"aggregationType":"value",
|
||||
"aggregations":[
|
||||
"min",
|
||||
"mean",
|
||||
"max"
|
||||
],
|
||||
"nrOfBins":2
|
||||
}
|
||||
```
|
||||
|
||||
- **aggregationType**: Specifies the type of aggregation (see [here](https://github.psi.ch/sf_daq/ch.psi.daq.domain/blob/master/src/main/java/ch/psi/daq/domain/query/operation/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]).
|
||||
- **aggregations**: Array of requested aggregations (see [here](https://github.psi.ch/sf_daq/ch.psi.daq.domain/blob/master/src/main/java/ch/psi/daq/domain/query/operation/Aggregation.java) for possible values). These values will be added to the *data* array response.
|
||||
- **nrOfBins**: Activates data binning. Specifies the number of bins the pulse/time range should be divided into.
|
||||
- **msPerBin**: Activates data binning. Specifies the number of milliseconds per bin for time-range queries (using number of milliseconds makes this binning strategy consistent between channel with different update frequencies).
|
||||
- **pulsesPerBin**: Activates data binning. Specifies the number of pulses per bin for pulse-range queries (using number of pulses makes this binning strategy consistent between channel with different update frequencies).
|
||||
|
||||
|
||||
<a name="response_format"/>
|
||||
|
||||
### Response Format
|
||||
@ -393,22 +483,9 @@ See JSON representation of the data above.
|
||||
|
||||
```json
|
||||
{
|
||||
"compression":"gzip",
|
||||
"range":{
|
||||
"startPulseId":0,
|
||||
"endPulseId":3
|
||||
},
|
||||
"channels":[
|
||||
"Channel_01"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
or `deflate` can be used too:
|
||||
|
||||
```json
|
||||
{
|
||||
"compression":"deflate",
|
||||
"response":{
|
||||
"compression":"gzip"
|
||||
},
|
||||
"range":{
|
||||
"startPulseId":0,
|
||||
"endPulseId":3
|
||||
@ -424,7 +501,7 @@ or `deflate` can be used too:
|
||||
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 | python -m json.tool
|
||||
curl --compressed -H "Content-Type: application/json" -X POST -d '{"response":{"compression":"gzip"},"range":{"startPulseId":0,"endPulseId":3},"channels":["Channel_01"]}' http://data-api.psi.ch/sf/query | python -m json.tool
|
||||
```
|
||||
|
||||
#### Querying for Specific Fields
|
||||
@ -505,8 +582,6 @@ curl -H "Content-Type: application/json" -X POST -d '{"fields":["pulseId","valu
|
||||
}
|
||||
```
|
||||
|
||||
It is possible to request the time in seconds (since January 1, 1970 (the UNIX epoch) as a decimal value including fractional seconds - using fields *globalSeconds* and *iocSeconds*), in milliseconds (since January 1, 1970 (the JAVA epoch) - using fields *globalMillis* and *iocMillis*) or as a ISO8601 formatted String - using fields *globalDate* and *iocDate* (such as 1997-07-16T19:20:30.123456789+02:00).
|
||||
|
||||
##### Command
|
||||
|
||||
```bash
|
||||
@ -590,8 +665,10 @@ curl -H "Content-Type: application/json" -X POST -d '{"ordering":"desc","fields
|
||||
|
||||
```json
|
||||
{
|
||||
"aggregationType":"value",
|
||||
"aggregations":["min","max","mean"],
|
||||
"aggregation":{
|
||||
"aggregationType":"value",
|
||||
"aggregations":["min","mean","max"]
|
||||
},
|
||||
"fields":["pulseId","value"],
|
||||
"range":{
|
||||
"startPulseId":0,
|
||||
@ -606,7 +683,7 @@ curl -H "Content-Type: application/json" -X POST -d '{"ordering":"desc","fields
|
||||
##### Command
|
||||
|
||||
```bash
|
||||
curl -H "Content-Type: application/json" -X POST -d '{"aggregationType":"value","aggregations":["min","max","mean"],"fields":["pulseId","value"],"range":{"startPulseId":0,"endPulseId":3},"channels":["Channel_01"]}' http://data-api.psi.ch/sf/query | python -m json.tool
|
||||
curl -H "Content-Type: application/json" -X POST -d '{"aggregation":{"aggregationType":"value","aggregations":["min","mean","max"]},"fields":["pulseId","value"],"range":{"startPulseId":0,"endPulseId":3},"channels":["Channel_01"]}' http://data-api.psi.ch/sf/query | python -m json.tool
|
||||
```
|
||||
|
||||
##### Response
|
||||
@ -663,9 +740,11 @@ Illustration of array value aggregation:
|
||||
|
||||
```json
|
||||
{
|
||||
"nrOfBins":2,
|
||||
"aggregationType":"value",
|
||||
"aggregations":["min","max","mean"],
|
||||
"aggregation":{
|
||||
"nrOfBins":2,
|
||||
"aggregationType":"value",
|
||||
"aggregations":["min","mean","max"]
|
||||
},
|
||||
"fields":["pulseId","value"],
|
||||
"range":{
|
||||
"startPulseId":0,
|
||||
@ -680,7 +759,7 @@ Illustration of array value aggregation:
|
||||
##### Command
|
||||
|
||||
```bash
|
||||
curl -H "Content-Type: application/json" -X POST -d '{"nrOfBins":2,"aggregationType":"value","aggregations":["min","max","mean"],"fields":["pulseId","value"],"range":{"startPulseId":0,"endPulseId":3},"channels":["Channel_01"]}' http://data-api.psi.ch/sf/query | python -m json.tool
|
||||
curl -H "Content-Type: application/json" -X POST -d '{"aggregation":{"nrOfBins":2,"aggregationType":"value","aggregations":["min","mean","max"]},"fields":["pulseId","value"],"range":{"startPulseId":0,"endPulseId":3},"channels":["Channel_01"]}' http://data-api.psi.ch/sf/query | python -m json.tool
|
||||
```
|
||||
|
||||
##### Response
|
||||
@ -716,15 +795,19 @@ Illustration of array value aggregation with additional binning:
|
||||
|
||||
|
||||
|
||||
#### Value Aggregation with Binning (binSize)
|
||||
#### Value Aggregation with Binning (msPerBin/pulsesPerBin)
|
||||
|
||||
**binSize** specifies the number of pulses per bin for pulse-range queries or the number of milliseconds per bin for time-range queries (using number of pulses and number of milliseconds makes this binning strategy consistent between channel with different update frequencies).
|
||||
**msPerBin** specifies the number of milliseconds per bin for time-range queries (using number of milliseconds makes this binning strategy consistent between channel with different update frequencies).
|
||||
|
||||
**pulsesPerBin** specifies the number of pulses per bin for pulse-range queries (using number of pulses makes this binning strategy consistent between channel with different update frequencies).
|
||||
|
||||
```json
|
||||
{
|
||||
"binSize":10,
|
||||
"aggregationType":"value",
|
||||
"aggregations":["min","max","mean"],
|
||||
"aggregation":{
|
||||
"pulsesPerBin":2,
|
||||
"aggregationType":"value",
|
||||
"aggregations":["min","mean","max"]
|
||||
},
|
||||
"fields":["globalMillis","value"],
|
||||
"range":{
|
||||
"startSeconds":"0.0",
|
||||
@ -739,7 +822,7 @@ Illustration of array value aggregation with additional binning:
|
||||
##### Command
|
||||
|
||||
```bash
|
||||
curl -H "Content-Type: application/json" -X POST -d '{"binSize":10,"aggregationType":"value","aggregations":["min","max","mean"],"fields":["globalMillis","value"],"range":{"startSeconds":"0.0","endSeconds":"0.030000000"},"channels":["Channel_01"]}' http://data-api.psi.ch/sf/query | python -m json.tool
|
||||
curl -H "Content-Type: application/json" -X POST -d '{"aggregation":{"pulsesPerBin":2,"aggregationType":"value","aggregations":["min","mean","max"]},"fields":["globalMillis","value"],"range":{"startSeconds":"0.0","endSeconds":"0.030000000"},"channels":["Channel_01"]}' http://data-api.psi.ch/sf/query | python -m json.tool
|
||||
```
|
||||
|
||||
##### Response
|
||||
@ -779,9 +862,11 @@ Illustration of array value aggregation with additional binning:
|
||||
|
||||
```json
|
||||
{
|
||||
"nrOfBins":1,
|
||||
"aggregationType":"index",
|
||||
"aggregations":["min","max","mean","sum"],
|
||||
"aggregation":{
|
||||
"pulsesPerBin":1,
|
||||
"aggregationType":"index",
|
||||
"aggregations":["min","mean","max","sum"]
|
||||
},
|
||||
"fields":["pulseId","value"],
|
||||
"range":{
|
||||
"startPulseId":0,
|
||||
@ -796,7 +881,7 @@ Illustration of array value aggregation with additional binning:
|
||||
##### Command
|
||||
|
||||
```bash
|
||||
curl -H "Content-Type: application/json" -X POST -d '{"nrOfBins":1,"aggregationType":"index","aggregations":["min","max","mean","sum"],"fields":["pulseId","value"],"range":{"startPulseId":0,"endPulseId":3},"channels":["Channel_01"]}' http://data-api.psi.ch/sf/query | python -m json.tool
|
||||
curl -H "Content-Type: application/json" -X POST -d '{"aggregation":{"nrOfBins":1,"aggregationType":"index","aggregations":["min","max","mean","sum"]},"fields":["pulseId","value"],"range":{"startPulseId":0,"endPulseId":3},"channels":["Channel_01"]}' http://data-api.psi.ch/sf/query | python -m json.tool
|
||||
```
|
||||
|
||||
##### Response
|
||||
@ -849,8 +934,10 @@ Illustration of array index aggregation with additional with binning (several nr
|
||||
|
||||
```json
|
||||
{
|
||||
"aggregationType":"extrema",
|
||||
"aggregations":["min","max","sum"],
|
||||
"aggregation":{
|
||||
"aggregationType":"extrema",
|
||||
"aggregations":["min","max","sum"]
|
||||
},
|
||||
"fields":["pulseId","value"],
|
||||
"range":{
|
||||
"startPulseId":0,
|
||||
@ -865,7 +952,7 @@ Illustration of array index aggregation with additional with binning (several nr
|
||||
##### Command
|
||||
|
||||
```bash
|
||||
curl -H "Content-Type: application/json" -X POST -d '{"aggregationType":"extrema","aggregations":["min","max","sum"],"fields":["pulseId","value"],"range":{"startPulseId":0,"endPulseId":3},"channels":["Channel_01"]}' http://data-api.psi.ch/sf/query | python -m json.tool
|
||||
curl -H "Content-Type: application/json" -X POST -d '"aggregation":{"aggregationType":"extrema","aggregations":["min","max","sum"]},"fields":["pulseId","value"],"range":{"startPulseId":0,"endPulseId":3},"channels":["Channel_01"]}' http://data-api.psi.ch/sf/query | python -m json.tool
|
||||
```
|
||||
|
||||
##### Response
|
||||
|
||||
Reference in New Issue
Block a user