PIQuery¶

The PIQuery class provides a fluent, method-chaining interface for building PI data queries. It’s accessed through PIClient.query().

PIQuery Class¶

class pipolars.PIQuery[source]¶

Bases: object

Fluent query builder for PI data.

This class provides a method-chaining interface for building PI data queries in a readable, declarative style.

Example

>>> df = client.query("SINUSOID") \
...     .time_range("*-1d", "*") \
...     .recorded() \
...     .with_quality() \
...     .to_dataframe()

>>> df = client.query(["TAG1", "TAG2"]) \
...     .last(hours=24) \
...     .interpolated(interval="15m") \
...     .pivot() \
...     .to_dataframe()

>>> df = client.query("SINUSOID") \
...     .time_range("*-7d", "*") \
...     .summary(SummaryType.AVERAGE, SummaryType.MAXIMUM) \
...     .to_dataframe()

Time Range Methods

time_range(start, end)[source]¶

Set the time range for the query.

Parameters:

start (datetime | str | AFTime) – Start time (datetime, string, or AFTime)
end (datetime | str | AFTime) – End time

Returns:

Self for method chaining

Return type:

PIQuery

last(hours=0, days=0, minutes=0, seconds=0)[source]¶

Set time range to the last N time units.

Parameters:

hours (int) – Number of hours
days (int) – Number of days
minutes (int) – Number of minutes
seconds (int) – Number of seconds

Returns:

Self for method chaining

Return type:

PIQuery

today()[source]¶

Set time range to today.

Returns:: Self for method chaining
Return type:: PIQuery

yesterday()[source]¶

Set time range to yesterday.

Returns:: Self for method chaining
Return type:: PIQuery

this_week()[source]¶

Set time range to this week.

Returns:: Self for method chaining
Return type:: PIQuery

this_month()[source]¶

Set time range to this month.

Returns:: Self for method chaining
Return type:: PIQuery

Query Type Methods

recorded(max_count=0)[source]¶

Query for recorded values.

Parameters:: max_count (int) – Maximum values to return (0 = no limit)
Returns:: Self for method chaining
Return type:: PIQuery

interpolated(interval='1h')[source]¶

Query for interpolated values.

Parameters:: interval (str) – Time interval (e.g., “1h”, “15m”, “1d”)
Returns:: Self for method chaining
Return type:: PIQuery

plot(intervals=640)[source]¶

Query for plot-optimized values.

Parameters:: intervals (int) – Number of intervals
Returns:: Self for method chaining
Return type:: PIQuery

summary(*summary_types)[source]¶

Query for summary statistics.

Parameters:: *summary_types (SummaryType) – Summary types to calculate
Returns:: Self for method chaining
Return type:: PIQuery

snapshot()[source]¶

Query for current snapshot values.

Returns:: Self for method chaining
Return type:: PIQuery

Option Methods

with_quality()[source]¶

Include quality information in results.

Returns:: Self for method chaining
Return type:: PIQuery

without_quality()[source]¶

Exclude quality information from results.

Returns:: Self for method chaining
Return type:: PIQuery

boundary(boundary_type)[source]¶

Set the boundary type for recorded values.

Parameters:: boundary_type (BoundaryType) – Boundary type to use
Returns:: Self for method chaining
Return type:: PIQuery

filter(expression)[source]¶

Set a filter expression.

Parameters:: expression (str) – PI filter expression
Returns:: Self for method chaining
Return type:: PIQuery

pivot()[source]¶

Pivot results to wide format (tags as columns).

Returns:: Self for method chaining
Return type:: PIQuery

limit(max_count)[source]¶

Limit the number of values returned.

Parameters:: max_count (int) – Maximum values per tag
Returns:: Self for method chaining
Return type:: PIQuery

Execution Methods

to_dataframe()[source]¶

Execute the query and return a Polars DataFrame.

Returns:: DataFrame with query results
Return type:: DataFrame

to_lazy_frame()[source]¶

Execute the query and return a Polars LazyFrame.

Returns:: LazyFrame for deferred execution
Return type:: LazyFrame

__init__(client, tags)[source]¶

Initialize the query builder.

Parameters:

client (PIClient) – PIClient instance
tags (list[str]) – List of tags to query

time_range(start, end)[source]¶

Set the time range for the query.

Parameters:

start (datetime | str | AFTime) – Start time (datetime, string, or AFTime)
end (datetime | str | AFTime) – End time

Returns:

Self for method chaining

Return type:

PIQuery

last(hours=0, days=0, minutes=0, seconds=0)[source]¶

Set time range to the last N time units.

Parameters:

hours (int) – Number of hours
days (int) – Number of days
minutes (int) – Number of minutes
seconds (int) – Number of seconds

Returns:

Self for method chaining

Return type:

PIQuery

today()[source]¶

Set time range to today.

Returns:: Self for method chaining
Return type:: PIQuery

yesterday()[source]¶

Set time range to yesterday.

Returns:: Self for method chaining
Return type:: PIQuery

this_week()[source]¶

Set time range to this week.

Returns:: Self for method chaining
Return type:: PIQuery

this_month()[source]¶

Set time range to this month.

Returns:: Self for method chaining
Return type:: PIQuery

recorded(max_count=0)[source]¶

Query for recorded values.

Parameters:: max_count (int) – Maximum values to return (0 = no limit)
Returns:: Self for method chaining
Return type:: PIQuery

interpolated(interval='1h')[source]¶

Query for interpolated values.

Parameters:: interval (str) – Time interval (e.g., “1h”, “15m”, “1d”)
Returns:: Self for method chaining
Return type:: PIQuery

plot(intervals=640)[source]¶

