Update SQL Server vector search for latest VECTOR_SEARCH() syntax

- Remove deprecated topN parameter from VectorSearch API
- Add WithApproximate() LINQ operator for opt-in approximate search
- Implicit ORDER BY Distance for VectorSearch results
- Update SQL generation: GenerateTop checks WithApproximateExpression
- Handle nullability processing for WithApproximateExpression
- Remove SetOffset from SelectExpression (no longer needed)
- Add comprehensive tests including exact kNN, approximate, subquery,
  joins, skip/take patterns
- Refresh API baselines

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: roji

src/EFCore.SqlServer/EFCore.SqlServer.baseline.json

@@ -2662,6 +2662,10 @@
         {
           "Member": "static System.Linq.IQueryable<Microsoft.EntityFrameworkCore.VectorSearchResult<T>> VectorSearch<T, TVector>(this Microsoft.EntityFrameworkCore.DbSet<T> source, System.Linq.Expressions.Expression<System.Func<T, TVector>> vectorPropertySelector, TVector similarTo, string metric);",
           "Stage": "Experimental"
+        },
+        {
+          "Member": "static System.Linq.IQueryable<T> WithApproximate<T>(this System.Linq.IQueryable<T> source);",
+          "Stage": "Experimental"
         }
       ]
     },

src/EFCore.SqlServer/Extensions/SqlServerQueryableExtensions.cs

@@ -18,7 +18,7 @@ public static class SqlServerQueryableExtensions
     #region VectorSearch
 
     /// <summary>
-    ///     Search for vectors similar to a given query vector using an approximate nearest neighbors vector search algorithm.
+    ///     Search for vectors similar to a given query vector using the SQL Server <c>VECTOR_SEARCH()</c> function.
     /// </summary>
     /// <param name="source">The <see cref="DbSet{T}" /> representing the table containing the vector column to query.</param>
     /// <param name="vectorPropertySelector">A selector for the vector property on the entity.</param>
@@ -30,8 +30,9 @@ public static class SqlServerQueryableExtensions
     /// </param>
     /// <remarks>
     ///     <para>
-    ///         Compose the returned query with <c>OrderBy(r => r.Distance)</c> and <c>Take(...)</c> to limit the results as required
-    ///         for approximate vector search.
+    ///         Use <see cref="WithApproximate{T}" /> after <c>Take(...)</c> to enable approximate nearest neighbor (ANN)
+    ///         search, which uses the vector index for better performance. Without <c>WithApproximate</c>, an exact k-nearest
+    ///         neighbor (kNN) search is performed. Add an explicit <c>OrderBy</c> to control result ordering.
     ///     </para>
     /// </remarks>
     /// <seealso href="https://learn.microsoft.com/sql/t-sql/functions/vector-search-transact-sql">
