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[source]¶

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()[source]¶

Connect to the PI Server.

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

disconnect()[source]¶

Disconnect from the PI Server.

Snapshot Methods

snapshot(tag)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

Check if a tag exists.

Parameters:: tag (str) – PI Point name
Returns:: True if the tag exists
Return type:: bool

tag_info(tag)[source]¶

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)[source]¶

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)[source]¶

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()[source]¶

Get cache statistics.

Returns:: Dictionary with cache stats
Return type:: dict[str, Any]

clear_cache()[source]¶

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)[source]¶

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()[source]¶

Connect to the PI Server.

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

disconnect()[source]¶

Disconnect from the PI Server.

__enter__()[source]¶

Context manager entry.

__exit__(exc_type, exc_val, exc_tb)[source]¶

Context manager exit.

query(tags)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

Check if a tag exists.

Parameters:: tag (str) – PI Point name
Returns:: True if the tag exists
Return type:: bool

tag_info(tag)[source]¶

Get metadata for a tag.

Parameters:: tag (str) – PI Point name
Returns:: Dictionary with tag metadata
Return type:: dict[str, Any]

cache_stats()[source]¶

Get cache statistics.

Returns:: Dictionary with cache stats
Return type:: dict[str, Any]

clear_cache()[source]¶

Clear all cached data.

last(tags, hours=0, days=0, minutes=0, **kwargs)[source]¶

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)[source]¶

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", "*")

PIClient¶

PIClient Class¶

Usage Examples¶

Basic Connection¶

Historical Data Retrieval¶

Summary Statistics¶

Configuration¶

See Also¶