158 lines
3.4 KiB
Markdown
158 lines
3.4 KiB
Markdown
# 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! 🚀
|