Metadata-Version: 2.5
Name: glacierdb
Version: 0.1.0
Summary: Python driver for glacierdb (og-core)
Project-URL: Homepage, https://openglacier.org
Project-URL: Source, https://github.com/openglacier/glacierdb-python
Author: OpenGlacier contributors
License: MIT
License-File: LICENSE
Keywords: csv,database,glacierdb,og-core,pandas
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: cryptography>=42.0
Requires-Dist: msgpack>=1.0
Provides-Extra: dev
Requires-Dist: pandas>=2.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: pandas
Requires-Dist: pandas>=2.0; extra == 'pandas'
Description-Content-Type: text/markdown

# glacierdb

Premier driver Python pour le daemon `ogd`, sans modification de `og-core`.

Il utilise directement le protocole officiel TCP/NDJSON v1 : une requête JSON
par ligne, une réponse JSON par ligne.

## Installation locale

```bash
cd glacierdb
python -m pip install -e '.[pandas]'
```

Démarrer OG dans un autre terminal :

```bash
cargo run --bin ogd
```

## Requêtes

```python
import glacierdb

with glacierdb.connect("127.0.0.1:7878") as db:
    result = db.execute("from users | where age >= 18")
    print(result.documents)
    print(result.statistics)

    frame = db.query_df("from users")
```

## Charger un CSV par chunks

```python
import glacierdb

with glacierdb.connect() as db:
    result = db.load_csv(
        "users",
        "users.csv",
        chunk_size=10_000,
    )

print(result)
```

Alias pratique :

```python
result = db.load("users", "users.csv", chunk_size=10_000)
```

## Charger un DataFrame Pandas

```python
import pandas as pd
import glacierdb

frame = pd.DataFrame([
    {"name": "Ada", "age": 36},
    {"name": "Grace", "age": 85},
])

with glacierdb.connect() as db:
    result = db.load("users", frame, chunk_size=1_000)
```

`None`, `pd.NA` et `NaN` sont convertis en `null`. Les dates sont converties
en ISO 8601.

## Charger un itérateur

```python
def documents():
    yield {"name": "Ada"}
    yield {"name": "Grace"}

result = db.load("users", documents(), chunk_size=500)
```

## Limite de cette v0.1

Le protocole OG v1 accepte une requête à la fois et la syntaxe actuelle de
`insert` insère un document. Le driver effectue donc un aller-retour par ligne.
Le `chunk_size` borne la mémoire de lecture CSV/Pandas, mais ne constitue pas
encore un insert réseau groupé. Un futur protocole de batch pourrait accélérer
le chargement sans changer cette API Python.
