first commit
This commit is contained in:
Timur Gordon
454
EXAMPLES.md
Normal file
454
EXAMPLES.md
Normal file
@@ -0,0 +1,454 @@
|
||||
# OSIRIS Examples
|
||||
|
||||
This document provides practical examples of using OSIRIS for various use cases.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. **Start HeroDB**:
|
||||
```bash
|
||||
cd /path/to/herodb
|
||||
cargo run --release -- --dir ./data --admin-secret mysecret --port 6379
|
||||
```
|
||||
|
||||
2. **Build OSIRIS**:
|
||||
```bash
|
||||
cd /path/to/osiris
|
||||
cargo build --release
|
||||
```
|
||||
|
||||
3. **Initialize OSIRIS**:
|
||||
```bash
|
||||
./target/release/osiris init --herodb redis://localhost:6379
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example 1: Personal Note Management
|
||||
|
||||
### Create a namespace for notes
|
||||
```bash
|
||||
./target/release/osiris ns create notes
|
||||
```
|
||||
|
||||
### Add notes with tags
|
||||
```bash
|
||||
# Create a note about Rust
|
||||
echo "Rust is a systems programming language focused on safety and performance." | \
|
||||
./target/release/osiris put notes/rust-intro - \
|
||||
--title "Introduction to Rust" \
|
||||
--tags topic=rust,level=beginner,type=tutorial \
|
||||
--mime text/plain
|
||||
|
||||
# Create a note about OSIRIS
|
||||
echo "OSIRIS is an object storage system built on HeroDB." | \
|
||||
./target/release/osiris put notes/osiris-overview - \
|
||||
--title "OSIRIS Overview" \
|
||||
--tags topic=osiris,level=intermediate,type=documentation \
|
||||
--mime text/plain
|
||||
|
||||
# Create a note from a file
|
||||
./target/release/osiris put notes/network-latency ./network-notes.md \
|
||||
--title "Network Latency Analysis" \
|
||||
--tags topic=networking,priority=high,type=analysis \
|
||||
--mime text/markdown
|
||||
```
|
||||
|
||||
### Search notes
|
||||
```bash
|
||||
# Search for notes about Rust
|
||||
./target/release/osiris find "rust" --ns notes
|
||||
|
||||
# Filter by tag
|
||||
./target/release/osiris find --ns notes --filter topic=rust
|
||||
|
||||
# Combine text search and filters
|
||||
./target/release/osiris find "performance" --ns notes --filter level=beginner
|
||||
|
||||
# Get more results
|
||||
./target/release/osiris find "programming" --ns notes --topk 20
|
||||
|
||||
# Output as JSON
|
||||
./target/release/osiris find "rust" --ns notes --json
|
||||
```
|
||||
|
||||
### Retrieve notes
|
||||
```bash
|
||||
# Get note as JSON (with metadata)
|
||||
./target/release/osiris get notes/rust-intro
|
||||
|
||||
# Get raw content only
|
||||
./target/release/osiris get notes/rust-intro --raw
|
||||
|
||||
# Save to file
|
||||
./target/release/osiris get notes/rust-intro --raw --output /tmp/rust-intro.txt
|
||||
```
|
||||
|
||||
### Delete notes
|
||||
```bash
|
||||
./target/release/osiris del notes/rust-intro
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example 2: Calendar/Event Management
|
||||
|
||||
### Create a calendar namespace
|
||||
```bash
|
||||
./target/release/osiris ns create calendar
|
||||
```
|
||||
|
||||
### Add events
|
||||
```bash
|
||||
# Add a meeting
|
||||
echo '{"title":"Team Standup","when":"2025-10-20T10:00:00Z","attendees":["alice","bob"]}' | \
|
||||
./target/release/osiris put calendar/standup-2025-10-20 - \
|
||||
--title "Team Standup" \
|
||||
--tags type=meeting,team=eng,priority=high \
|
||||
--mime application/json
|
||||
|
||||
# Add a deadline
|
||||
echo '{"title":"Project Deadline","when":"2025-10-31T23:59:59Z","project":"osiris-mvp"}' | \
|
||||
./target/release/osiris put calendar/deadline-osiris - \
|
||||
--title "OSIRIS MVP Deadline" \
|
||||
--tags type=deadline,project=osiris,priority=critical \
|
||||
--mime application/json
|
||||
|
||||
# Add a reminder
|
||||
echo '{"title":"Code Review","when":"2025-10-21T14:00:00Z","pr":"#123"}' | \
|
||||
./target/release/osiris put calendar/review-pr123 - \
|
||||
--title "Code Review PR #123" \
|
||||
--tags type=reminder,team=eng \
|
||||
--mime application/json
|
||||
```
|
||||
|
||||
### Search events
|
||||
```bash
|
||||
# Find all meetings
|
||||
./target/release/osiris find --ns calendar --filter type=meeting
|
||||
|
||||
# Find high-priority items
|
||||
./target/release/osiris find --ns calendar --filter priority=high
|
||||
|
||||
# Search by text
|
||||
./target/release/osiris find "standup" --ns calendar
|
||||
|
||||
# Find project-specific events
|
||||
./target/release/osiris find --ns calendar --filter project=osiris
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example 3: Code Snippet Library
|
||||
|
||||
### Create a snippets namespace
|
||||
```bash
|
||||
./target/release/osiris ns create snippets
|
||||
```
|
||||
|
||||
### Add code snippets
|
||||
```bash
|
||||
# Rust snippet
|
||||
cat > /tmp/rust-error-handling.rs <<'EOF'
|
||||
use anyhow::Result;
|
||||
|
||||
fn main() -> Result<()> {
|
||||
let result = risky_operation()?;
|
||||
println!("Success: {}", result);
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn risky_operation() -> Result<String> {
|
||||
Ok("All good!".to_string())
|
||||
}
|
||||
EOF
|
||||
|
||||
./target/release/osiris put snippets/rust-error-handling /tmp/rust-error-handling.rs \
|
||||
--title "Rust Error Handling with anyhow" \
|
||||
--tags language=rust,topic=error-handling,pattern=result \
|
||||
--mime text/x-rust
|
||||
|
||||
# Python snippet
|
||||
cat > /tmp/python-async.py <<'EOF'
|
||||
import asyncio
|
||||
|
||||
async def fetch_data(url):
|
||||
await asyncio.sleep(1)
|
||||
return f"Data from {url}"
|
||||
|
||||
async def main():
|
||||
result = await fetch_data("https://example.com")
|
||||
print(result)
|
||||
|
||||
asyncio.run(main())
|
||||
EOF
|
||||
|
||||
./target/release/osiris put snippets/python-async /tmp/python-async.py \
|
||||
--title "Python Async/Await Example" \
|
||||
--tags language=python,topic=async,pattern=asyncio \
|
||||
--mime text/x-python
|
||||
```
|
||||
|
||||
### Search snippets
|
||||
```bash
|
||||
# Find all Rust snippets
|
||||
./target/release/osiris find --ns snippets --filter language=rust
|
||||
|
||||
# Find async patterns
|
||||
./target/release/osiris find "async" --ns snippets
|
||||
|
||||
# Find error handling examples
|
||||
./target/release/osiris find --ns snippets --filter topic=error-handling
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example 4: Document Management
|
||||
|
||||
### Create a documents namespace
|
||||
```bash
|
||||
./target/release/osiris ns create docs
|
||||
```
|
||||
|
||||
### Add documents
|
||||
```bash
|
||||
# Add a specification
|
||||
./target/release/osiris put docs/osiris-spec ./docs/specs/osiris-mvp.md \
|
||||
--title "OSIRIS MVP Specification" \
|
||||
--tags type=spec,project=osiris,status=draft \
|
||||
--mime text/markdown
|
||||
|
||||
# Add a README
|
||||
./target/release/osiris put docs/readme ./README.md \
|
||||
--title "OSIRIS README" \
|
||||
--tags type=readme,project=osiris,status=published \
|
||||
--mime text/markdown
|
||||
|
||||
# Add meeting notes
|
||||
echo "# Team Meeting 2025-10-20\n\n- Discussed OSIRIS MVP\n- Decided on minimal feature set" | \
|
||||
./target/release/osiris put docs/meeting-2025-10-20 - \
|
||||
--title "Team Meeting Notes" \
|
||||
--tags type=notes,date=2025-10-20,team=eng \
|
||||
--mime text/markdown
|
||||
```
|
||||
|
||||
### Search documents
|
||||
```bash
|
||||
# Find all specifications
|
||||
./target/release/osiris find --ns docs --filter type=spec
|
||||
|
||||
# Find draft documents
|
||||
./target/release/osiris find --ns docs --filter status=draft
|
||||
|
||||
# Search by content
|
||||
./target/release/osiris find "MVP" --ns docs
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example 5: Multi-Namespace Operations
|
||||
|
||||
### List all namespaces
|
||||
```bash
|
||||
./target/release/osiris ns list
|
||||
```
|
||||
|
||||
### Get statistics
|
||||
```bash
|
||||
# Overall stats
|
||||
./target/release/osiris stats
|
||||
|
||||
# Namespace-specific stats
|
||||
./target/release/osiris stats --ns notes
|
||||
./target/release/osiris stats --ns calendar
|
||||
./target/release/osiris stats --ns snippets
|
||||
```
|
||||
|
||||
### Delete a namespace
|
||||
```bash
|
||||
./target/release/osiris ns delete snippets
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example 6: Batch Operations
|
||||
|
||||
### Bulk import notes
|
||||
```bash
|
||||
# Create multiple notes from a directory
|
||||
for file in ./my-notes/*.md; do
|
||||
filename=$(basename "$file" .md)
|
||||
./target/release/osiris put "notes/$filename" "$file" \
|
||||
--tags source=import,format=markdown \
|
||||
--mime text/markdown
|
||||
done
|
||||
```
|
||||
|
||||
### Export all notes
|
||||
```bash
|
||||
# Get all note IDs and export them
|
||||
./target/release/osiris find --ns notes --topk 1000 --json | \
|
||||
jq -r '.[].id' | \
|
||||
while read id; do
|
||||
./target/release/osiris get "notes/$id" --raw --output "./export/$id.txt"
|
||||
done
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example 7: Advanced Search Patterns
|
||||
|
||||
### Complex filtering
|
||||
```bash
|
||||
# Find high-priority engineering tasks
|
||||
./target/release/osiris find --ns calendar \
|
||||
--filter priority=high \
|
||||
--filter team=eng
|
||||
|
||||
# Find beginner-level Rust tutorials
|
||||
./target/release/osiris find "rust" --ns notes \
|
||||
--filter level=beginner \
|
||||
--filter type=tutorial
|
||||
```
|
||||
|
||||
### Combining text search with filters
|
||||
```bash
|
||||
# Find notes about "performance" tagged as high priority
|
||||
./target/release/osiris find "performance" --ns notes \
|
||||
--filter priority=high
|
||||
|
||||
# Find meetings about "standup"
|
||||
./target/release/osiris find "standup" --ns calendar \
|
||||
--filter type=meeting
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example 8: JSON Output and Scripting
|
||||
|
||||
### Get search results as JSON
|
||||
```bash
|
||||
# Search and process with jq
|
||||
./target/release/osiris find "rust" --ns notes --json | \
|
||||
jq '.[] | {id: .id, score: .score, snippet: .snippet}'
|
||||
|
||||
# Count results
|
||||
./target/release/osiris find "programming" --ns notes --json | \
|
||||
jq 'length'
|
||||
|
||||
# Get top result
|
||||
./target/release/osiris find "osiris" --ns notes --json | \
|
||||
jq '.[0]'
|
||||
```
|
||||
|
||||
### Scripting with OSIRIS
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Script to find and display all high-priority items
|
||||
|
||||
echo "High Priority Items:"
|
||||
echo "==================="
|
||||
|
||||
# Search notes
|
||||
echo -e "\nNotes:"
|
||||
./target/release/osiris find --ns notes --filter priority=high --json | \
|
||||
jq -r '.[] | "- \(.id): \(.snippet)"'
|
||||
|
||||
# Search calendar
|
||||
echo -e "\nEvents:"
|
||||
./target/release/osiris find --ns calendar --filter priority=high --json | \
|
||||
jq -r '.[] | "- \(.id): \(.snippet)"'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tips and Best Practices
|
||||
|
||||
### 1. Consistent Tagging
|
||||
Use consistent tag names across your objects:
|
||||
```bash
|
||||
# Good: consistent tag names
|
||||
--tags topic=rust,level=beginner,type=tutorial
|
||||
|
||||
# Avoid: inconsistent naming
|
||||
--tags Topic=Rust,skill_level=Beginner,kind=Tutorial
|
||||
```
|
||||
|
||||
### 2. Meaningful IDs
|
||||
Use descriptive IDs that make sense:
|
||||
```bash
|
||||
# Good: descriptive ID
|
||||
./target/release/osiris put notes/rust-ownership-guide ...
|
||||
|
||||
# Avoid: cryptic ID
|
||||
./target/release/osiris put notes/abc123 ...
|
||||
```
|
||||
|
||||
### 3. Use MIME Types
|
||||
Always specify MIME types for better organization:
|
||||
```bash
|
||||
--mime text/markdown
|
||||
--mime application/json
|
||||
--mime text/x-rust
|
||||
--mime text/plain
|
||||
```
|
||||
|
||||
### 4. Leverage Filters
|
||||
Use filters to narrow down search results:
|
||||
```bash
|
||||
# Instead of searching all notes
|
||||
./target/release/osiris find "rust" --ns notes
|
||||
|
||||
# Filter by specific criteria
|
||||
./target/release/osiris find "rust" --ns notes --filter level=beginner
|
||||
```
|
||||
|
||||
### 5. Regular Backups
|
||||
Export your data regularly:
|
||||
```bash
|
||||
# Export all namespaces
|
||||
for ns in notes calendar docs; do
|
||||
./target/release/osiris find --ns "$ns" --topk 10000 --json > "backup-$ns.json"
|
||||
done
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Connection Issues
|
||||
```bash
|
||||
# Check if HeroDB is running
|
||||
redis-cli -p 6379 PING
|
||||
|
||||
# Verify configuration
|
||||
cat ~/.config/osiris/config.toml
|
||||
```
|
||||
|
||||
### Object Not Found
|
||||
```bash
|
||||
# List all objects in a namespace
|
||||
./target/release/osiris find --ns notes --topk 1000
|
||||
|
||||
# Check if namespace exists
|
||||
./target/release/osiris ns list
|
||||
```
|
||||
|
||||
### Search Returns No Results
|
||||
```bash
|
||||
# Try without filters first
|
||||
./target/release/osiris find "keyword" --ns notes
|
||||
|
||||
# Check if objects have the expected tags
|
||||
./target/release/osiris get notes/some-id
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Explore the [README](README.md) for more information
|
||||
- Read the [MVP Specification](docs/specs/osiris-mvp.md)
|
||||
- Check out the [source code](src/) to understand the implementation
|
||||
- Contribute improvements or report issues
|
||||
|
||||
Happy organizing with OSIRIS! 🎯
|
||||
Reference in New Issue
Block a user