User Guide - PIPolars 0.1.0 documentation

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

# User Guide

This guide provides comprehensive documentation on using PIPolars for PI System data extraction and analysis.

## Overview

PIPolars is designed around a layered architecture:

Layer | Purpose
--- | ---
API | User-facing interface (PIClient, PIQuery)
Connection | PI Server and AF Database connectivity
Extraction | Data retrieval from PI System
Transform | Data conversion to Polars DataFrames
Cache | Result caching for performance
Core | Types, configuration, and exceptions

## Typical Workflow

A typical PIPolars workflow:

1. Configure the client with server settings and optional caching

2. Connect to the PI Server (automatically or explicitly)

3. Query data using direct methods or the fluent query builder

4. Process the resulting Polars DataFrame

5. Disconnect (automatic with context manager)

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

    # 1. Configure
    config = PIConfig(
        server=PIServerConfig(host="my-pi-server"),
        cache=CacheConfig(backend=CacheBackend.SQLITE),
    )

    # 2. Connect
    with PIClient(config=config) as client:
        # 3. Query
        df = (
            client.query("SINUSOID")
            .last(hours=24)
            .interpolated(interval="15m")
            .to_dataframe()
        )

        # 4. Process
        result = df.filter(df["value"] > 50)
        print(result)

    # 5. Disconnect (automatic)

## Guide Contents

- Connecting to PI Server
  - Basic Connection
  - Manual Connection Management
  - Connection Properties
  - Server Configuration
  - Authentication
  - Using Environment Variables
  - Discovering Servers
  - Low-Level Connection
  - Connection Pooling
  - Error Handling
  - Next Steps
- Querying Data
  - Query Methods Overview
  - Direct Methods
  - Query Builder (Fluent API)
  - Convenience Methods
  - Tag Operations
  - Output Format Options
  - Next Steps
- Time Expressions
  - PI Time Expression Syntax
  - Using Time Expressions
  - The AFTime Class
  - Python datetime Objects
  - TimeRange Class
  - Interval Specifications
  - Best Practices
  - Error Handling
  - Next Steps
- Working with Polars DataFrames
  - Why Polars?
  - DataFrame Structure
  - Basic Operations
  - Transformations
  - Common Data Science Patterns
  - LazyFrame for Large Data
  - Converting to Other Formats
  - Performance Tips
  - Next Steps
- Caching
  - Overview
  - Enabling Caching
  - Cache Backends
  - Cache Management
  - Cache Key Generation
  - Environment Variables
  - Best Practices
  - Advanced: Custom Cache Backend
  - Troubleshooting
  - Next Steps
- Configuration
  - Configuration Classes
  - PIConfig
  - PIServerConfig
  - AFServerConfig
  - CacheConfig
  - QueryConfig
  - PolarsConfig
  - Configuration Files
  - Environment File (.env)
  - Configuration Precedence
  - Viewing Configuration
  - Validation
  - Complete Example
  - Next Steps
- Advanced Usage
  - Bulk Operations
  - Lazy Evaluation
  - Error Handling
  - Streaming Large Datasets
  - Custom Data Processing Pipeline
  - Logging and Monitoring
  - Connection Pooling Pattern
  - Working with AF Data
  - uv Script Dependencies
  - Integration with Other Libraries
  - Next Steps