# pmseriesquery

## NAME



           **pmSeriesQuery** , **pmSeriesWindow** , **pmSeriesValues** , **pmSeriesLoad** -
           fast, scalable time series querying
    


## C SYNOPSIS



           **#include <pcp/pmwebapi.h>**
    
           **int pmSeriesQuery(pmSeriesSettings ***_sp_**, sds ***_query_**,**
                             **pmSeriesFlags** _flags_**, void ***_arg_**);**
           **int pmSeriesWindow(pmSeriesSettings ***_sp_**, sds ***_window_**,**
                              **pmSeriesTimeWindow ***_window_**, void ***_arg_**);**
           **int pmSeriesValues(pmSeriesSettings ***_sp_**,**
                              **pmSeriesTimeWindow ***_window_**, int** _count_**,**
                              **sds ***_series_**, void ***_arg_**);**
           **int pmSeriesLoad(pmSeriesSettings ***_sp_**, sds ***_query_**,**
                            **pmSeriesFlags** _flags_**, void ***_arg_**);**
    
           **cc ... -lpcp_web**
    


## DESCRIPTION



           Searching for time series identifiers and values using the Perfor‐
           mance  Co-Pilot  (PCP)  fast,  scalable  time  series  services is
           achieved using the pmseries(1) utility, and associated  pmproxy(1)
           REST API service.
    
           The implementation of these facilities is shared and available for
           other  programs  to  use  as  well.  The functionality is provided
           through asynchronous APIs, which function in an event-driven fash‐
           ion where callbacks are invoked for each set of series identifiers
           or values structure being returned.  These callbacks must be  reg‐
           istered  using  pmSeriesSetup(3)  before  any  query API calls are
           made.
    
           As a general pattern, these interfaces  take  an  opaque  (void  *
           pointer)  parameter, _arg_.  This pointer will be passed through un‐
           changed and is typically used to access a data structure maintain‐
           ing state within the calling program.
    
           Depending on the **pmseries** _query_ string provided, **pmSeriesQuery** op‐
           erates in one of two modes.
    
           Firstly, if no  time  window  specification  is  provided  (square
           brackets),  then  the  interface  will return only matching series
           identifiers and no values.  These identifiers are returned via the
           _on_match_ callback registered using **pmSeriesSetup**.   If  the  _query_
           expression includes function calls or arithmetic operators (rather
           than simple metric names), then the returned identifier is dynami‐
           cally  created  and  persistently  associated with the expression.
           The **query** expression may be retrieved  with  the  **pmSeriesExprs**(3)
           API call.  See also PMWEBAPI(3) and the **-e** option to pmseries(1).
    
           The  second  mode  is where a time window specification is used in
           the _query_ string, or when the **pmSeriesValues** interface  is  used.
           This  mode  provides  values and time stamps for all matching time
           series identifiers having data points  within  the  provided  time
           _window_.   In  this case, the results are returned via the _on_value_
           callback registered using **pmSeriesSetup**.  A helper routine to cre‐
           ate a time _window_ structure from a  square-bracket  enclosed  time
           specification is provided in the form of **pmSeriesWindow**.
    
           Further  metadata  (metric  names, labels, units, semantics, type,
           etc) about matched time series and their values  can  be  obtained
           using  the  interfaces  described  on  the pmSeriesDescs(3) manual
           page.
    
           Typically, loading of time series is handled automatically by  the
           **pmproxy** daemon, which uses the pmDiscoverSetup(3) series of inter‐
           faces  to  automatically  detect  and load logged time series from
           pmlogger(1).  However, it is also possible to manually  load  time
           series  from  a PCP archive using the **pmSeriesLoad** interface.  The
           provided _query_ string must provide an archive or directory to load
           data from using the _source.path_ keyword.
    


## DIAGNOSTICS



           Where these functions return a status code, this is always zero on
           success.  On failure a negative PMAPI error code is returned.
    


* * *