From 1aa5b86b9421a43b7e4162d20faafbad64945182 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20M=C3=A4rki?= Date: Wed, 28 Oct 2015 11:31:15 +0100 Subject: [PATCH] ATEST-246 --- Readme.md | 153 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 112 insertions(+), 41 deletions(-) diff --git a/Readme.md b/Readme.md index 8dfdef3..2fdb6f2 100644 --- a/Readme.md +++ b/Readme.md @@ -72,6 +72,59 @@ POST http://:/channels curl -H "Content-Type: application/json" -X POST -d '{"regex": "TRFCA|TRFCB"}' http://sf-nube-14.psi.ch:8080/channels ``` + + +## Query Range + +Queries are applied to a range. Following ranges are supported. + +### By Pulse-Id + +```json +"range":{ + "startPulseId":0, + "endPulseId":100 +} +``` + +- **startPulseId**: The start pulse-id of the range request. +- **endPulseId**: The end pulse-id of the range request. + + +### By Date + +```json +"range":{ + "startDate":"2015-08-06T18:00:00.000", + "startNanos":0, + "endDate":"2015-08-06T18:59:59.999", + "endNanos":999999 +} +``` + +- **startDate**: The start date of the time range (ISO8601 format (YYYY-MM-DDThh:mm:ss.sTZD e.g. 1997-07-16T19:20:30.475+02:00 (omitting +02:00 falls back to the local time zone)). +- **[startNanos]**: The optional nanosecond offset to the milliseconds (range [0..999999]). +- **endDate**: The end date of the time range. +- **[endNanos]**: The optional nanosecond offset. + + +### By Time + +```json +"range":{ + "startMillis":0, + "startNanos":0, + "endMillis":100, + "endNanos":999999 +} +``` + +- **startMillis**: The start time of the range in milliseconds since January 1, 1970 (the UNIX/JAVA epoch). +- **[startNanos]**: The optional nanosecond offset to the milliseconds (range [0..999999]). +- **endMillis**: The end time of the range. +- **[endNanos]**: The optional nanosecond offset. + + ## Query Data @@ -89,9 +142,7 @@ A request is performed using JSON. The JSON query defines the channels to be que 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]). +- **range**: The range of the query (see [Query Range](Readme.md#query_range)). - **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. @@ -105,7 +156,7 @@ There exist following fields: ### Example ```bash -curl -H "Content-Type: application/json" -X POST -d '{"channels":["channel1","channel2"],"startPulseId":0,"endPulseId":4}' http://sf-nube-14.psi.ch:8080/query +curl -H "Content-Type: application/json" -X POST -d '{"range":{"startPulseId":0,"endPulseId":4},"channels":["channel1","channel2"]}' http://sf-nube-14.psi.ch:8080/query ``` ### Response example @@ -233,8 +284,10 @@ Following examples build on a waveform data (see below). They also work for scal ```json { - "startPulseId":0, - "endPulseId":3, + "range":{ + "startPulseId":0, + "endPulseId":3 + }, "channels":[ "Channel_01" ] @@ -244,7 +297,7 @@ Following examples build on a waveform data (see below). They also work for scal ###### Command ```bash -curl -H "Content-Type: application/json" -X POST -d '{"startPulseId":0,"endPulseId":3,"channels":["Channel_01"]}' http://sf-nube-14.psi.ch:8080/query +curl -H "Content-Type: application/json" -X POST -d '{"range":{"startPulseId":0,"endPulseId":3},"channels":["Channel_01"]}' http://sf-nube-14.psi.ch:8080/query ``` ###### Response @@ -257,10 +310,12 @@ See JSON representation of the data above. ```json { - "startMillis":0, - "startNanos":0, - "endMillis":30, - "endNanos":999999, + "range":{ + "startMillis":0, + "startNanos":0, + "endMillis":30, + "endNanos":999999 + }, "channels":[ "Channel_01" ] @@ -270,7 +325,7 @@ See JSON representation of the data above. ###### Command ```bash -curl -H "Content-Type: application/json" -X POST -d '{"startMillis":0,"startNanos":0,"endMillis":30,"endNanos":999999,"channels":["Channel_01"]}' http://sf-nube-14.psi.ch:8080/query +curl -H "Content-Type: application/json" -X POST -d '{"range":{"startMillis":0,"startNanos":0,"endMillis":30,"endNanos":999999},"channels":["Channel_01"]}' http://sf-nube-14.psi.ch:8080/query ``` ###### Response @@ -283,22 +338,24 @@ See JSON representation of the data above. ```json { - "startDate":"1970/01/01 01:00:00.000", - "startNanos":0, - "endDate":"1970/01/01 01:00:00.030", - "endNanos":999999, + "range":{ + "startDate":"1970-01-01T01:00:00.000", + "startNanos":0, + "endDate":"1970-01-01T01:00:00.030", + "endNanos":999999 + }, "channels":[ "Channel_01" ] } ``` -Supported formats: *yyyy/MM/dd HH:mm:ss.SSS* and *dd.MM.yyyy HH:mm:ss.SSS* +Supported format is ISO8601 *YYYY-MM-DDThh:mm:ss.sTZD* (e.g. *1997-07-16T19:20:30.475+02:00*). ###### Command ```bash -curl -H "Content-Type: application/json" -X POST -d '{"startDate":"1970/01/01 01:00:00.000","startNanos":0,"endDate":"1970/01/01 01:00:00.030","endNanos":999999,"channels":["Channel_01"]}' http://sf-nube-14.psi.ch:8080/query +curl -H "Content-Type: application/json" -X POST -d '{"range":{"startDate":"1970-01-01T01:00:00.000","startNanos":0,"endDate":"1970-01-01T01:00:00.030","endNanos":999999},"channels":["Channel_01"]}' http://sf-nube-14.psi.ch:8080/query ``` ###### Response @@ -312,10 +369,12 @@ See JSON representation of the data above. ```json { "dbMode":"archiverappliance", - "startMillis":0, - "startNanos":0, - "endMillis":30, - "endNanos":999999, + "range":{ + "startMillis":0, + "startNanos":0, + "endMillis":30, + "endNanos":999999 + }, "channels":[ "Channel_01" ] @@ -328,7 +387,7 @@ Archiver Appliance supports queries by *time range* and *date range* only (as it ###### Command ```bash -curl -H "Content-Type: application/json" -X POST -d '{"dbmode":"archiverappliance","startMillis":0,"startNanos":0,"endMillis":30,"endNanos":999999,"channels":["Channel_01"]}' http://sf-nube-14.psi.ch:8080/query +curl -H "Content-Type: application/json" -X POST -d '{"dbmode":"archiverappliance","range":{"startMillis":0,"startNanos":0,"endMillis":30,"endNanos":999999},"channels":["Channel_01"]}' http://sf-nube-14.psi.ch:8080/query ``` ###### Response @@ -344,8 +403,10 @@ Allows for server side optimizations since not all data needs to be retrieved. ```json { "fields":["pulseId","value"], - "startPulseId":0, - "endPulseId":3, + "range":{ + "startPulseId":0, + "endPulseId":3 + }, "channels":[ "Channel_01" ] @@ -355,7 +416,7 @@ Allows for server side optimizations since not all data needs to be retrieved. ###### Command ```bash -curl -H "Content-Type: application/json" -X POST -d '{"fields":["pulseId","value"],"startPulseId":0,"endPulseId":3,"channels":["Channel_01"]}' http://sf-nube-14.psi.ch:8080/query +curl -H "Content-Type: application/json" -X POST -d '{"fields":["pulseId","value"],"range":{"startPulseId":0,"endPulseId":3},"channels":["Channel_01"]}' http://sf-nube-14.psi.ch:8080/query ``` ###### Response @@ -392,8 +453,10 @@ curl -H "Content-Type: application/json" -X POST -d '{"fields":["pulseId","value { "ordering":"desc", "fields":["pulseId","value"], - "startPulseId":0, - "endPulseId":3, + "range":{ + "startPulseId":0, + "endPulseId":3 + }, "channels":[ "Channel_01" ] @@ -406,7 +469,7 @@ Use **none** in case ordering does not matter (allows for server side optimizati ###### Command ```bash -curl -H "Content-Type: application/json" -X POST -d '{"ordering":"desc","fields":["pulseId","value"],"startPulseId":0,"endPulseId":3,"channels":["Channel_01"]}' http://sf-nube-14.psi.ch:8080/query +curl -H "Content-Type: application/json" -X POST -d '{"ordering":"desc","fields":["pulseId","value"],"range":{"startPulseId":0,"endPulseId":3},"channels":["Channel_01"]}' http://sf-nube-14.psi.ch:8080/query ``` ###### Response @@ -446,8 +509,10 @@ curl -H "Content-Type: application/json" -X POST -d '{"ordering":"desc","fields" "aggregationType":"value", "aggregations":["min","max","mean"], "fields":["pulseId","value"], - "startPulseId":0, - "endPulseId":3, + "range":{ + "startPulseId":0, + "endPulseId":3 + }, "channels":[ "Channel_01" ] @@ -457,7 +522,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"],"startPulseId":0,"endPulseId":3,"channels":["Channel_01"]}' http://sf-nube-14.psi.ch:8080/query +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://sf-nube-14.psi.ch:8080/query ``` ###### Response @@ -518,8 +583,10 @@ Array value [aggregations](https://github.psi.ch/projects/ST/repos/ch.psi.daq.qu "aggregationType":"value", "aggregations":["min","max","mean"], "fields":["pulseId","value"], - "startPulseId":0, - "endPulseId":3, + "range":{ + "startPulseId":0, + "endPulseId":3 + }, "channels":[ "Channel_01" ] @@ -529,7 +596,7 @@ Array value [aggregations](https://github.psi.ch/projects/ST/repos/ch.psi.daq.qu ###### Command ```bash -curl -H "Content-Type: application/json" -X POST -d '{"nrOfBins":2,"aggregationType":"value","aggregations":["min","max","mean"],"fields":["pulseId","value"],"startPulseId":0,"endPulseId":3,"channels":["Channel_01"]}' http://sf-nube-14.psi.ch:8080/query +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://sf-nube-14.psi.ch:8080/query ``` ###### Response @@ -573,8 +640,10 @@ Array value [aggregations](https://github.psi.ch/projects/ST/repos/ch.psi.daq.qu "aggregationType":"index", "aggregations":["min","max","mean","sum"], "fields":["pulseId","value"], - "startPulseId":0, - "endPulseId":3, + "range":{ + "startPulseId":0, + "endPulseId":3 + }, "channels":[ "Channel_01" ] @@ -584,7 +653,7 @@ Array value [aggregations](https://github.psi.ch/projects/ST/repos/ch.psi.daq.qu ###### Command ```bash -curl -H "Content-Type: application/json" -X POST -d '{"nrOfBins":1,"aggregationType":"index","aggregations":["min","max","mean","sum"],"fields":["pulseId","value"],"startPulseId":0,"endPulseId":3,"channels":["Channel_01"]}' http://sf-nube-14.psi.ch:8080/query +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://sf-nube-14.psi.ch:8080/query ``` ###### Response @@ -640,8 +709,10 @@ curl -H "Content-Type: application/json" -X POST -d '{"nrOfBins":1,"aggregationT "aggregationType":"extrema", "aggregations":["min","max","sum"], "fields":["pulseId","value"], - "startPulseId":0, - "endPulseId":3, + "range":{ + "startPulseId":0, + "endPulseId":3 + }, "channels":[ "Channel_01" ] @@ -651,7 +722,7 @@ curl -H "Content-Type: application/json" -X POST -d '{"nrOfBins":1,"aggregationT ###### Command ```bash -curl -H "Content-Type: application/json" -X POST -d '{"aggregationType":"extrema","aggregations":["min","max","sum"],"fields":["pulseId","value"],"startPulseId":0,"endPulseId":3,"channels":["Channel_01"]}' http://sf-nube-14.psi.ch:8080/query +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://sf-nube-14.psi.ch:8080/query ``` ###### Response