using lease for VRANGE

Author: mgravell

docs/VectorSets.md

@@ -135,23 +135,26 @@ Retrieve members in lexicographical order:
 
 ```csharp
 // Get all members
-var allMembers = await db.VectorSetRangeAsync(key);
+using var allMembers = await db.VectorSetRangeAsync(key);
+// ... access allMembers.Span, etc
 
 // Get members in a specific range
-var rangeMembers = await db.VectorSetRangeAsync(
+using var rangeMembers = await db.VectorSetRangeAsync(
     key,
     start: "product-100",
     end: "product-200",
     count: 50
 );
+// ... access rangeMembers.Span, etc
 
 // Exclude boundaries
-var members = await db.VectorSetRangeAsync(
+using var members = await db.VectorSetRangeAsync(
     key,
     start: "product-100",
     end: "product-200",
     exclude: Exclude.Both
 );
+// ... access members.Span, etc
 ```
 
 ### Enumerating Large Result Sets
@@ -194,7 +197,7 @@ await db.VectorSetAddAsync(key, request);
 
 ### Dimension Reduction
 
-Use random projection to reduce vector dimensions:
+Use projection to reduce vector dimensions:
 
 ```csharp
 var request = VectorSetAddRequest.Member("product-123", vector.AsMemory());
@@ -331,17 +334,20 @@ await Task.WhenAll(tasks);
 
 ### Range Query Pagination
 
-Use enumeration for large result sets to avoid loading everything into memory:
+Prefer enumeration for large result sets to avoid loading everything into memory:
 
 ```csharp
-// Good: Processes in batches
-await foreach (var member in db.VectorSetRangeEnumerateAsync(key, count: 1000))
+// Good: loads results in batches, processes items individually
+await foreach (var member in db.VectorSetRangeEnumerateAsync(key))
 {
     await ProcessMemberAsync(member);
 }
 
