Commit 08b5ea1
authored
.Net: docs: Add ADR-0065 for LINQ-based ITextSearch filtering migration strategy (#13335)
# Add ADR-0065: LINQ-Based Filtering for ITextSearch Interface
## Summary
This PR adds a comprehensive Architectural Decision Record (ADR)
documenting the decision to migrate `ITextSearch` from clause-based
filtering to LINQ-based filtering using a dual interface pattern.
## Context
Issue: #10456
The existing `ITextSearch` interface uses `TextSearchFilter`
(clause-based approach) which:
- Creates runtime errors from property name typos
- Lacks compile-time type safety
- Requires conversion to obsolete `VectorSearchFilter` APIs internally
- Provides no IntelliSense support
## Decision
**Chosen Approach**: Dual Interface Pattern (Option 3)
- **NEW**: `ITextSearch<TRecord>` with LINQ filtering
(`Expression<Func<TRecord, bool>>`)
- **LEGACY**: `ITextSearch` marked `[Obsolete]` for backward
compatibility
- Both interfaces coexist temporarily during migration
## Key Architectural Points
### Migration Strategy (Temporary by Design)
1. **Phase 1 (Current)**: Both interfaces coexist - zero breaking
changes
2. **Phase 2 (Future Major Version)**: Increase deprecation warnings
3. **Phase 3 (Future Major Version)**: Remove obsolete interface
entirely
### Why Mark as `[Obsolete]` Now
- Prevents new code from adopting legacy patterns
- Signals future removal to ecosystem
- Gives 1-2 major versions for migration
- Follows .NET best practices for API evolution
### Implementation Patterns Documented
**Pattern A: Direct LINQ Passthrough** (VectorStoreTextSearch)
- Two independent code paths
- No conversion overhead
- Native LINQ support in vector stores
**Pattern B: LINQ-to-Legacy Conversion** (Bing, Google, Tavily, Brave)
- Converts LINQ expressions to legacy format
- Reuses existing API implementations
- Expression tree analysis
## Benefits
✅ **Zero breaking changes** - existing code continues working
✅ **Type safety** - compile-time validation and IntelliSense
✅ **AOT compatible** - no `[RequiresDynamicCode]` attributes
✅ **Clear migration path** - deprecation warnings guide users
✅ **Future-ready** - establishes path for technical debt removal
## Related PRs
This ADR documents the architectural decision behind:
- ✅ PR #13175 - Core interfaces (Merged)
- ✅ PR #13179 - VectorStoreTextSearch (Merged)
- ✅ PR #13318 - Type improvements (Merged)
- ✅ PR #13188 - BingTextSearch (Merged)
- ✅ PR #13190 - GoogleTextSearch (Merged)
- ⏳ PR #13191 - Tavily/Brave (Open)
- 📋 PR #13194 - Samples/docs (Planned)
## Review Notes
Per ADR process requirements:
- **Status**: `accepted` (implementation already complete)
- **Deciders**: @roji, @westey-m, @markwallace-microsoft (required
reviewers)
- **Consulted**: @moonbox3
- **Date**: 2025-10-25 (when decision was finalized)
This ADR serves as:
- Permanent documentation of the architectural decision
- Reference for future maintainers
- Explanation of the temporary dual interface state
- Migration guide for ecosystem consumers
## Checklist
- [x] ADR follows template structure
- [x] All required sections included
- [x] Deciders listed as required reviewers
- [x] Status set to `accepted`
- [x] Date reflects decision finalization
- [x] File naming follows convention:
`0065-linq-based-text-search-filtering.md`
- [x] Located in correct directory: `dotnet/docs/decisions/`
## Target Branch
- **Base**: `feature-text-search-linq`
- **Reason**: ADR documents the architectural decisions implemented in
this feature branch
Co-authored-by: Alexander Zarei <alzarei@users.noreply.github.com>1 parent d8bd8ab commit 08b5ea1
1 file changed
Lines changed: 569 additions & 0 deletions
0 commit comments