---
name: "pmSeriesQuery"
section: "3"
platform: "linux"
package: "pcp"
version: "7.2.2-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/pmSeriesQuery"
---

# pmSeriesQuery(3)

fast, scalable time series querying

## 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 Performance Co-Pilot (PCP) fast, scalable time series services is achieved using the [**pmseries**(1)](/pmseries/1.md) utility, and associated [**pmproxy**(1)](/pmproxy/1.md) 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 fashion where callbacks are invoked for each set of series identifiers or values structure being returned. These callbacks must be registered using [**pmSeriesSetup**(3)](/pmSeriesSetup/3.md) 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 unchanged and is typically used to access a data structure maintaining state within the calling program.

Depending on the **pmseries** *query* string provided, **pmSeriesQuery** operates 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 dynamically created and persistently associated with the expression. The **query** expression may be retrieved with the **pmSeriesExprs**(3) API call. See also [**PMWEBAPI**(3)](/PMWEBAPI/3.md) and the **-e** option to [**pmseries**(1)](/pmseries/1.md).

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 create 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)](/pmSeriesDescs/3.md) manual page.

Typically, loading of time series is handled automatically by the **pmproxy** daemon, which uses the [**pmDiscoverSetup**(3)](/pmDiscoverSetup/3.md) series of interfaces to automatically detect and load logged time series from [**pmlogger**(1)](/pmlogger/1.md). 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.

## SEE ALSO

[**pmproxy**(1)](/pmproxy/1.md), [**pmlogger**(1)](/pmlogger/1.md), [**pmSeriesSetup**(3)](/pmSeriesSetup/3.md), [**pmSeriesDescs**(3)](/pmSeriesDescs/3.md), [**pmDiscoverSetup**(3)](/pmDiscoverSetup/3.md), [**PMAPI**(3)](/PMAPI/3.md) and [**PMWEBAPI**(3)](/PMWEBAPI/3.md).