151 lines
5.4 KiB
Markdown
151 lines
5.4 KiB
Markdown
#Overview
|
|
|
|
This project provides a REST interface to execute queries on the databuffer.
|
|
|
|
# Requirements
|
|
|
|
This project requires Java 8 or greater.
|
|
|
|
# Deployment
|
|
|
|
Use the instructions provided by [ch.psi.daq.install](https://github.psi.ch/projects/ST/repos/ch.psi.daq.install/browse#query_rest) to install the application on a server.
|
|
|
|
## Application Properties
|
|
|
|
Following files define and describe application properties:
|
|
|
|
- [Cassandra](https://github.psi.ch/projects/ST/repos/ch.psi.daq.cassandra/browse/src/main/resources/cassandra.properties) specific properties.
|
|
- [Query](https://github.psi.ch/projects/ST/repos/ch.psi.daq.dispatcher/browse/src/main/resources/query.properties) specific properties..
|
|
- [Query REST](https://github.psi.ch/projects/ST/repos/ch.psi.daq.queryrest/browse/src/main/resources/queryrest.properties) specific properties.
|
|
|
|
It is possible to overwrite properties by defining new values in `${HOME}/.config/daq/queryrest.properties`
|
|
|
|
<a name="rest_interface"/>
|
|
|
|
# REST Interface
|
|
|
|
<a name="query_channel_names"/>
|
|
|
|
## Query Channel Names
|
|
|
|
### Request
|
|
|
|
```
|
|
POST http://<host>:<port>/channels
|
|
```
|
|
|
|
#### Data
|
|
|
|
```
|
|
{"regex": "TRFCA|TRFCB", "dbMode": "databuffer"}
|
|
```
|
|
|
|
##### Explanation
|
|
|
|
- **regex**: Reqular expression used to filter channel names (default: no filtering). Filtering is done using JAVA's [Pattern](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html), more precisely [Matcher.find()](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Matcher.html#find--)).
|
|
- **dbMode**: Defines the database to access (values: **databuffer**|archiverappliance)
|
|
|
|
|
|
### Example
|
|
|
|
```
|
|
curl -H "Content-Type: application/json" -X POST -d '{"regex": "TRFCA|TRFCB"}' http://sf-nube-14.psi.ch:8080/channels
|
|
```
|
|
|
|
<a name="query_data"/>
|
|
|
|
## Query Data
|
|
|
|
### Request
|
|
|
|
```
|
|
GET http://<host>:<port>/query
|
|
```
|
|
|
|
#### Data
|
|
|
|
A request is performed using JSON. The JSON query defines the channels to be queried, the range, and how the data should be aggregated (this is optional but highly recommended).
|
|
|
|
There exist following fields:
|
|
|
|
- **channels**: Array of channel names to be queried.
|
|
- **startPulseId** and **endPulseId** : A pulse-id range request with start and end pulse-id.
|
|
- **startMillis/[startNanos]** and **endMillis/[endNanos]**: A time range request with start and end milliseconds since January 1, 1970 (the UNIX/JAVA epoch) and optionally supplemented with the nanosecond offset to the milliseconds (range [0..999999]).
|
|
- **startDate/[startNanos]** and **endDate/[endNanos]**: A time range request with start and end date (format yyyy/MM/dd HH:mm:ss.SSS or dd.MM.yyyy HH:mm:ss.SSS) and optionally supplemented with the nanosecond offset to the milliseconds (range [0..999999]).
|
|
- **ordering**: The ordering of the data (see [here](https://github.psi.ch/projects/ST/repos/ch.psi.daq.common/browse/src/main/java/ch/psi/daq/common/ordering/Ordering.java) for possible values).
|
|
- **fields**: The requested fields (see [here](https://github.psi.ch/projects/ST/repos/ch.psi.daq.query/browse/src/main/java/ch/psi/daq/query/model/QueryField.java) for possible values).
|
|
- **nrOfBins**: Activates data binning. Specifies the number of bins the pulse/time range should be devided 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.
|
|
- **aggregations**: Activates data aggregation. Array of requested aggregations (see [here](https://github.psi.ch/projects/ST/repos/ch.psi.daq.query/browse/src/main/java/ch/psi/daq/query/model/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/projects/ST/repos/ch.psi.daq.query/browse/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**)
|
|
|
|
|
|
### Example
|
|
|
|
```
|
|
curl -H "Content-Type: application/json" -X GET -d '{"channels":["channel1","channel2"],"startPulseId":0,"endPulseId":4}' http://sf-nube-14.psi.ch:8080/channels
|
|
```
|
|
|
|
### Response example
|
|
|
|
The response is in 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 JSON Queries
|
|
|
|
**TODO:** |