API Reference

Multiple Event Query (Interval)

Query for all events on the timeline between the begin (inclusive) and end (exclusive) dates.

Path: myquery/interval

Request URL Parameters

Name	Description	Value Format	Required	Default
c	EPICS Channel name	String	YES
b	Inclusive begin date with optional time	String in ISO 8601 format (YYYY-MM-DD[Thh:mm:[ss]])	YES
e	Exclusive end date with optional time	String in ISO 8601 format (YYYY-MM-DD[Thh:mm:[ss]])	YES
l	Limit by binning / sampling	Integer, number of samples or bins. No sampling if absent	NO	No sampling is done
t	type of sampling	String: 'graphical', 'simpleevent', 'myget', 'mysampler'	NO	'graphical'
m	MYA deployment	String	NO	'ops'
f	Fractional seconds time digits	Integer (0-6)	NO	0 (ISO 8601 only)
v	Significant figures	Integer (1-18)	NO	6 (floats only)
d	Data update events only (ignore info events)	Boolean, true if parameter exits	NO	All events returned (update and info)
p	Include prior point (guarantee at least one point in result)	Boolean, true if parameter exists	NO	Prior point isn't included
s	Enumerations as strings	Boolean, true if parameter exists	NO	Enumerations presented as ordinal number
u	Timestamps as milliseconds from UNIX Epoch	Boolean, true if parameter exists	NO	Timestamps are returned in ISO 8601 format (local server time)
a	Timestamps as milliseconds at the server zone offset*	Boolean, true if parameter exists	NO	Timestamps milliseconds in UTC
i	Integrate (float data-types only)†	Boolean, true if parameter exists	NO	No integration is performed

*Some clients like web browsers have limited access to an IANA timezone database so it is convenient if the server does local timezone (America/New_York - EST and EDT) shifting of historic time series and clients can interpret time series as timezone-less UTC internally yet present it as local time. Note: this does mean results may contain two data points for 1:00 AM where that Fall hour is duplicated due to the daylight savings boundary and an hour in the Spring that is skipped. In other words: The data values are identical, just timestamps can differ: two 1:00 AM vs both a 1:00 AM EST and 1:00 AM EDT.

†Both integrated and non integrated values are returned. The "raw" value has key "v" and the integrated value key is "i".

Response JSON Format
On Success (HTTP 200 Response Code):

{   
    "datatype":"<EPICS datatype>",     
    "datasize":"<data vector size; 1 for scalar>",    
    "datahost":"<MYA hostname of data home>",      
    "sampled":"<true if sampled, false otherwise>", 
    "sampleType":"<graphical, simpleevent, myget, mysampler; only present if sampled = true>",
    "count":"<original count of events; only present if sampled = true>",
    "labels":"<An array of historic labels; only present if datatype = DBR_ENUM>",
    "data":[   
        {   
            "d":"<DATE-TIME>",   
            "v":"<VALUE>",  
            "t":"<TYPE (only present if not update)>",  
            "i":"<INTEGRATED VALUE (only present if requested with i option)>",
            "x":"<DISCONNECTION-TRUE/FALSE (only present if disconnection)>"    
        },   
        ...   
    ]    
}

On Error (HTTP 400 Repsonse Code):

{   
    "error":"<error reason>"   
}

Sampling Routines Explained:

