pipolars.PIQuery - PIPolars 0.1.0 documentation

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

# pipolars.PIQuery

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

  __init__(client, tags)

    Initialize the query builder.

    Parameters:

      - client (PIClient) – PIClient instance

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

  Methods

  `__init__`(client, tags) | Initialize the query builder.
  `boundary`(boundary_type) | Set the boundary type for recorded values.
  `filter`(expression) | Set a filter expression.
  `interpolated`([interval]) | Query for interpolated values.
  `last`([hours, days, minutes, seconds]) | Set time range to the last N time units.
  `limit`(max_count) | Limit the number of values returned.
  `pivot`() | Pivot results to wide format (tags as columns).
  `plot`([intervals]) | Query for plot-optimized values.
  `recorded`([max_count]) | Query for recorded values.
  `snapshot`() | Query for current snapshot values.
  `summary`(*summary_types) | Query for summary statistics.
  `this_month`() | Set time range to this month.
  `this_week`() | Set time range to this week.
  `time_range`(start, end) | Set the time range for the query.
  `to_dataframe`() | Execute the query and return a Polars DataFrame.
  `to_lazy_frame`() | Execute the query and return a Polars LazyFrame.
  `today`() | Set time range to today.
  `with_quality`() | Include quality information in results.
  `without_quality`() | Exclude quality information from results.
  `yesterday`() | Set time range to yesterday.

  __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.