# OSIRIS Examples

This directory contains examples demonstrating various features of OSIRIS.

## Prerequisites

Before running the examples, make sure HeroDB is running:

```bash
cd /path/to/herodb
cargo run --release -- --dir ./data --admin-secret mysecret --port 6379
```

## Running Examples

### Basic Usage

Demonstrates core OSIRIS functionality with Notes and Events:

```bash
cargo run --example basic_usage
```

**What it shows:**
- Creating objects with the derive macro
- Storing objects in HeroDB
- Querying by indexed fields
- Retrieving objects by ID
- Auto-generated index keys
- Cleanup/deletion

### Custom Object

Shows how to create your own custom object types:

```bash
cargo run --example custom_object
```

**What it shows:**
- Defining custom structs with `#[derive(DeriveObject)]`
- Using enums in indexed fields
- Builder pattern for object construction
- Querying by various indexed fields
- Updating objects
- Tag-based organization

## Example Structure

Each example follows this pattern:

1. **Setup** - Connect to HeroDB
2. **Create** - Build objects using builder pattern
3. **Store** - Save objects to HeroDB
4. **Query** - Search by indexed fields
5. **Retrieve** - Get objects by ID
6. **Update** - Modify and re-store objects (where applicable)
7. **Cleanup** - Delete test data

## Key Concepts Demonstrated

### Derive Macro

All examples use the `#[derive(DeriveObject)]` macro:

```rust
#[derive(Debug, Clone, Serialize, Deserialize, DeriveObject)]
pub struct MyObject {
    pub base_data: BaseData,
    
    #[index]
    pub indexed_field: String,
    
    pub non_indexed_field: String,
}
```

### Indexed Fields

Fields marked with `#[index]` are automatically indexed:

- `Option<T>` - Indexed if Some
- `BTreeMap<String, String>` - Each key-value pair indexed
- `OffsetDateTime` - Indexed as date string
- Enums - Indexed using Debug format
- Other types - Indexed using Debug format

### Querying

Query by any indexed field:

```rust
// Query by exact match
let ids = store.get_ids_by_index("namespace", "field_name", "value").await?;

// Query tags (BTreeMap fields)
let ids = store.get_ids_by_index("namespace", "tags:tag", "key=value").await?;
```

### Builder Pattern

All objects support fluent builder pattern:

```rust
let obj = MyObject::new("namespace".to_string())
    .set_field1("value1")
    .set_field2("value2")
    .add_tag("key", "value");
```

## Troubleshooting

### Connection Refused

Make sure HeroDB is running on port 6379:

```bash
redis-cli -p 6379 PING
```

### Database Not Found

The examples use different database IDs:
- `basic_usage` - DB 1
- `custom_object` - DB 2

Make sure these databases are accessible in HeroDB.

### Compilation Errors

Ensure you have the latest dependencies:

```bash
cargo clean
cargo build --examples
```

## Next Steps

After running the examples:

1. Read the [Architecture Documentation](../docs/ARCHITECTURE.md)
2. Learn about the [Derive Macro](../docs/DERIVE_MACRO.md)
3. Check out the [Quick Start Guide](../QUICKSTART.md)
4. Explore the [source code](../src/objects/) for Note and Event implementations

## Creating Your Own Objects

Use the `custom_object` example as a template:

1. Define your struct with `base_data: BaseData`
2. Add `#[derive(DeriveObject)]`
3. Mark fields with `#[index]` for automatic indexing
4. Implement builder methods for convenience
5. Use `GenericStore` to store and query

Happy coding! 🚀