Consolidate document retrieval methods: Remove v1 and standardize on v2 #5537

Problem Statement

Currently, Feast has both v1 and v2 document retrieval methods (retrieve_online_documents_v1 and retrieve_online_documents_v2) across different online stores. This creates inconsistency and maintenance overhead.

Issues identified:

• Different online stores may have different logic between v1 and v2 implementations
• As noted in PR #5487, PostgreSQL online store shows v1 and v2 "retrieving different dataframes as the logic is completely different for both versions"
• v2 was intended to "incorporate more fields" but differences beyond that indicate potential bugs
• Maintaining two versions increases code complexity and testing burden

Research Required

Before removing v1, we need to investigate:

1. Cross-Store Analysis

• Audit all online stores that implement both v1 and v2 document retrieval
• Document the specific differences in logic between v1 and v2 for each store
• Identify which stores have consistent behavior vs. divergent behavior

2. API Compatibility Assessment

• Analyze which version provides more comprehensive/correct results
• Compare field coverage between v1 and v2 responses
• Evaluate performance characteristics of both versions

3. Usage Analysis

• Identify current usage patterns of v1 vs v2 in the codebase
• Check external documentation and examples using these APIs
• Assess backward compatibility requirements

4. Store-Specific Investigation

Focus on stores mentioned with differences:

• PostgreSQL: Detailed analysis of why v1/v2 return different dataframes
• Remote store: Ensure consistency after PR #5487 implementation
• Other stores: Milvus, Redis, DynamoDB, etc.

Proposed Solution

Based on research findings:

Phase 1: Research & Documentation

1. Complete the research items above
2. Create a comprehensive comparison matrix of v1 vs v2 across all stores
3. Identify the "canonical" version that should be preserved

Phase 2: Standardization

1. Ensure v2 implementation is consistent and correct across all stores
2. Update v2 to include any missing functionality from v1 (if needed)
3. Add comprehensive tests for v2 across all stores

Phase 3: Migration & Removal

1. Deprecate v1 methods with clear migration guidance
2. Update all internal usage to v2
3. Remove v1 implementation after appropriate deprecation period

Acceptance Criteria

• All online stores have consistent document retrieval behavior
• Single document retrieval API (v2) that works uniformly across stores
• Comprehensive test coverage for document retrieval functionality
• Migration guide for any external users of v1 API
• Updated documentation reflecting the consolidated API

Context

This issue stems from the discussion in PR #5487 where @franciscojavierarceo noted that v1/v2 differences beyond additional fields indicate bugs, and @jyejare confirmed that different stores have different logic between versions.

Original comment:

"v2 vs v1 should be approximately the same where v2 was meant to incorporate more fields. If there is a difference, it's a bug... we should remove v1 and move to v2 for all of the existing usage."

Priority

Medium-High - This affects API consistency and maintainability, but doesn't block current functionality.