Skip to content

Commit 08b5ea1

Browse files
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

File tree

0 commit comments

Comments
 (0)