PIClient - PIPolars 0.1.0 documentation

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

# PIClient

The `PIClient` class is the main entry point for interacting with the PI System. It provides methods for querying PI Points, extracting data, and managing connections.

## PIClient Class

class pipolars.PIClient

  Bases: `object`

  Main client for extracting PI System data as Polars DataFrames.

  This is the primary interface for the PIPolars library. It provides a high-level API for querying PI Points, AF Attributes, and Event Frames, returning data as Polars DataFrames.

  Example

      >>> # Connect to PI Server
      >>> with PIClient("my-pi-server") as client:
      ...     # Get recorded values as DataFrame
      ...     df = client.recorded_values("SINUSOID", start="*-1d", end="*")
      ...     print(df)
      ...
      ...     # Get multiple tags at once
      ...     df = client.recorded_values(
      ...         ["TAG1", "TAG2", "TAG3"],
      ...         start="*-1h",
      ...         end="*"
      ...     )
      ...
      ...     # Get summary statistics
      ...     summaries = client.summaries(
      ...         "SINUSOID",
      ...         start="*-7d",
      ...         end="*",
      ...         summary_types=[SummaryType.AVERAGE, SummaryType.MAXIMUM]
      ...     )

      >>> # Using configuration
      >>> config = PIConfig(
      ...     server=PIServerConfig(host="my-pi-server"),
      ...     cache=CacheConfig(backend=CacheBackend.SQLITE),
      ... )
      >>> client = PIClient(config=config)

  Connection Methods

  connect()

    Connect to the PI Server.

    Returns:

      Self for method chaining

    Return type:

      PIClient

  disconnect()

    Disconnect from the PI Server.

  Snapshot Methods

  snapshot(tag)

    Get the current snapshot value for a tag.

    Parameters:

      tag (str) – PI Point name

    Returns:

      DataFrame with single row containing current value

    Return type:

      DataFrame

  snapshots(tags)

    Get current snapshot values for multiple tags.

    Parameters:

      tags (list[str]) – List of PI Point names

    Returns:

      DataFrame with current values for all tags

    Return type:

      DataFrame

  Historical Data Methods

  recorded_values(tags, start, end, max_count=0, include_quality=False, pivot=False)

    Get recorded values for one or more tags.

    Parameters:

      - tags (str | list[str]) – Single tag or list of tags

      - start (PITimestamp) – Start time

      - end (PITimestamp) – End time

      - max_count (int) – Maximum values per tag (0 = no limit)

      - include_quality (bool) – Include quality column

      - pivot (bool) – Pivot to wide format (tags as columns)

    Returns:

      DataFrame with recorded values

    Return type:

      pl.DataFrame

  interpolated_values(tags, start, end, interval='1h', include_quality=False, pivot=False)

    Get interpolated values at regular intervals.

    Parameters:

      - tags (str | list[str]) – Single tag or list of tags

      - start (PITimestamp) – Start time

      - end (PITimestamp) – End time

      - interval (str) – Time interval (e.g., “1h”, “15m”, “1d”)

      - include_quality (bool) – Include quality column

      - pivot (bool) – Pivot to wide format

    Returns:

      DataFrame with interpolated values

    Return type:

      pl.DataFrame

  plot_values(tag, start, end, intervals=640, include_quality=False)

    Get values optimized for plotting.

    Parameters:

      - tag (str) – PI Point name

      - start (PITimestamp) – Start time

      - end (PITimestamp) – End time

      - intervals (int) – Number of intervals

      - include_quality (bool) – Include quality column

    Returns:

      DataFrame with plot-optimized values

    Return type:

      pl.DataFrame

  Summary Methods

  summary(tags, start, end, summary_types=SummaryType.AVERAGE)

    Get summary statistics for one or more tags.

    Parameters:

      - tags (str | list[str]) – Single tag or list of tags

      - start (PITimestamp) – Start time

      - end (PITimestamp) – End time

      - summary_types (SummaryType | list[SummaryType]) – Summary type(s) to calculate

    Returns:

      DataFrame with summary statistics

    Return type:

      pl.DataFrame

  summaries(tag, start, end, interval, summary_types=SummaryType.AVERAGE)

    Get summary statistics over multiple intervals.

    Parameters:

      - tag (str) – PI Point name

      - start (PITimestamp) – Start time

      - end (PITimestamp) – End time

      - interval (str) – Interval for each summary

      - summary_types (SummaryType | list[SummaryType]) – Summary type(s) to calculate

    Returns:

      DataFrame with time-series summary statistics

    Return type:

      pl.DataFrame

  Query Builder

  query(tags)

    Create a query builder for the specified tags.

    Parameters:

      tags (str | list[str]) – Single tag or list of tags to query

    Returns:

      PIQuery builder for method chaining

    Return type:

      PIQuery

    Example

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

  Tag Operations

  search_tags(pattern, max_results=1000)

    Search for PI Points matching a pattern.

    Parameters:

      - pattern (str) – Search pattern (supports wildcards)

      - max_results (int) – Maximum results

    Returns:

      List of matching tag names

    Return type:

      list[str]

  tag_exists(tag)

    Check if a tag exists.

    Parameters:

      tag (str) – PI Point name

    Returns:

      True if the tag exists

    Return type:

      bool

  tag_info(tag)

    Get metadata for a tag.

    Parameters:

      tag (str) – PI Point name

    Returns:

      Dictionary with tag metadata

    Return type:

      dict[str, Any]

  Convenience Methods

  last(tags, hours=0, days=0, minutes=0, **kwargs)

    Get recorded values for the last N hours/days/minutes.

    Parameters:

      - tags (str | list[str]) – Single tag or list of tags

      - hours (int) – Number of hours

      - days (int) – Number of days

      - minutes (int) – Number of minutes

      - **kwargs (Any) – Additional arguments for recorded_values

    Returns:

      DataFrame with recorded values

    Return type:

      DataFrame

    Example

        >>> df = client.last("SINUSOID", hours=24)
        >>> df = client.last(["TAG1", "TAG2"], days=7)

  today(tags, **kwargs)

    Get recorded values for today.

    Parameters:

      - tags (str | list[str]) – Single tag or list of tags

      - **kwargs (Any) – Additional arguments for recorded_values

    Returns:

      DataFrame with today’s values

    Return type:

      DataFrame

  Cache Management

  cache_stats()

    Get cache statistics.

    Returns:

      Dictionary with cache stats

    Return type:

      dict[str, Any]

  clear_cache()

    Clear all cached data.

  Properties

  property config: PIConfig

    Get the client configuration.

  property is_connected: bool

    Check if connected to PI Server.

  property server_name: str | None

    Get the connected server name.

  __init__(server=None, config=None, enable_cache=True)

    Initialize the PI client.

    Parameters:

      - server (str | PIServerConfig | None) – PI Server hostname or configuration

      - config (PIConfig | None) – Full PIPolars configuration

      - enable_cache (bool) – Whether to enable caching

  property config: PIConfig

    Get the client configuration.

  property is_connected: bool

    Check if connected to PI Server.

  property server_name: str | None

    Get the connected server name.

  connect()

    Connect to the PI Server.

    Returns:

      Self for method chaining

    Return type:

      PIClient

  disconnect()

    Disconnect from the PI Server.

  __enter__()

    Context manager entry.

  __exit__(exc_type, exc_val, exc_tb)

    Context manager exit.

  query(tags)

    Create a query builder for the specified tags.

    Parameters:

      tags (str | list[str]) – Single tag or list of tags to query

    Returns:

      PIQuery builder for method chaining

    Return type:

      PIQuery

    Example

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

  snapshot(tag)

    Get the current snapshot value for a tag.

    Parameters:

      tag (str) – PI Point name

    Returns:

      DataFrame with single row containing current value

    Return type:

      DataFrame

  snapshots(tags)

    Get current snapshot values for multiple tags.

    Parameters:

      tags (list[str]) – List of PI Point names

    Returns:

      DataFrame with current values for all tags

    Return type:

      DataFrame

  recorded_values(tags, start, end, max_count=0, include_quality=False, pivot=False)

    Get recorded values for one or more tags.

    Parameters:

      - tags (str | list[str]) – Single tag or list of tags

      - start (PITimestamp) – Start time

      - end (PITimestamp) – End time

      - max_count (int) – Maximum values per tag (0 = no limit)

      - include_quality (bool) – Include quality column

      - pivot (bool) – Pivot to wide format (tags as columns)

    Returns:

      DataFrame with recorded values

    Return type:

      pl.DataFrame

  interpolated_values(tags, start, end, interval='1h', include_quality=False, pivot=False)

    Get interpolated values at regular intervals.

    Parameters:

      - tags (str | list[str]) – Single tag or list of tags

      - start (PITimestamp) – Start time

      - end (PITimestamp) – End time

      - interval (str) – Time interval (e.g., “1h”, “15m”, “1d”)

      - include_quality (bool) – Include quality column

      - pivot (bool) – Pivot to wide format

    Returns:

      DataFrame with interpolated values

    Return type:

      pl.DataFrame

  plot_values(tag, start, end, intervals=640, include_quality=False)

    Get values optimized for plotting.

    Parameters:

      - tag (str) – PI Point name

      - start (PITimestamp) – Start time

      - end (PITimestamp) – End time

      - intervals (int) – Number of intervals

      - include_quality (bool) – Include quality column

    Returns:

      DataFrame with plot-optimized values

    Return type:

      pl.DataFrame

  summary(tags, start, end, summary_types=SummaryType.AVERAGE)

    Get summary statistics for one or more tags.

    Parameters:

      - tags (str | list[str]) – Single tag or list of tags

      - start (PITimestamp) – Start time

      - end (PITimestamp) – End time

      - summary_types (SummaryType | list[SummaryType]) – Summary type(s) to calculate

    Returns:

      DataFrame with summary statistics

    Return type:

      pl.DataFrame

  summaries(tag, start, end, interval, summary_types=SummaryType.AVERAGE)

    Get summary statistics over multiple intervals.

    Parameters:

      - tag (str) – PI Point name

      - start (PITimestamp) – Start time

      - end (PITimestamp) – End time

      - interval (str) – Interval for each summary

      - summary_types (SummaryType | list[SummaryType]) – Summary type(s) to calculate

    Returns:

      DataFrame with time-series summary statistics

    Return type:

      pl.DataFrame

  search_tags(pattern, max_results=1000)

    Search for PI Points matching a pattern.

    Parameters:

      - pattern (str) – Search pattern (supports wildcards)

      - max_results (int) – Maximum results

    Returns:

      List of matching tag names

    Return type:

      list[str]

  tag_exists(tag)

    Check if a tag exists.

    Parameters:

      tag (str) – PI Point name

    Returns:

      True if the tag exists

    Return type:

      bool

  tag_info(tag)

    Get metadata for a tag.

    Parameters:

      tag (str) – PI Point name

    Returns:

      Dictionary with tag metadata

    Return type:

      dict[str, Any]

  cache_stats()

    Get cache statistics.

    Returns:

      Dictionary with cache stats

    Return type:

      dict[str, Any]

  clear_cache()

    Clear all cached data.

  last(tags, hours=0, days=0, minutes=0, **kwargs)

    Get recorded values for the last N hours/days/minutes.

    Parameters:

      - tags (str | list[str]) – Single tag or list of tags

      - hours (int) – Number of hours

      - days (int) – Number of days

      - minutes (int) – Number of minutes

      - **kwargs (Any) – Additional arguments for recorded_values

    Returns:

      DataFrame with recorded values

    Return type:

      DataFrame

    Example

        >>> df = client.last("SINUSOID", hours=24)
        >>> df = client.last(["TAG1", "TAG2"], days=7)

  today(tags, **kwargs)

    Get recorded values for today.

    Parameters:

      - tags (str | list[str]) – Single tag or list of tags

      - **kwargs (Any) – Additional arguments for recorded_values

    Returns:

      DataFrame with today’s values

    Return type:

      DataFrame

