# Quickstart

Dieser Guide zeigt die grundlegende Verwendung von Questra Data.

## Authentifizierung

Zunächst benötigen Sie einen authentifizierten Client:

```python
from questra_authentication import QuestraAuthentication

auth_client = QuestraAuthentication(
    url="https://authentik.dev.example.com",
    username="ServiceUser",
    password="secret_password"
)
```

!!! info "questra-authentication"
    Questra Data verwendet `questra-authentication` für OAuth2-Authentifizierung. Stellen Sie sicher, dass das Paket installiert ist.

## High-Level API (empfohlen)

Die High-Level API bietet eine einfache, intuitive Schnittstelle:

```python
from questra_data import QuestraData
from datetime import datetime

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

### Inventory Items auflisten

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

for item in items:
    print(f"ID: {item['_id']}, Nummer: {item['stromzaehlernummer']}")
```

### Zeitreihen-Daten laden

```python
# Zeitreihen-Werte laden (kombiniert automatisch Inventory + TimeSeries!)
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)
)

# Ergebnis ist ein Dict: {item_id: {"item": {...}, "values": [...]}}
for item_id, data in result.items():
    print(f"Stromzähler: {data['item']['stromzaehlernummer']}")
    print(f"Anzahl Werte: {len(data['values'])}")

    # Erste 5 Werte anzeigen
    for value in data['values'][:5]:
        print(f"  {value.time}: {value.value} ({value.quality})")
```

### Items erstellen

```python
# Neues Item erstellen
new_item = client.create(
    inventory_name="Stromzaehler",
    namespace_name="Energie",
    properties={
        "stromzaehlernummer": "SZ-99999",
        "hersteller": "Test GmbH",
        "baujahr": 2025
    }
)

print(f"Neues Item erstellt: {new_item['_id']}")
```

### Items aktualisieren

```python
# Item aktualisieren
updated = client.update(
    inventory_name="Stromzaehler",
    namespace_name="Energie",
    item_id="630...",
    properties={
        "hersteller": "Neue Firma GmbH"
    }
)
```

### Items löschen

```python
# Item löschen
client.delete(
    inventory_name="Stromzaehler",
    namespace_name="Energie",
    item_id="630..."
)
```

## Mit pandas (optional)

Falls pandas installiert ist, können Sie Ergebnisse zu DataFrames konvertieren:

```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(include_metadata=True)  # Item-Felder als Spalten

# DataFrame:
#                        value  quality  item_id  item_stromzaehlernummer
# time
# 2025-01-01 12:00:00   100.5    VALID   630...   SZ-12345
# 2025-01-02 12:00:00   105.2    VALID   630...   SZ-12345

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

```python
# Inventory Items als DataFrame
items = client.list(
    inventory_name="Stromzaehler",
    namespace_name="Energie",
    properties=["_id", "stromzaehlernummer", "hersteller"]
)

# Optional: zu DataFrame konvertieren
df_items = items.to_df()
print(df_items.head())
```

## Inventory & Namespace erstellen

```python
# Namespace erstellen
namespace_result = client.create_namespace(
    name="TestNamespace",
    description="Mein Test Namespace"
)
print(f"Namespace erstellt: {namespace_result.name} (ID: {namespace_result.id})")

# Inventory erstellen mit spezialisierten Property-Klassen
from questra_data import (
    StringProperty,
    IntProperty,
    ConflictAction
)

properties = [
    StringProperty(
        propertyName="Name",
        maxLength=200,
        isRequired=True,
        isUnique=True
    ),
    IntProperty(
        propertyName="Age",
        isRequired=False
    )
]

inventory_result = client.create_inventory(
    name="TestInventory",
    properties=properties,
    if_exists=ConflictAction.IGNORE
)
print(f"Inventory erstellt: {inventory_result.name} (ID: {inventory_result.id})")
```

## Low-Level API

Für fortgeschrittene Operationen können Sie auf die Low-Level API zugreifen:

```python
# Zugriff auf Low-Level Client
lowlevel = client.lowlevel

# Direkte GraphQL Query
result = lowlevel.execute_raw("""
    query {
        _timeZones(first: 5) {
            nodes {
                name
                baseUtcOffset
            }
        }
    }
""")

for tz in result["_timeZones"]["nodes"]:
    print(f"{tz['name']}: UTC{tz['baseUtcOffset']}")
```

## Nächste Schritte

- [API-Übersicht](api-overview.md) - High-Level vs Low-Level API im Detail
- [API Referenz](../api/index.md) - Vollständige API-Dokumentation
- [Best Practices](../guides/best-practices.md) - Empfehlungen für Production
- [TimeSeries Guide](../guides/timeseries.md) - Arbeiten mit Zeitreihen-Daten
