# Examples - DSOL

This directory contains practical usage examples for various DSOL components.

## Running Examples

### Option 1: Run from Project Root (Recommended)

```bash
cd /home/neil/Documents/DSOL
python examples/structured_store_usage.py
```

### Option 2: Run as Module

```bash
cd /home/neil/Documents/DSOL
python -m examples.structured_store_usage
```

### Option 3: Install in Development Mode

```bash
# Install the project in editable mode
pip install -e .

# Now you can run from anywhere
python examples/structured_store_usage.py
```

## Prerequisites

### 1. Database Setup

Make sure PostgreSQL is running:

```bash
# Using Docker
docker start postgres

# Or start the full stack
docker-compose up -d postgres
```

### 2. Environment Variables

```bash
# Set database URL
export DATABASE_URL="postgresql+asyncpg://dsol_user:dsol_password@localhost:5432/dsol"
```

### 3. Run Database Migrations

```bash
# Apply migrations
alembic upgrade head
```

## Available Examples

### `structured_store_usage.py`

Demonstrates StructuredStore and QueryHelper usage:

1. **Basic Storage** - Store extracted records
2. **Exact Field Query** - Fast lookups using GIN indexes
3. **JSONB Containment** - Complex JSON queries
4. **Sheet Filtering** - Filter by sheet name
5. **Batch Storage** - Handle large datasets (1200+ records)
6. **Idempotent Retry** - ON CONFLICT handling

**Run it:**
```bash
python examples/structured_store_usage.py
```

## Troubleshooting

### ModuleNotFoundError: No module named 'src'

**Solution:** Run from project root:
```bash
cd /home/neil/Documents/DSOL
python examples/structured_store_usage.py
```

### Connection Refused to Database

**Solution:** Start PostgreSQL:
```bash
docker-compose up -d postgres
```

### Table 'extracted_records' does not exist

**Solution:** Run migrations:
```bash
alembic upgrade head
```

### Import Errors

**Solution:** Install dependencies:
```bash
pip install -r requirements.txt
# Or if using uv:
uv pip install -r requirements.txt
```

## Writing New Examples

When creating new examples:

1. Add the path setup at the top:
```python
import sys
from pathlib import Path

# Add project root to Python path
project_root = Path(__file__).parent.parent
sys.path.insert(0, str(project_root))
```

2. Include clear docstrings with run instructions

3. Use async/await for database operations

4. Add error handling and logging

5. Document prerequisites and setup steps

## Questions?

See the main project README or integration guide:
- `README.md` - Project overview
- `docs/integration-guide-structured-store.md` - Integration guide