## Usage Examples

### Basic Connection

    from pipolars import PIClient

    # Using context manager (recommended)
    with PIClient("my-pi-server") as client:
        df = client.snapshot("SINUSOID")
        print(df)

    # Manual connection management
    client = PIClient("my-pi-server")
    client.connect()
    try:
        df = client.snapshot("SINUSOID")
    finally:
        client.disconnect()

### Historical Data Retrieval

    with PIClient("my-pi-server") as client:
        # Recorded values
        df = client.recorded_values(
            "SINUSOID",
            start="*-1d",
            end="*",
            include_quality=True
        )

        # Interpolated values
        df = client.interpolated_values(
            ["TAG1", "TAG2"],
            start="*-1d",
            end="*",
            interval="1h",
            pivot=True
        )

### Summary Statistics

    from pipolars import PIClient, SummaryType

    with PIClient("my-pi-server") as client:
        # Overall summary
        df = client.summary(
            "SINUSOID",
            start="*-7d",
            end="*",
            summary_types=[
                SummaryType.AVERAGE,
                SummaryType.MINIMUM,
                SummaryType.MAXIMUM
            ]
        )

        # Interval summaries
        df = client.summaries(
            "SINUSOID",
            start="*-1d",
            end="*",
            interval="1h",
            summary_types=SummaryType.AVERAGE
        )

### Configuration

    from pipolars import PIClient, PIConfig
    from pipolars.core.config import PIServerConfig, CacheConfig, CacheBackend

    config = PIConfig(
        server=PIServerConfig(
            host="my-pi-server",
            timeout=60
        ),
        cache=CacheConfig(
            backend=CacheBackend.SQLITE
        )
    )

    with PIClient(config=config) as client:
        df = client.recorded_values("SINUSOID", "*-1d", "*")

## See Also

- PIQuery - PIQuery fluent query builder

- Configuration - Configuration options

- Connecting to PI Server - Connection guide

- Querying Data - Querying guide