PIQuery - PIPolars 0.1.0 documentation

Skip to content
Back to top
View this page
Edit this page

# 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

  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)

    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)

    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()

    Set time range to today.

    Returns:

      Self for method chaining

    Return type:

      PIQuery

  yesterday()

    Set time range to yesterday.

    Returns:

      Self for method chaining

    Return type:

      PIQuery

  this_week()

    Set time range to this week.

    Returns:

      Self for method chaining

    Return type:

      PIQuery

  this_month()

    Set time range to this month.

    Returns:

      Self for method chaining

    Return type:

      PIQuery

  Query Type Methods

  recorded(max_count=0)

    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')

    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)

    Query for plot-optimized values.

    Parameters:

      intervals (int) – Number of intervals

    Returns:

      Self for method chaining

    Return type:

      PIQuery

  summary(*summary_types)

    Query for summary statistics.

    Parameters:

      *summary_types (SummaryType) – Summary types to calculate

    Returns:

      Self for method chaining

    Return type:

      PIQuery

  snapshot()

    Query for current snapshot values.

    Returns:

      Self for method chaining

    Return type:

      PIQuery

  Option Methods

  with_quality()

    Include quality information in results.

    Returns:

      Self for method chaining

    Return type:

      PIQuery

  without_quality()

    Exclude quality information from results.

    Returns:

      Self for method chaining

    Return type:

      PIQuery

  boundary(boundary_type)

    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)

    Set a filter expression.

    Parameters:

      expression (str) – PI filter expression

    Returns:

      Self for method chaining

    Return type:

      PIQuery

  pivot()

    Pivot results to wide format (tags as columns).

    Returns:

      Self for method chaining

    Return type:

      PIQuery

  limit(max_count)

    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()

    Execute the query and return a Polars DataFrame.

    Returns:

      DataFrame with query results

    Return type:

      DataFrame

  to_lazy_frame()

    Execute the query and return a Polars LazyFrame.

    Returns:

      LazyFrame for deferred execution

    Return type:

      LazyFrame

  __init__(client, tags)

    Initialize the query builder.

    Parameters:

      - client (PIClient) – PIClient instance

      - tags (list[str]) – List of tags to query

  time_range(start, end)

    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)

    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()

    Set time range to today.

    Returns:

      Self for method chaining

    Return type:

      PIQuery

  yesterday()

    Set time range to yesterday.

    Returns:

      Self for method chaining

    Return type:

      PIQuery

  this_week()

    Set time range to this week.

    Returns:

      Self for method chaining

    Return type:

      PIQuery

  this_month()

    Set time range to this month.

    Returns:

      Self for method chaining

    Return type:

      PIQuery

  recorded(max_count=0)

    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')

    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)

    Query for plot-optimized values.

    Parameters:

      intervals (int) – Number of intervals

    Returns:

      Self for method chaining

    Return type:

      PIQuery

  summary(*summary_types)

    Query for summary statistics.

    Parameters:

      *summary_types (SummaryType) – Summary types to calculate

    Returns:

      Self for method chaining

    Return type:

      PIQuery

  snapshot()

    Query for current snapshot values.

    Returns:

      Self for method chaining

    Return type:

      PIQuery

  with_quality()

    Include quality information in results.

    Returns:

      Self for method chaining

    Return type:

      PIQuery

  without_quality()

    Exclude quality information from results.

    Returns:

      Self for method chaining

    Return type:

      PIQuery

  boundary(boundary_type)

    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)

    Set a filter expression.

    Parameters:

      expression (str) – PI filter expression

    Returns:

      Self for method chaining

    Return type:

      PIQuery

  pivot()

    Pivot results to wide format (tags as columns).

    Returns:

      Self for method chaining

    Return type:

      PIQuery

  limit(max_count)

    Limit the number of values returned.

    Parameters:

      max_count (int) – Maximum values per tag

    Returns:

      Self for method chaining

    Return type:

      PIQuery

  to_dataframe()

    Execute the query and return a Polars DataFrame.

    Returns:

      DataFrame with query results

    Return type:

      DataFrame

  to_lazy_frame()

    Execute the query and return a Polars LazyFrame.

    Returns:

      LazyFrame for deferred execution

    Return type:

      LazyFrame

  __repr__()

    String representation of the query.

## QueryOptions Class

class pipolars.api.query.QueryOptions

  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

  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()
        )

## See Also

- PIClient - PIClient class

- Types - SummaryType and other enums

- Querying Data - Complete querying guide