# Questra Data

Python Client für Questra Dynamic Objects (GraphQL + REST API).

## Überblick

Questra Data ist ein umfassender Python-Client für die Questra Dynamic Objects Platform. Der Client bietet zwei komplementäre APIs:

- **High-Level API** (`QuestraData`): Vereinfachte, benutzerfreundliche Schnittstelle für die häufigsten Anwendungsfälle
- **Low-Level API** (`QuestraDataCore`): Direkter, flexibler Zugriff auf GraphQL und REST Endpoints

## Features

- **Typsichere Dataclasses**: Vollständige IDE-Unterstützung für Inventory-Erstellung
- **Zeitreihen-Verwaltung**: Effiziente Verwaltung von TimeSeries-Daten
- **Inventory-Operationen**: CRUD-Operationen für Dynamic Objects
- **Optional: pandas Integration**: DataFrames für Zeitreihen- und Inventory-Daten
- **GraphQL & REST**: Unterstützung beider API-Paradigmen
- **OAuth2 Authentifizierung**: Nahtlose Integration mit `questra-authentication`

## Schnellstart

```python
from questra_authentication import QuestraAuthentication
from questra_data import QuestraData
from datetime import datetime

# Authentifizierung
auth_client = QuestraAuthentication(
    url="https://authentik.dev.example.com",
    username="ServiceUser",
    password="secret"
)

# Client initialisieren
client = QuestraData(
    graphql_url="https://dev.example.com/dynamic-objects/graphql",
    auth_client=auth_client
)

# Inventory Items auflisten
items = client.list(
    inventory_name="Stromzaehler",
    namespace_name="Energie",
    properties=["_id", "stromzaehlernummer", "hersteller"],
    limit=10
)

# Zeitreihen-Werte laden
result = client.list_timeseries_values(
    inventory_name="Stromzaehler",
    namespace_name="Energie",
    timeseries_property="messwerte_Energie",
    from_time=datetime(2025, 1, 1),
    to_time=datetime(2025, 12, 31)
)
```

## Installation

```bash
# Basis-Installation
pip install questra-data

# Mit pandas-Unterstützung (empfohlen für Data Science)
pip install questra-data[pandas]
```

Siehe [Installation](getting-started/installation.md) für detaillierte Installationsanweisungen.

## Warum Questra Data?

### Einfach zu verwenden

Die High-Level API abstrahiert die Komplexität von GraphQL und REST und bietet eine intuitive Schnittstelle:

```python
# Eine Zeile Code für komplexe Operationen
items = client.list("Stromzaehler", "Energie", properties=["_id", "name"])
```

### Typsicher

Vollständige Unterstützung für Python Type Hints und IDE-Autovervollständigung:

```python
from questra_data import StringProperty

property = StringProperty(
    propertyName="Name",
    maxLength=200,
    isRequired=True
)
```

### Flexibel

Wählen Sie zwischen High-Level und Low-Level API je nach Bedarf:

```python
# High-Level: Einfach und schnell
items = client.list("Stromzaehler", "Energie")

# Low-Level: Volle Kontrolle
result = client.lowlevel.execute_raw("""
    query { ... }
""")
```

### Data Science Ready

Optionale pandas-Integration für nahtlose Datenanalyse:

```python
# Zeitreihen als DataFrame
result = client.list_timeseries_values(
    inventory_name="Stromzaehler",
    namespace_name="Energie",
    timeseries_property="messwerte_Energie",
    from_time=datetime(2025, 1, 1),
    to_time=datetime(2025, 12, 31)
)

# Optional: zu DataFrame konvertieren
df = result.to_df()

# Direkt weiterverarbeiten
df.resample('1D').mean()
df.plot()
```

## Dokumentation

<div class="grid cards" markdown>

-   :material-rocket-launch:{ .lg .middle } **Erste Schritte**

    ---

    Installation, Quickstart und API-Übersicht

    [:octicons-arrow-right-24: Los geht's](getting-started/installation.md)

-   :material-api:{ .lg .middle } **API Referenz**

    ---

    Vollständige Dokumentation aller Klassen und Methoden

    [:octicons-arrow-right-24: API erkunden](api/index.md)

-   :material-book-open-variant:{ .lg .middle } **Guides**

    ---

    Best Practices, Error Handling und fortgeschrittene Themen

    [:octicons-arrow-right-24: Guides lesen](guides/best-practices.md)

-   :material-github:{ .lg .middle } **Beispiele**

    ---

    Praktische Codebeispiele für häufige Anwendungsfälle

    [:octicons-arrow-right-24: Beispiele ansehen](https://dev.azure.com/seven2one/Seven2one.Questra/_git/S2O.PoC.Questra.Python.Packages?path=/questra-data)

</div>

## Requirements

- Python >= 3.10
- gql >= 3.5.0
- requests >= 2.31.0
- loguru >= 0.7.0
- questra-authentication >= 0.1.4

### Optional

- pandas >= 2.0.0 (für DataFrame-Unterstützung)

## License

Proprietär - Seven2one GmbH

---

**Hinweis**: Diese Dokumentation beschreibt die Funktionalität des Python Clients. Für allgemeine Informationen zur Questra Platform konsultieren Sie bitte die offizielle Questra Dokumentation.