@@ -75,6 +76,32 @@ private static IQueryable<VectorSearchResult<T>> VectorSearch<T, TVector>(
         where TVector : unmanaged
         => throw new UnreachableException();
 
+    /// <summary>
+    ///     Enables approximate nearest neighbor (ANN) search for a vector search query. This causes <c>WITH APPROXIMATE</c> to
+    ///     be added to the SQL <c>TOP</c> clause, instructing SQL Server to use the vector index for better performance.
+    /// </summary>
+    /// <remarks>
+    ///     <para>
+    ///         This method must be called after <c>Take(...)</c> to specify the number of results. Without <c>WithApproximate</c>,
+    ///         vector search performs an exact k-nearest neighbor (kNN) search without using the vector index.
+    ///     </para>
+    /// </remarks>
+    /// <seealso href="https://learn.microsoft.com/sql/t-sql/functions/vector-search-transact-sql">
+    ///     SQL Server documentation for <c>VECTOR_SEARCH()</c>.
+    /// </seealso>
+    [Experimental(EFDiagnostics.SqlServerVectorSearch)]
+    public static IQueryable<T> WithApproximate<T>(this IQueryable<T> source)
+    {
+        var queryableSource = (IQueryable)source;
+
+        return queryableSource.Provider is EntityQueryProvider
+            ? queryableSource.Provider.CreateQuery<T>(
+                Expression.Call(
+                    method: new Func<IQueryable<T>, IQueryable<T>>(WithApproximate).Method,
+                    queryableSource.Expression))
+            : throw new InvalidOperationException(CoreStrings.FunctionOnNonEfLinqProvider(nameof(WithApproximate)));
+    }
+
     #endregion VectorSearch
 
     #region Full-text search TVFs

src/EFCore.SqlServer/Properties/SqlServerStrings.Designer.cs

@@ -426,4 +426,10 @@
   <data name="VectorSearchRequiresColumn" xml:space="preserve">
     <value>VectorSearch() requires a valid vector column.</value>
   </data>
+  <data name="WithApproximateRequiresTake" xml:space="preserve">
+    <value>WithApproximate() must be called after Take() to specify the number of results.</value>
+  </data>
+  <data name="WithApproximateNotSupportedWithSkipAndTake" xml:space="preserve">
+    <value>WithApproximate() after Skip().Take() is not supported. Use Take().WithApproximate().Skip() instead, or remove Skip().</value>
+  </data>
 </root>

src/EFCore.SqlServer/Properties/SqlServerStrings.resx

@@ -0,0 +1,89 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using Microsoft.EntityFrameworkCore.Query.SqlExpressions;
+
+// ReSharper disable once CheckNamespace
+namespace Microsoft.EntityFrameworkCore.SqlServer.Query.Internal;
+
+// WITH APPROXIMATE can only be specified on SELECT's TOP clause, so it's better to model it as a flag on SelectExpression
+// rather than as an expression node. But EF doesn't currently support provider-specific subclasses of SelectExpression.
+
+/// <summary>
+///     This is an internal API that supports the Entity Framework Core infrastructure and not subject to
+///     the same compatibility standards as public APIs. It may be changed or removed without notice in
+///     any release. You should only use it directly in your code with extreme caution and knowing that
+///     doing so can result in application failures when updating to a new Entity Framework Core release.
+/// </summary>
+/// <remarks>
+///     Wraps a <see cref="SqlExpression" /> (the limit value) so that <c>GenerateTop</c> can render
+///     <c>TOP(N) WITH APPROXIMATE</c> instead of just <c>TOP(N)</c>.
+/// </remarks>
+public class WithApproximateExpression : SqlExpression
+{
+    private static ConstructorInfo? _quotingConstructor;
+
+    /// <summary>
+    ///     This is an internal API that supports the Entity Framework Core infrastructure and not subject to
+    ///     the same compatibility standards as public APIs. It may be changed or removed without notice in
+    ///     any release. You should only use it directly in your code with extreme caution and knowing that
+    ///     doing so can result in application failures when updating to a new Entity Framework Core release.
+    /// </summary>
+    public WithApproximateExpression(SqlExpression operand)
+        : base(operand.Type, operand.TypeMapping)
+    {
+        Operand = operand;
+    }
+
+    /// <summary>
+    ///     This is an internal API that supports the Entity Framework Core infrastructure and not subject to
+    ///     the same compatibility standards as public APIs. It may be changed or removed without notice in
+    ///     any release. You should only use it directly in your code with extreme caution and knowing that
+    ///     doing so can result in application failures when updating to a new Entity Framework Core release.
+    /// </summary>
+    public virtual SqlExpression Operand { get; }
+
+    /// <inheritdoc />
+    protected override Expression VisitChildren(ExpressionVisitor visitor)
+        => Update((SqlExpression)visitor.Visit(Operand));
+
+    /// <summary>
+    ///     This is an internal API that supports the Entity Framework Core infrastructure and not subject to
+    ///     the same compatibility standards as public APIs. It may be changed or removed without notice in
+    ///     any release. You should only use it directly in your code with extreme caution and knowing that
+    ///     doing so can result in application failures when updating to a new Entity Framework Core release.
+    /// </summary>
+    public virtual WithApproximateExpression Update(SqlExpression operand)
+        => operand != Operand
+            ? new WithApproximateExpression(operand)
+            : this;
+
+    /// <inheritdoc />
+    public override Expression Quote()
+        => New(
+            _quotingConstructor ??= typeof(WithApproximateExpression).GetConstructor(
+                [typeof(SqlExpression)])!,
+            Operand.Quote());
+
+    /// <inheritdoc />
+    protected override void Print(ExpressionPrinter expressionPrinter)
+    {
+        expressionPrinter.Visit(Operand);
+        expressionPrinter.Append(" WITH APPROXIMATE");
+    }
+
+    /// <inheritdoc />
+    public override bool Equals(object? obj)
+        => obj != null
+            && (ReferenceEquals(this, obj)
+                || obj is WithApproximateExpression withApproximate
+                && Equals(withApproximate));
+
+    private bool Equals(WithApproximateExpression other)
+        => base.Equals(other)
+            && Operand.Equals(other.Operand);
+
+    /// <inheritdoc />
+    public override int GetHashCode()
+        => HashCode.Combine(base.GetHashCode(), Operand);
+}

src/EFCore.SqlServer/Query/Internal/SqlExpressions/WithApproximateExpression.cs

@@ -548,16 +548,12 @@ protected override void GenerateTop(SelectExpression selectExpression)
         if (selectExpression is { Limit: not null, Offset: null })
         {
             Sql.Append("TOP(");
-
             Visit(selectExpression.Limit);
 
-            Sql.Append(") ");
-
-            // When performing approximate vector search with VECTOR_SEARCH(), SQL Server requires adding
-            // WITH APPROXIMATE: https://learn.microsoft.com/sql/t-sql/functions/vector-search-transact-sql
-            if (selectExpression.Tables.Any(t => t.UnwrapJoin() is TableValuedFunctionExpression { Name: "VECTOR_SEARCH" }))
+            // WithApproximateExpression renders its own closing ") WITH APPROXIMATE " via VisitExtension
+            if (selectExpression.Limit is not WithApproximateExpression)
             {
-                Sql.Append("WITH APPROXIMATE ");
+                Sql.Append(") ");
             }
         }
 
@@ -755,6 +751,13 @@ when tableExpression.FindAnnotation(SqlServerAnnotationNames.TemporalOperationTy
 
             case SqlServerOpenJsonExpression openJsonExpression:
                 return VisitOpenJsonExpression(openJsonExpression);
+
+            // WithApproximateExpression wraps the Limit in the SelectExpression; it renders the operand value
+            // followed by ") WITH APPROXIMATE " (closing the TOP( opened by GenerateTop).
+            case WithApproximateExpression withApproximate:
+                Visit(withApproximate.Operand);
+                Sql.Append(") WITH APPROXIMATE ");
+                return withApproximate;
         }
 
         return base.VisitExtension(extensionExpression);

src/EFCore.SqlServer/Query/Internal/SqlServerQuerySqlGenerator.cs

@@ -171,6 +171,11 @@ var metric
 #pragma warning restore EF9105 // VectorSearch is experimental
                 }
 
