osiris/examples

OSIRIS Examples

This directory contains examples demonstrating various features of OSIRIS.

Prerequisites

Before running the examples, make sure HeroDB is running:

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:

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:

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:

#[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:

// 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:

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:

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:

cargo clean
cargo build --examples

Next Steps

After running the examples:

1. Read the Architecture Documentation
2. Learn about the Derive Macro
3. Check out the Quick Start Guide
4. Explore the source code 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! 🚀