Query for plot-optimized values.

Parameters:: intervals (int) – Number of intervals
Returns:: Self for method chaining
Return type:: PIQuery

summary(*summary_types)[source]¶

Query for summary statistics.

Parameters:: *summary_types (SummaryType) – Summary types to calculate
Returns:: Self for method chaining
Return type:: PIQuery

snapshot()[source]¶

Query for current snapshot values.

Returns:: Self for method chaining
Return type:: PIQuery

with_quality()[source]¶

Include quality information in results.

Returns:: Self for method chaining
Return type:: PIQuery

without_quality()[source]¶

Exclude quality information from results.

Returns:: Self for method chaining
Return type:: PIQuery

boundary(boundary_type)[source]¶

Set the boundary type for recorded values.

Parameters:: boundary_type (BoundaryType) – Boundary type to use
Returns:: Self for method chaining
Return type:: PIQuery

filter(expression)[source]¶

Set a filter expression.

Parameters:: expression (str) – PI filter expression
Returns:: Self for method chaining
Return type:: PIQuery

pivot()[source]¶

Pivot results to wide format (tags as columns).

Returns:: Self for method chaining
Return type:: PIQuery

limit(max_count)[source]¶

Limit the number of values returned.

Parameters:: max_count (int) – Maximum values per tag
Returns:: Self for method chaining
Return type:: PIQuery

to_dataframe()[source]¶

Execute the query and return a Polars DataFrame.

Returns:: DataFrame with query results
Return type:: DataFrame

to_lazy_frame()[source]¶

Execute the query and return a Polars LazyFrame.

Returns:: LazyFrame for deferred execution
Return type:: LazyFrame

__repr__()[source]¶

String representation of the query.

QueryOptions Class¶

class pipolars.api.query.QueryOptions[source]¶

Bases: object

Options for a PI query.

query_type: QueryType = 1¶

start: datetime | str | AFTime | None = None¶

end: datetime | str | AFTime | None = None¶

interval: str | None = None¶

max_count: int = 0¶

include_quality: bool = False¶

boundary_type: BoundaryType = 'inside'¶

filter_expression: str | None = None¶

summary_types: list[SummaryType]¶

plot_intervals: int = 640¶

pivot: bool = False¶

__init__(query_type=QueryType.RECORDED, start=None, end=None, interval=None, max_count=0, include_quality=False, boundary_type=BoundaryType.INSIDE, filter_expression=None, summary_types=<factory>, plot_intervals=640, pivot=False)¶

QueryType Enum¶

class pipolars.api.query.QueryType[source]¶

Bases: Enum

Types of PI data queries.

RECORDED = 1¶

INTERPOLATED = 2¶

PLOT = 3¶

SUMMARY = 4¶

SNAPSHOT = 5¶

Usage Examples¶

Basic Query Building¶

from pipolars import PIClient

with PIClient("my-pi-server") as client:
    # Simple recorded values query
    df = (
        client.query("SINUSOID")
        .time_range("*-1d", "*")
        .recorded()
        .to_dataframe()
    )

    # Using convenience time methods
    df = (
        client.query("SINUSOID")
        .last(hours=24)
        .recorded()
        .to_dataframe()
    )

Interpolated Values¶

with PIClient("my-pi-server") as client:
    # Hourly interpolation
    df = (
        client.query("SINUSOID")
        .last(days=7)
        .interpolated(interval="1h")
        .to_dataframe()
    )

    # 15-minute intervals with quality
    df = (
        client.query("SINUSOID")
        .time_range("*-4h", "*")
        .interpolated(interval="15m")
        .with_quality()
        .to_dataframe()
    )

Multi-Tag Queries¶

with PIClient("my-pi-server") as client:
    # Multiple tags, long format
    df = (
        client.query(["TAG1", "TAG2", "TAG3"])
        .last(hours=4)
        .interpolated(interval="10m")
        .to_dataframe()
    )

    # Pivot to wide format
    df = (
        client.query(["TAG1", "TAG2", "TAG3"])
        .time_range("*-2h", "*")
        .interpolated(interval="10m")
        .pivot()
        .to_dataframe()
    )

Summary Statistics¶

from pipolars import PIClient, SummaryType

with PIClient("my-pi-server") as client:
    # Overall summary
    df = (
        client.query("SINUSOID")
        .last(days=7)
        .summary(
            SummaryType.AVERAGE,
            SummaryType.MINIMUM,
            SummaryType.MAXIMUM,
            SummaryType.STD_DEV
        )
        .to_dataframe()
    )

Lazy Evaluation¶

import polars as pl

with PIClient("my-pi-server") as client:
    # Get LazyFrame for deferred execution
    lf = (
        client.query("SINUSOID")
        .last(days=30)
        .recorded()
        .to_lazy_frame()
    )

    # Build complex query
    result = (
        lf.filter(pl.col("value") > 50)
        .with_columns(
            pl.col("value").rolling_mean(window_size=100).alias("rolling")
        )
        .collect()  # Execute
    )

Method Chaining Patterns¶

with PIClient("my-pi-server") as client:
    # All options at once
    df = (
        client.query(["TAG1", "TAG2"])
        .time_range("*-1d", "*")
        .interpolated(interval="30m")
        .with_quality()
        .pivot()
        .limit(1000)
        .to_dataframe()
    )

PIQuery¶

PIQuery Class¶

QueryOptions Class¶

QueryType Enum¶

Usage Examples¶

Basic Query Building¶

Interpolated Values¶

Multi-Tag Queries¶

Summary Statistics¶

Lazy Evaluation¶

Method Chaining Patterns¶

See Also¶