David Snelling
7e243b6f2b
BREAKING CHANGE: Remove hard delete option from deleteVerb() for consistent API - Add complete metadata namespace architecture with O(1) soft delete performance - Implement periodic cleanup system for old soft-deleted items - Add restore methods for both nouns and verbs - Require metadata contracts for all augmentations - Eliminate namespace collisions with clean separation (_brainy, _augmentations, _audit) - Optimize index performance using flattened dot-notation for O(1) lookups - Add comprehensive augmentation safety system with type-safe access control - Maintain full backward compatibility for existing data - Add enterprise-grade cleanup with configurable age thresholds and batch processing 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
114 lines
No EOL
3.3 KiB
Markdown
114 lines
No EOL
3.3 KiB
Markdown
# Brainy Performance Analysis & Optimization
|
|
|
|
## Current Issues Found
|
|
|
|
### 1. ❌ CRITICAL: notEquals Operator is O(n)
|
|
```javascript
|
|
// PROBLEM: Gets ALL items to filter
|
|
case 'notEquals':
|
|
const allItemIds = await this.getAllIds() // O(n) - TERRIBLE!
|
|
```
|
|
|
|
### 2. ❌ Soft Delete Performance
|
|
- Every query adds `deleted: { notEquals: true }`
|
|
- This makes EVERY query O(n) instead of O(log n)
|
|
|
|
### 3. ❌ exists Operator is Inefficient
|
|
```javascript
|
|
case 'exists':
|
|
// Scans all cache entries - O(n)
|
|
for (const [key, entry] of this.indexCache.entries()) {
|
|
if (entry.field === field) {
|
|
entry.ids.forEach(id => allIds.add(id))
|
|
}
|
|
}
|
|
```
|
|
|
|
### 4. ⚠️ Query Optimizer Not Smart Enough
|
|
- `isSelectiveFilter()` needs to understand which filters are fast
|
|
- Should prioritize O(1) and O(log n) operations
|
|
|
|
## Performance Characteristics
|
|
|
|
### ✅ Fast Operations (Keep These)
|
|
| Operation | Complexity | Example |
|
|
|-----------|-----------|---------|
|
|
| Vector Search (HNSW) | O(log n) | `like: "query"` |
|
|
| Exact Match | O(1) | `where: { status: "active" }` |
|
|
| Deleted Filter (NEW) | O(1) | `where: { deleted: false }` |
|
|
| Range Query (sorted) | O(log n) | `where: { year: { gt: 2000 } }` |
|
|
| Graph Traversal | O(k) | `connected: { from: id }` |
|
|
|
|
### ❌ Slow Operations (Need Fixing)
|
|
| Operation | Current | Should Be | Fix |
|
|
|-----------|---------|-----------|-----|
|
|
| notEquals | O(n) | O(1) or O(log n) | Use complement index |
|
|
| exists | O(n) | O(1) | Maintain field existence bitmap |
|
|
| noneOf | O(n) | O(k) | Use set operations |
|
|
|
|
## Optimized Architecture
|
|
|
|
### Solution 1: Positive Indexing for Soft Delete ✅
|
|
```javascript
|
|
// Instead of: deleted !== true (O(n))
|
|
// Use: deleted === false (O(1))
|
|
where: { deleted: false }
|
|
|
|
// Ensure all items have deleted field
|
|
if (!metadata.deleted) metadata.deleted = false
|
|
```
|
|
|
|
### Solution 2: Complement Indices for notEquals
|
|
```javascript
|
|
class MetadataIndexManager {
|
|
// For common notEquals queries, maintain complement sets
|
|
private complementIndices: Map<string, Set<string>> = new Map()
|
|
|
|
// Example: Track non-deleted items separately
|
|
private activeItems: Set<string> = new Set()
|
|
private deletedItems: Set<string> = new Set()
|
|
}
|
|
```
|
|
|
|
### Solution 3: Field Existence Bitmap
|
|
```javascript
|
|
class FieldExistenceIndex {
|
|
private fieldBitmaps: Map<string, BitSet> = new Map()
|
|
|
|
hasField(id: string, field: string): boolean {
|
|
return this.fieldBitmaps.get(field)?.has(id) ?? false
|
|
}
|
|
}
|
|
```
|
|
|
|
## Query Execution Strategy
|
|
|
|
### Progressive Search (When Metadata is Selective)
|
|
```
|
|
1. Field Filter (O(1) or O(log n)) → Small candidate set
|
|
2. Vector Search within candidates (O(k log k))
|
|
3. Fusion if needed
|
|
```
|
|
|
|
### Parallel Search (When Nothing is Selective)
|
|
```
|
|
1. Vector Search (O(log n)) → Top K results
|
|
2. Graph Traversal (O(m)) → Connected items
|
|
3. Field Filter (O(1)) → Metadata matches
|
|
4. Fusion: Intersection or Union
|
|
```
|
|
|
|
## Implementation Priority
|
|
|
|
1. **DONE** ✅ Fix soft delete to use `deleted: false`
|
|
2. **TODO** 🔧 Optimize notEquals for common fields
|
|
3. **TODO** 🔧 Add field existence index
|
|
4. **TODO** 🔧 Improve query optimizer intelligence
|
|
5. **TODO** 🔧 Add query explain mode for debugging
|
|
|
|
## Performance Targets
|
|
|
|
- Vector search: < 10ms for 1M items
|
|
- Metadata filter: < 1ms for exact match
|
|
- Combined query: < 20ms for complex queries
|
|
- Soft delete overhead: < 0.1ms (O(1)) |