-// Avoid: Loads all results at once
-var allMembers = await db.VectorSetRangeAsync(key); // Could be millions
+// Avoid: loads all results at once
+using var allMembers1 = await db.VectorSetRangeAsync(key);
+
+// Avoid: loads resultsin batches, but still loads everything into memory at once
+var allMembers2 = await VectorSetRangeEnumerateAsync(key).ToArrayAsync();
 ```
 
 ## Common Patterns

src/StackExchange.Redis/Interfaces/IDatabase.VectorSets.cs

@@ -190,10 +190,10 @@ bool VectorSetSetAttributesJson(
     /// <param name="count">The maximum number of members to return (-1 for all).</param>
     /// <param name="exclude">Whether to exclude the start and/or end values.</param>
     /// <param name="flags">The flags to use for this operation.</param>
-    /// <returns>Members in the specified range.</returns>
+    /// <returns>Members in the specified range as a pooled memory lease.</returns>
     /// <remarks><seealso href="https://redis.io/commands/vrange"/></remarks>
     [Experimental(Experiments.VectorSets, UrlFormat = Experiments.UrlFormat)]
-    RedisValue[] VectorSetRange(
+    Lease<RedisValue> VectorSetRange(
         RedisKey key,
         RedisValue start = default,
         RedisValue end = default,

src/StackExchange.Redis/Interfaces/IDatabaseAsync.VectorSets.cs

@@ -95,7 +95,7 @@ Task<bool> VectorSetSetAttributesJsonAsync(
 
     /// <inheritdoc cref="IDatabase.VectorSetRange(RedisKey, RedisValue, RedisValue, long, Exclude, CommandFlags)"/>
     [Experimental(Experiments.VectorSets, UrlFormat = Experiments.UrlFormat)]
-    Task<RedisValue[]> VectorSetRangeAsync(
+    Task<Lease<RedisValue>?> VectorSetRangeAsync(
         RedisKey key,
         RedisValue start = default,
         RedisValue end = default,

src/StackExchange.Redis/KeyspaceIsolation/KeyPrefixed.VectorSets.cs

@@ -57,7 +57,7 @@ public Task<bool> VectorSetSetAttributesJsonAsync(RedisKey key, RedisValue membe
         CommandFlags flags = CommandFlags.None) =>
         Inner.VectorSetSimilaritySearchAsync(ToInner(key), query, flags);
 
-    public Task<RedisValue[]> VectorSetRangeAsync(
+    public Task<Lease<RedisValue>?> VectorSetRangeAsync(
         RedisKey key,
         RedisValue start = default,
         RedisValue end = default,

src/StackExchange.Redis/KeyspaceIsolation/KeyPrefixedDatabase.VectorSets.cs

@@ -54,7 +54,7 @@ public bool VectorSetSetAttributesJson(RedisKey key, RedisValue member, string a
         CommandFlags flags = CommandFlags.None) =>
         Inner.VectorSetSimilaritySearch(ToInner(key), query, flags);
 
-    public RedisValue[] VectorSetRange(
+    public Lease<RedisValue> VectorSetRange(
         RedisKey key,
         RedisValue start = default,
         RedisValue end = default,

src/StackExchange.Redis/Lease.cs

@@ -18,6 +18,11 @@ public sealed class Lease<T> : IMemoryOwner<T>
 
         private T[]? _arr;
 
+        /// <summary>
+        /// Gets whether this lease is empty.
+        /// </summary>
+        public bool IsEmpty => Length == 0;
+
         /// <summary>
         /// The length of the lease.
         /// </summary>

src/StackExchange.Redis/PublicAPI/PublicAPI.Unshipped.txt

@@ -1,5 +1,6 @@
 #nullable enable
-[SER001]StackExchange.Redis.IDatabase.VectorSetRange(StackExchange.Redis.RedisKey key, StackExchange.Redis.RedisValue start = default(StackExchange.Redis.RedisValue), StackExchange.Redis.RedisValue end = default(StackExchange.Redis.RedisValue), long count = -1, StackExchange.Redis.Exclude exclude = StackExchange.Redis.Exclude.None, StackExchange.Redis.CommandFlags flags = StackExchange.Redis.CommandFlags.None) -> StackExchange.Redis.RedisValue[]!
+StackExchange.Redis.Lease<T>.IsEmpty.get -> bool
+[SER001]StackExchange.Redis.IDatabase.VectorSetRange(StackExchange.Redis.RedisKey key, StackExchange.Redis.RedisValue start = default(StackExchange.Redis.RedisValue), StackExchange.Redis.RedisValue end = default(StackExchange.Redis.RedisValue), long count = -1, StackExchange.Redis.Exclude exclude = StackExchange.Redis.Exclude.None, StackExchange.Redis.CommandFlags flags = StackExchange.Redis.CommandFlags.None) -> StackExchange.Redis.Lease<StackExchange.Redis.RedisValue>!
 [SER001]StackExchange.Redis.IDatabase.VectorSetRangeEnumerate(StackExchange.Redis.RedisKey key, StackExchange.Redis.RedisValue start = default(StackExchange.Redis.RedisValue), StackExchange.Redis.RedisValue end = default(StackExchange.Redis.RedisValue), long count = 100, StackExchange.Redis.Exclude exclude = StackExchange.Redis.Exclude.None, StackExchange.Redis.CommandFlags flags = StackExchange.Redis.CommandFlags.None) -> System.Collections.Generic.IEnumerable<StackExchange.Redis.RedisValue>!
-[SER001]StackExchange.Redis.IDatabaseAsync.VectorSetRangeAsync(StackExchange.Redis.RedisKey key, StackExchange.Redis.RedisValue start = default(StackExchange.Redis.RedisValue), StackExchange.Redis.RedisValue end = default(StackExchange.Redis.RedisValue), long count = -1, StackExchange.Redis.Exclude exclude = StackExchange.Redis.Exclude.None, StackExchange.Redis.CommandFlags flags = StackExchange.Redis.CommandFlags.None) -> System.Threading.Tasks.Task<StackExchange.Redis.RedisValue[]!>!
+[SER001]StackExchange.Redis.IDatabaseAsync.VectorSetRangeAsync(StackExchange.Redis.RedisKey key, StackExchange.Redis.RedisValue start = default(StackExchange.Redis.RedisValue), StackExchange.Redis.RedisValue end = default(StackExchange.Redis.RedisValue), long count = -1, StackExchange.Redis.Exclude exclude = StackExchange.Redis.Exclude.None, StackExchange.Redis.CommandFlags flags = StackExchange.Redis.CommandFlags.None) -> System.Threading.Tasks.Task<StackExchange.Redis.Lease<StackExchange.Redis.RedisValue>?>!
 [SER001]StackExchange.Redis.IDatabaseAsync.VectorSetRangeEnumerateAsync(StackExchange.Redis.RedisKey key, StackExchange.Redis.RedisValue start = default(StackExchange.Redis.RedisValue), StackExchange.Redis.RedisValue end = default(StackExchange.Redis.RedisValue), long count = 100, StackExchange.Redis.Exclude exclude = StackExchange.Redis.Exclude.None, StackExchange.Redis.CommandFlags flags = StackExchange.Redis.CommandFlags.None) -> System.Collections.Generic.IAsyncEnumerable<StackExchange.Redis.RedisValue>!

src/StackExchange.Redis/RedisDatabase.VectorSets.cs

@@ -215,7 +215,7 @@ static RedisValue GetTerminator(RedisValue value, Exclude exclude, bool isStart)
             : Message.Create(Database, flags, RedisCommand.VRANGE, key, from, to, count);
     }
 
-    public RedisValue[] VectorSetRange(
+    public Lease<RedisValue> VectorSetRange(
         RedisKey key,
         RedisValue start = default,
         RedisValue end = default,
@@ -224,10 +224,10 @@ public RedisValue[] VectorSetRange(
         CommandFlags flags = CommandFlags.None)
     {
         var msg = GetVectorSetRangeMessage(key, start, end, count, exclude, flags);
-        return ExecuteSync(msg, ResultProcessor.RedisValueArray)!; // returns empty array if no key
+        return ExecuteSync(msg, ResultProcessor.LeaseRedisValue)!;
     }
 
-    public Task<RedisValue[]> VectorSetRangeAsync(
+    public Task<Lease<RedisValue>?> VectorSetRangeAsync(
         RedisKey key,
         RedisValue start = default,
         RedisValue end = default,
@@ -236,7 +236,7 @@ public Task<RedisValue[]> VectorSetRangeAsync(
         CommandFlags flags = CommandFlags.None)
     {
         var msg = GetVectorSetRangeMessage(key, start, end, count, exclude, flags);
-        return ExecuteAsync(msg, ResultProcessor.RedisValueArray)!; // returns empty array if no key
+        return ExecuteAsync(msg, ResultProcessor.LeaseRedisValue);
     }
 
     public IEnumerable<RedisValue> VectorSetRangeEnumerate(
@@ -250,15 +250,16 @@ public IEnumerable<RedisValue> VectorSetRangeEnumerate(
         // intentionally not using "scan" naming in case a VSCAN command is added later
         while (true)
         {
-            var batch = VectorSetRange(key, start, end, count, exclude, flags);
+            using var batch = VectorSetRange(key, start, end, count, exclude, flags);
             exclude |= Exclude.Start; // on subsequent iterations, exclude the start (we've already yielded it)
 
-            if (batch.Length == 0) yield break;
-            for (int i = 0; i < batch.Length; i++)
+            if (batch is null || batch.IsEmpty) yield break;
+            var segment = batch.ArraySegment;
+            for (int i = 0; i < segment.Count; i++)
             {
-                yield return batch[i];
+                // note side effect: use the last value as the exclusive start of the next batch
+                yield return start = segment.Array![segment.Offset + i];
             }
-            start = batch[batch.Length - 1]; // use the last value as the exclusive start of the next batch
             if (batch.Length < count || (!end.IsNull && end == start)) yield break; // no need to issue a final query
         }
     }
@@ -279,15 +280,16 @@ async IAsyncEnumerable<RedisValue> WithCancellationSupport([EnumeratorCancellati
             while (true)
             {
                 cancellationToken.ThrowIfCancellationRequested();
-                var batch = await VectorSetRangeAsync(key, start, end, count, exclude, flags);
+                using var batch = await VectorSetRangeAsync(key, start, end, count, exclude, flags);
                 exclude |= Exclude.Start; // on subsequent iterations, exclude the start (we've already yielded it)
 
-                if (batch.Length == 0) yield break;
-                for (int i = 0; i < batch.Length; i++)
+                if (batch is null || batch.IsEmpty) yield break;
+                var segment = batch.ArraySegment;
+                for (int i = 0; i < segment.Count; i++)
                 {
-                    yield return batch[i];
+                    // note side effect: use the last value as the exclusive start of the next batch
+                    yield return start = segment.Array![segment.Offset + i];
                 }
-                start = batch[batch.Length - 1]; // use the last value as the exclusive start of the next batch
                 if (batch.Length < count || (!end.IsNull && end == start)) yield break; // no need to issue a final query
             }
         }

src/StackExchange.Redis/ResultProcessor.VectorSets.cs

@@ -11,6 +11,8 @@ internal abstract partial class ResultProcessor
 
     public static readonly ResultProcessor<Lease<RedisValue>?> VectorSetLinks = new VectorSetLinksProcessor();
 
+    public static readonly ResultProcessor<Lease<RedisValue>?> LeaseRedisValue = new LeaseRedisValueProcessor();
+
     public static ResultProcessor<VectorSetInfo?> VectorSetInfo = new VectorSetInfoProcessor();
 
     private sealed class VectorSetLinksWithScoresProcessor : FlattenedLeaseProcessor<VectorSetLink>
@@ -43,6 +45,15 @@ protected override bool TryReadOne(in RawResult result, out RedisValue value)
         }
     }
 
+    private sealed class LeaseRedisValueProcessor : LeaseProcessor<RedisValue>
+    {
+        protected override bool TryParse(in RawResult raw, out RedisValue parsed)
+        {
+            parsed = raw.AsRedisValue();
+            return true;
+        }
+    }
+
     private sealed partial class VectorSetInfoProcessor : ResultProcessor<VectorSetInfo?>
     {
         protected override bool SetResultCore(PhysicalConnection connection, Message message, in RawResult result)

tests/StackExchange.Redis.Tests/VectorSetIntegrationTests.cs

@@ -694,12 +694,12 @@ public async Task VectorSetRange_BasicOperation()
         }
 
         // Get all members - should be in lexicographical order
-        var result = await db.VectorSetRangeAsync(key);
+        using var result = await db.VectorSetRangeAsync(key);
 
         Assert.NotNull(result);
         Assert.Equal(4, result.Length);
         // Lexicographical order: alpha, beta, delta, gamma
-        Assert.Equal(new[] { "alpha", "beta", "delta", "gamma" }, result.Select(r => (string?)r).ToArray());
+        Assert.Equal(new[] { "alpha", "beta", "delta", "gamma" }, result.Span.ToArray().Select(r => (string?)r).ToArray());
     }
 
     [Fact]
@@ -721,11 +721,11 @@ public async Task VectorSetRange_WithStartAndEnd()
         }
 
         // Get range from "banana" to "date" (inclusive)
-        var result = await db.VectorSetRangeAsync(key, start: "banana", end: "date");
+        using var result = await db.VectorSetRangeAsync(key, start: "banana", end: "date");
 
         Assert.NotNull(result);
         Assert.Equal(3, result.Length);
-        Assert.Equal(new[] { "banana", "cherry", "date" }, result.Select(r => (string?)r).ToArray());
+        Assert.Equal(new[] { "banana", "cherry", "date" }, result.Span.ToArray().Select(r => (string?)r).ToArray());
     }
 
     [Fact]
@@ -747,7 +747,7 @@ public async Task VectorSetRange_WithCount()
         }
 
         // Get only 5 members
-        var result = await db.VectorSetRangeAsync(key, count: 5);
+        using var result = await db.VectorSetRangeAsync(key, count: 5);
 
         Assert.NotNull(result);
         Assert.Equal(5, result.Length);
@@ -772,11 +772,11 @@ public async Task VectorSetRange_WithExcludeStart()
         }
 
         // Get range excluding start
-        var result = await db.VectorSetRangeAsync(key, start: "a", end: "d", exclude: Exclude.Start);
+        using var result = await db.VectorSetRangeAsync(key, start: "a", end: "d", exclude: Exclude.Start);
 
         Assert.NotNull(result);
         Assert.Equal(3, result.Length);
-        Assert.Equal(new[] { "b", "c", "d" }, result.Select(r => (string?)r).ToArray());
+        Assert.Equal(new[] { "b", "c", "d" }, result.Span.ToArray().Select(r => (string?)r).ToArray());
     }
 
     [Fact]
@@ -798,11 +798,11 @@ public async Task VectorSetRange_WithExcludeEnd()
         }
 
         // Get range excluding end
-        var result = await db.VectorSetRangeAsync(key, start: "a", end: "d", exclude: Exclude.Stop);
+        using var result = await db.VectorSetRangeAsync(key, start: "a", end: "d", exclude: Exclude.Stop);
 
         Assert.NotNull(result);
         Assert.Equal(3, result.Length);
-        Assert.Equal(new[] { "a", "b", "c" }, result.Select(r => (string?)r).ToArray());
+        Assert.Equal(new[] { "a", "b", "c" }, result.Span.ToArray().Select(r => (string?)r).ToArray());
     }
 
     [Fact]
@@ -824,11 +824,11 @@ public async Task VectorSetRange_WithExcludeBoth()
         }
 
         // Get range excluding both boundaries
-        var result = await db.VectorSetRangeAsync(key, start: "a", end: "e", exclude: Exclude.Both);
+        using var result = await db.VectorSetRangeAsync(key, start: "a", end: "e", exclude: Exclude.Both);
 
         Assert.NotNull(result);
         Assert.Equal(3, result.Length);
-        Assert.Equal(new[] { "b", "c", "d" }, result.Select(r => (string?)r).ToArray());
+        Assert.Equal(new[] { "b", "c", "d" }, result.Span.ToArray().Select(r => (string?)r).ToArray());
     }
 
     [Fact]
@@ -841,10 +841,10 @@ public async Task VectorSetRange_EmptySet()
         await db.KeyDeleteAsync(key, CommandFlags.FireAndForget);
 
         // Don't add any members
-        var result = await db.VectorSetRangeAsync(key);
+        using var result = await db.VectorSetRangeAsync(key);
 
         Assert.NotNull(result);
-        Assert.Empty(result);
+        Assert.Empty(result.Span.ToArray());
     }
 
     [Fact]
@@ -866,10 +866,10 @@ public async Task VectorSetRange_NoMatches()
         }
 
         // Query range with no matching members
-        var result = await db.VectorSetRangeAsync(key, start: "x", end: "z");
+        using var result = await db.VectorSetRangeAsync(key, start: "x", end: "z");
 
         Assert.NotNull(result);
-        Assert.Empty(result);
+        Assert.Empty(result.Span.ToArray());
     }
 
     [Fact]
@@ -891,11 +891,11 @@ public async Task VectorSetRange_OpenStart()
         }
 
         // Get from beginning to "beta"
-        var result = await db.VectorSetRangeAsync(key, end: "beta");
+        using var result = await db.VectorSetRangeAsync(key, end: "beta");
 
         Assert.NotNull(result);
         Assert.Equal(2, result.Length);
-        Assert.Equal(new[] { "alpha", "beta" }, result.Select(r => (string?)r).ToArray());
+        Assert.Equal(new[] { "alpha", "beta" }, result.Span.ToArray().Select(r => (string?)r).ToArray());
     }
 
     [Fact]
@@ -917,11 +917,11 @@ public async Task VectorSetRange_OpenEnd()
         }
 
         // Get from "beta" to end
-        var result = await db.VectorSetRangeAsync(key, start: "beta");
+        using var result = await db.VectorSetRangeAsync(key, start: "beta");
 
         Assert.NotNull(result);
         Assert.Equal(2, result.Length);
-        Assert.Equal(new[] { "beta", "gamma" }, result.Select(r => (string?)r).ToArray());
+        Assert.Equal(new[] { "beta", "gamma" }, result.Span.ToArray().Select(r => (string?)r).ToArray());
     }
 
     [Fact]
@@ -943,13 +943,13 @@ public async Task VectorSetRange_SyncVsAsync()
         }
 
         // Call both sync and async
-        var syncResult = db.VectorSetRange(key, start: "m05", end: "m15");
-        var asyncResult = await db.VectorSetRangeAsync(key, start: "m05", end: "m15");
+        using var syncResult = db.VectorSetRange(key, start: "m05", end: "m15");
+        using var asyncResult = await db.VectorSetRangeAsync(key, start: "m05", end: "m15");
 
         Assert.NotNull(syncResult);
         Assert.NotNull(asyncResult);
         Assert.Equal(syncResult.Length, asyncResult.Length);
-        Assert.Equal(syncResult.Select(r => (string?)r), asyncResult.Select(r => (string?)r));
+        Assert.Equal(syncResult.Span.ToArray().Select(r => (string?)r), asyncResult.Span.ToArray().Select(r => (string?)r));
     }
 
     [Fact]
@@ -971,12 +971,12 @@ public async Task VectorSetRange_WithNumericLexOrder()
         }
 
         // Get all - should be in lexicographical order, not numeric
-        var result = await db.VectorSetRangeAsync(key);
+        using var result = await db.VectorSetRangeAsync(key);
 
         Assert.NotNull(result);
         Assert.Equal(5, result.Length);
         // Lexicographical order: "1", "10", "2", "20", "3"
-        Assert.Equal(new[] { "1", "10", "2", "20", "3" }, result.Select(r => (string?)r).ToArray());
+        Assert.Equal(new[] { "1", "10", "2", "20", "3" }, result.Span.ToArray().Select(r => (string?)r).ToArray());
     }
 
     [Fact]