David Snelling
e838327a22
- Add frozen flag to separate data immutability from performance optimizations - readOnly: prevents data mutations but allows index optimizations (default behavior) - frozen: prevents ALL changes including statistics and index updates - Smart default: frozen=false when readOnly=true for optimal performance - Add comprehensive documentation for read-only and frozen modes - Created docs/guides/readonly-frozen-modes.md with detailed guide - Added examples for compliance, forensics, and testing use cases - Updated all documentation indexes with new guide links - Simplify README.md to emphasize unified API - Clearer demonstration that same code works everywhere - Simplified framework examples showing consistent API - Better noun/verb examples for entities and relationships - Collapsible sections for cloud platform examples - Environment auto-detection table - Add tests for frozen flag behavior - Test readOnly without frozen (allows optimizations) - Test frozen mode (complete immutability) - Test dynamic mode switching BREAKING CHANGE: readOnly behavior changed - now allows optimizations by default. To get old behavior (complete immutability), use readOnly: true with frozen: true.
122 lines
No EOL
4.4 KiB
Markdown
122 lines
No EOL
4.4 KiB
Markdown
# User Guides
|
|
|
|
Comprehensive guides for using Brainy's features effectively in your applications.
|
|
|
|
## 📖 Available Guides
|
|
|
|
### 🔍 [Search and Metadata Guide](SEARCH_AND_METADATA_GUIDE.md)
|
|
Master advanced search techniques and metadata management.
|
|
|
|
- Field-specific search strategies
|
|
- JSON document search patterns
|
|
- Metadata optimization techniques
|
|
- Search performance tips
|
|
|
|
### ✏️ [Write-Only Mode Implementation](WRITEONLY_MODE_IMPLEMENTATION.md)
|
|
Optimize data ingestion with write-only mode.
|
|
|
|
- High-throughput data loading
|
|
- Batch operation strategies
|
|
- Performance optimization for writes
|
|
- Use cases and implementations
|
|
|
|
### 🔒 [Read-Only & Frozen Modes](../guides/readonly-frozen-modes.md)
|
|
Control immutability for different production scenarios.
|
|
|
|
- Read-only with optimizations (default)
|
|
- Completely frozen for compliance
|
|
- Dynamic mode switching
|
|
- Migration from older versions
|
|
|
|
### 💾 [Cache Configuration](../guides/cache-configuration.md)
|
|
Configure caching for optimal performance.
|
|
|
|
- Multi-level caching strategies
|
|
- Memory optimization techniques
|
|
- Cache hit rate improvement
|
|
- Environment-specific settings
|
|
|
|
### 📄 [JSON Document Search](../guides/json-document-search.md)
|
|
Search within JSON document fields.
|
|
|
|
- Field prioritization strategies
|
|
- Service-based field mapping
|
|
- Cross-service search patterns
|
|
- Advanced querying techniques
|
|
|
|
### 🎯 [HNSW Field Search](../guides/hnsw-field-search.md)
|
|
Field-specific vector search techniques.
|
|
|
|
- Targeted field searches
|
|
- Search scope optimization
|
|
- Performance considerations
|
|
- Integration patterns
|
|
|
|
### 🤖 [Model Management](../guides/model-management.md)
|
|
Manage AI models and embeddings effectively.
|
|
|
|
- Embedding model selection
|
|
- Custom embedding functions
|
|
- Model performance optimization
|
|
- Version management strategies
|
|
|
|
### 🚀 [Production Migration Guide](../guides/production-migration-guide.md)
|
|
Best practices for production deployment.
|
|
|
|
- Environment transition strategies
|
|
- Data migration techniques
|
|
- Performance monitoring setup
|
|
- Scaling considerations
|
|
|
|
### 🔌 [Service Identification](../guides/service-identification.md)
|
|
Track and manage data from multiple services.
|
|
|
|
- Service-based data organization
|
|
- Cross-service search capabilities
|
|
- Data source attribution
|
|
- Integration patterns
|
|
|
|
### 📦 [Optional Model Bundling](../guides/optional-model-bundling.md)
|
|
Optimize bundle size with selective model loading.
|
|
|
|
- Bundle size optimization
|
|
- Conditional model loading
|
|
- Performance trade-offs
|
|
- Deployment strategies
|
|
|
|
## 🎯 How to Use These Guides
|
|
|
|
### For New Users
|
|
1. Start with **[Search and Metadata Guide](SEARCH_AND_METADATA_GUIDE.md)** to understand core search concepts
|
|
2. Review **[JSON Document Search](../guides/json-document-search.md)** for working with structured data
|
|
3. Check **[Cache Configuration](../guides/cache-configuration.md)** for performance optimization
|
|
|
|
### For Production Deployments
|
|
1. Read **[Production Migration Guide](../guides/production-migration-guide.md)** for deployment best practices
|
|
2. Implement **[Write-Only Mode](WRITEONLY_MODE_IMPLEMENTATION.md)** for high-throughput scenarios
|
|
3. Configure **[Model Management](../guides/model-management.md)** for optimal AI model usage
|
|
|
|
### For Advanced Use Cases
|
|
1. Master **[HNSW Field Search](../guides/hnsw-field-search.md)** for specialized search patterns
|
|
2. Implement **[Service Identification](../guides/service-identification.md)** for multi-service architectures
|
|
3. Optimize with **[Optional Model Bundling](../guides/optional-model-bundling.md)** for specific deployment needs
|
|
|
|
## 🔗 Related Documentation
|
|
|
|
- **[Getting Started](../getting-started/)** - Basic setup and first steps
|
|
- **[Optimization Guides](../optimization-guides/)** - Performance and scaling
|
|
- **[API Reference](../api-reference/)** - Complete API documentation
|
|
- **[Examples](../examples/)** - Practical code examples
|
|
|
|
## 💡 Pro Tips
|
|
|
|
- **Read Guides in Order**: Each guide builds on concepts from previous ones
|
|
- **Test Examples**: All guides include working code examples
|
|
- **Check Performance**: Monitor metrics after implementing guide recommendations
|
|
- **Stay Updated**: Guides are updated with new features and best practices
|
|
|
|
## 🆘 Need Help?
|
|
|
|
- **[Troubleshooting](../troubleshooting/)** - Common issues and solutions
|
|
- **[GitHub Issues](https://github.com/soulcraft-research/brainy/issues)** - Report bugs or request features
|
|
- **[GitHub Discussions](https://github.com/soulcraft-research/brainy/discussions)** - Community support and questions |