+                case nameof(SqlServerQueryableExtensions.WithApproximate):
+                {
+                    return TranslateWithApproximate(source);
+                }
+
                 case nameof(SqlServerQueryableExtensions.FreeTextTable) or nameof(SqlServerQueryableExtensions.ContainsTable)
                     when source is
                     {
@@ -795,6 +800,30 @@ bool TryTranslate(
         }
     }
 
+    private ShapedQueryExpression TranslateWithApproximate(ShapedQueryExpression source)
+    {
+        var selectExpression = (SelectExpression)source.QueryExpression;
+
+        switch (selectExpression)
+        {
+            // WithApproximate() after Skip().Take() — not yet supported; SQL Server will add native OFFSET+FETCH
+            // WITH APPROXIMATE support in the future.
+            case { Limit: not null, Offset: not null }:
+                throw new InvalidOperationException(SqlServerStrings.WithApproximateNotSupportedWithSkipAndTake);
+
+            // Normal case: WithApproximate() after Take() — wrap the Limit with WithApproximateExpression
+            case { Limit: { } limit }:
+#pragma warning disable EF1001 // Internal EF Core API usage.
+                selectExpression.SetLimit(new WithApproximateExpression(limit));
+#pragma warning restore EF1001 // Internal EF Core API usage.
+                return source;
+
+            // WithApproximate() without Take()
+            default:
+                throw new InvalidOperationException(SqlServerStrings.WithApproximateRequiresTake);
+        }
+    }
+
     /// <summary>
     ///     This is an internal API that supports the Entity Framework Core infrastructure and not subject to
     ///     the same compatibility standards as public APIs. It may be changed or removed without notice in

src/EFCore.SqlServer/Query/Internal/SqlServerQueryableMethodTranslatingExpressionVisitor.cs

@@ -5,6 +5,7 @@
 using System.Diagnostics.CodeAnalysis;
 using Microsoft.EntityFrameworkCore.Query.SqlExpressions;
 using Microsoft.EntityFrameworkCore.SqlServer.Infrastructure.Internal;
+using Microsoft.EntityFrameworkCore.SqlServer.Query.Internal.SqlExpressions;
 
 namespace Microsoft.EntityFrameworkCore.SqlServer.Query.Internal;
 
@@ -73,6 +74,9 @@ protected override SqlExpression VisitCustomSqlExpression(
             SqlServerAggregateFunctionExpression aggregateFunctionExpression
                 => VisitSqlServerAggregateFunction(aggregateFunctionExpression, allowOptimizedExpansion, out nullable),
 
+            WithApproximateExpression withApproximate
+                => withApproximate.Update(Visit(withApproximate.Operand, allowOptimizedExpansion, out nullable)),
+
             _ => base.VisitCustomSqlExpression(sqlExpression, allowOptimizedExpansion, out nullable)
         };