The graphical (default) application-level event-based routine returns a data set that attempts to maintain graphical fidelity. The signal is split into approximately the number of specified bins (l), with each bin returning important characteristics such as min, max, non-update events, largest triangluar three bucket (LTTB) point. This makes the number of returned data points somewhat unpredicatable, but generally gives very good graphical results even for heavily downsampled signals.
The simpleevent application-level event-based routine returns every nth event, where n is based on the "l" parameter and the number of events in the requested channel history (n = count/l). This gives greater detail to portions of the signal that are "busier", but may leave portions of the time domain sparsely represented.
The myget database-level time-based routine splits the time range up into the number of equally sized specified bins (l) and returns the first data point from each bin. This tries to give equal time-representation throughout the channel history.
The mysampler application-level time-based routine splits the time range up into the number of equally sized specified bins (l) and returns the previous data point before each bin with timestamps modified to start of bin. Only a single database query is currently used in contrast to the previous multi-query approach. This tries to give regularly spaced data points by creating them from implied values (converts MYA's delta-based data into regularly sampled data).

Single Event Query (Point)

Query for a single event on the timeline closest to the specified point. The direction to search from the point is determined by the 'w' parameter.

Path: myquery/point

Request Parameters

Name	Description	Value Format	Required	Default
c	EPICS Channel name	String	YES
t	Time of interest date with optional time	String in ISO 8601 format (YYYY-MM-DD[Thh:mm:[ss]])	YES
m	MYA deployment	String	NO	'ops'
f	Fractional seconds time digits	Integer (0-6)	NO	0 (ISO 8601 only)
v	Significant figures	Integer (1-18)	NO	6 (floats only)
d	Data update events only (ignore info events)	Boolean, true if parameter exits	NO	All events returned (update and info)
w	Get closest event greater than time of interest	Boolean, true if parameter exists	NO	Get closest event less than time of interest
x	Closest event is exclusive of time of interest	Boolean, true if parameter exists	NO	Closest event is inclusive of time of interest
s	Enumerations as strings	Boolean, true if parameter exists	NO	Enumerations presented as ordinal number
u	Timestamps as milliseconds from UNIX Epoch	Boolean, true if parameter exists	NO	Timestamps are returned in ISO 8601 format
a	Timestamps as milliseconds at the server zone offset	Boolean, true if parameter exists	NO	Timestamps milliseconds in UTC

Response JSON Format
On Success (HTTP 200 Response Code):

{   
    "datatype":"<EPICS datatype>",     
    "datasize":"<data vector size; 1 for scalar>",    
    "datahost":"<MYA hostname of data home>",  
    "data":{   
        "d":"<DATE-TIME>",   
        "v":"<VALUE>",  
        "t":"<TYPE (only present if not update)>",
        "x":"<DISCONNECTION-TRUE/FALSE (only present if disconnection)>"            
        }   
}

On Error (HTTP 400 Repsonse Code):

{   
    "error":"<error reason>"   
}

Wildcard PV lookup Query (Channel)

Query for all PVs with name like the provided wildcard query string. Wildcard characters include % (any) and _ (one). The results are sorted in ascending order by name.

Path: myquery/channel

Request Parameters

Name	Description	Value Format	Required	Default
q	EPICS Channel name wildcard query	String	YES
l	Limit results	Number	NO	10
o	Offset (pagination)	Number	NO	0
m	MYA deployment	String	NO	'ops'

Response JSON Format
On Success (HTTP 200 Response Code):

[   
    {
    "name":"<PV name>",
    "datatype":"<EPICS datatype>",     
    "datasize":"<data vector size; 1 for scalar>",    
    "datahost":"<MYA hostname of data home>",  
    "ioc":"<name of IOC generating updates or null if unavailable>",
    "active":"<true if active, false otherwise>"
    },
    ...
]

On Error (HTTP 400 Repsonse Code):

{   
    "error":"<error reason>"   
}

MySampler

Return the value of a set of channels at regularly spaced intervals from a target start time (inclusive). This is similar in practice to the command line mySampler utility. An UNDEFINED event is returned if the channel value is unavailable at the sample time for a channel.

Path: myquery/mysampler

Request Parameters

Name	Description	Value Format	Required	Default
c	EPICS Channel names separated by commas (no spaces)	String	YES
b	Begin date with optional time for the start of sampling.	String in ISO 8601 format (YYYY-MM-DD[Thh:mm:[ss]])	YES
n	Number of samples to take	Integer	YES
s	Step size between samples in milliseconds	Integer	YES
m	MYA deployment	String	NO	'ops'
f	Fractional seconds time digits in response	Integer (0-6)	NO	0 (ISO 8601 only)
v	Significant figures	Integer (1-18)	NO	6 (floats only)
d	Data update events only (ignore disconnect events)	Boolean, true if parameter exits	NO	All events returned (update and info)
e	Enumerations as strings	Boolean, true if parameter exists	NO	Enumerations presented as ordinal number
u	Timestamps as milliseconds from UNIX Epoch	Boolean, true if parameter exists	NO	Timestamps are returned in ISO 8601 format
a	Timestamps as milliseconds at the server zone offset	Boolean, true if parameter exists	NO	Timestamps milliseconds in UTC
x	Which sampling strategy to use, streaming (s) or n_queries (n)	String	NO	n_queries strategy

Response JSON Format
On Success (HTTP 200 Response Code):

{
  "channels": {
    "<PV_NAME_1>": {
      "metadata": {
        "name":"<PV name>",
        "datatype":"<EPICS datatype>",     
        "datasize":"<data vector size; 1 for scalar>",    
        "datahost":"<MYA hostname of data home>",  
        "ioc":"<name of IOC generating updates or null if unavailable>",
        "active":"<true if active, false otherwise>"
      },
      "data": [
        {
          "d":"<DATE-TIME>",   
          "v":"<VALUE>",  
          "t":"<TYPE (only present if not update)>",
          "x":"<DISCONNECTION-TRUE/FALSE (only present if disconnection)>"     
        },
        ...
      ],
      "returnCount": <number of data points>
    },
    "<PV_NAME_2>": {
      ...
    }
  }
}

On Error (HTTP 400 Response Code):
Each individual PV may produce an error. Efforts are made to contain those errors to the response for the problematic PV so that data for "good" PVs can still be returned. However, an error with any PV will result in a HTTP 400 response code to alert the user that something has gone wrong with the query.

Note: Some proxies may override the response body on error and destroy the data for successfully queried PVs in case of HTTP 400.

Error response format example:

{
  "channels": {
    "<channel_name1>": {
      "error": "<error reason>",
    },
    "<channel_name2>": { ...
    }
  }
}

MyStats

Return the a collection of statistical information about a set of PVs over a period of time. This is similar in practice to the command line myStats utility, with the added benefit that you can specify multiple regularly spaced bins over which to calculate the statistics. Generally speaking, the statistics are computed by ignoring "disconnected" sections of the channel history.

Statistics Calculated

Statistic	Description
eventCount	The number of MYA events
updateCount	The number of data update events
duration	The number of seconds the channel was connected
integration	The time integrated value of the signal (\int_begin^end f(t)dt)
max	The maximum value of the signal
mean	The (time-weighted) average value of the signal
min	The minimum value of the signal
rms	The (time-weighted) "root mean squared" value of the signal
stdev	The (time-weighted) standard deviation of the signal

Path: myquery/mystats

Request Parameters

Name	Description	Value Format	Required	Default
c	EPICS Channel names separated by commas (no spaces)	String	YES
b	Begin date with optional time for the start of statistics.	String in ISO 8601 format (YYYY-MM-DD[Thh:mm:[ss]])	YES
e	End date with optional time for the end of statistics.	String in ISO 8601 format (YYYY-MM-DD[Thh:mm:[ss]])	YES
n	Number of bins to calculated statistics over	Integer	YES
m	MYA deployment	String	NO	'ops'
f	Fractional seconds time digits in response	Integer (0-6)	NO	0 (ISO 8601 only)
v	Significant figures	Integer (1-18)	NO	6 (floats only)
d	Data update events only (ignore disconnect events)	Boolean, true if parameter exits	NO	All events returned (update and info)
u	Timestamps as milliseconds from UNIX Epoch	Boolean, true if parameter exists	NO	Timestamps are returned in ISO 8601 format
a	Timestamps as milliseconds at the server zone offset	Boolean, true if parameter exists	NO	Timestamps milliseconds in UTC

Response JSON Format
On Success (HTTP 200 Response Code):

{
  "channels": {
    "<PV_NAME_1>": {
      "metadata": {
        "name":"<PV name>",
        "datatype":"<EPICS datatype>",     
        "datasize":"<data vector size; 1 for scalar>",    
        "datahost":"<MYA hostname of data home>",  
        "ioc":"<name of IOC generating updates or null if unavailable>",
        "active":"<true if active, false otherwise>"
      },
      "data": [
        {
          "begin": "<Starting timestamp of bin>",
          "eventCount": <number of mya events>,
          "updateCount": <number of data update events>,
          "duration": <number of seconds channel was connected to mya>,
          "integration": <time integrated value of channel>,
          "max": <maximum channel value>,
          "mean": <time-weighted average value>,
          "min": <minimum channel value>,
          "rms": <time-weighted root mean squared value>,
          "stdev": <time-weighted standard deviation of the value>
        },
        {
          "begin": ...
        }
      ],
      "returnCount": <number_bins>
    }
  }
}

On Error (HTTP 400/500 Response Codes):
Each individual PV may produce an error. Efforts are made to contain those errors to the response for the problematic PV so that data for "good" PVs can still be returned. However, an error with any PV will result in a HTTP 400 response code to alert the user that something has gone wrong with the query.

A more general error will produce an HTTP 500 code. The output will be unpredictable in this case.

Note: Some proxies may override the response body on error and destroy the data for successfully queried PVs in case of error.

Error response format example (HTTP 400):

{
  "error": "<error reason>"
}

Event Types

Use the 'd' parameter to limit events to updates only. There are essentially two classes of events - disconnnect and data events. The primary data event type is an 'update', which is a normal data value that is not the first data point in the MYA archiver for that channel. Other data update events include additional information as to why there is no prior data. Disconnect event types have no data associated with them, but provide information on the type of disconnect:

Disconnection Events

NETWORK_DISCONNECTION
ARCHIVING_OF_CHANNEL_TURNED_OFF
ARCHIVER_SHUTDOWN
UNKNOWN_UNAVAILABILTY
NAN_OR_INFINITY
UNDEFINED (primarily used for sampling applications)

Miscellaneous Events

ORIGIN_OF_CHANNELS_HISTORY
CHANNELS_PRIOR_DATA_MOVED_OFFLINE
CHANNELS_PRIOR_DATA_DISCARDED

Disconnection events are also flagged with the presence of the attribute 'x' for convenience.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

API Reference

Table of Contents

Multiple Event Query (Interval)

Single Event Query (Point)

Wildcard PV lookup Query (Channel)

MySampler

MyStats

Event Types

Clone this wiki locally