Correct VLINKS return types #3404

VLINKS returns one collection per HNSW graph level. Preserve those levels for plain and WITHSCORES responses across all command APIs and decode both RESP2 arrays and RESP3 maps.

Author: hutiefang76

src/main/java/io/lettuce/core/AbstractRedisAsyncCommands.java

@@ -115,6 +115,7 @@
  * @author SeugnSu Kim
  * @author Yordan Tsintsov
  * @author dae won
+ * @author hutiefang76
  */
 @SuppressWarnings("unchecked")
 public abstract class AbstractRedisAsyncCommands<K, V> implements RedisAclAsyncCommands<K, V>, RedisHashAsyncCommands<K, V>,
@@ -2185,12 +2186,12 @@ public RedisFuture<VectorMetadata> vinfo(K key) {
     }
 
     @Override
-    public RedisFuture<List<V>> vlinks(K key, V element) {
+    public RedisFuture<List<List<V>>> vlinks(K key, V element) {
         return dispatch(vectorSetCommandBuilder.vlinks(key, element));
     }
 
     @Override
-    public RedisFuture<Map<V, Double>> vlinksWithScores(K key, V element) {
+    public RedisFuture<List<Map<V, Double>>> vlinksWithScores(K key, V element) {
         return dispatch(vectorSetCommandBuilder.vlinksWithScores(key, element));
     }
 

src/main/java/io/lettuce/core/AbstractRedisReactiveCommands.java

@@ -121,6 +121,7 @@
  * @author SeugnSu Kim
  * @author Yordan Tsintsov
  * @author dae won
+ * @author hutiefang76
  * @since 4.0
  */
 public abstract class AbstractRedisReactiveCommands<K, V>
@@ -2277,12 +2278,12 @@ public Mono<VectorMetadata> vinfo(K key) {
     }
 
     @Override
-    public Flux<V> vlinks(K key, V element) {
+    public Flux<List<V>> vlinks(K key, V element) {
         return createDissolvingFlux(() -> vectorSetCommandBuilder.vlinks(key, element));
     }
 
     @Override
-    public Mono<Map<V, Double>> vlinksWithScores(K key, V element) {
+    public Mono<List<Map<V, Double>>> vlinksWithScores(K key, V element) {
         return createMono(() -> vectorSetCommandBuilder.vlinksWithScores(key, element));
     }
 

src/main/java/io/lettuce/core/RedisVectorSetCommandBuilder.java

@@ -34,6 +34,7 @@
  * @param <K> Key type.
  * @param <V> Value type.
  * @author Tihomir Mateev
+ * @author hutiefang76
  * @since 6.7
  */
 public class RedisVectorSetCommandBuilder<K, V> extends BaseRedisCommandBuilder<K, V> {
@@ -251,11 +252,11 @@ public Command<K, V, VectorMetadata> vinfo(K key) {
      * @return a new {@link Command} that returns a list of elements that are linked to the specified element
      * @see <a href="https://redis.io/docs/latest/commands/vlinks/">Redis Documentation: VLINKS</a>
      */
-    public Command<K, V, List<V>> vlinks(K key, V element) {
+    public Command<K, V, List<List<V>>> vlinks(K key, V element) {
         notNullKey(key);
         notNullKey(element);
         CommandArgs<K, V> args = new CommandArgs<>(codec).addKey(key).addValue(element);
-        return createCommand(VLINKS, new ValueListOutput<>(codec), args);
+        return createCommand(VLINKS, new ValueListListOutput<>(codec), args);
     }
 
     /**
@@ -266,11 +267,11 @@ public Command<K, V, List<V>> vlinks(K key, V element) {
      * @return a new {@link Command} that returns a list of elements with their similarity scores
      * @see <a href="https://redis.io/docs/latest/commands/vlinks/">Redis Documentation: VLINKS</a>
      */
-    public Command<K, V, Map<V, Double>> vlinksWithScores(K key, V element) {
+    public Command<K, V, List<Map<V, Double>>> vlinksWithScores(K key, V element) {
         notNullKey(key);
         notNullKey(element);
         CommandArgs<K, V> args = new CommandArgs<>(codec).addKey(key).addValue(element).add(WITHSCORES);
-        return createCommand(VLINKS, new ValueDoubleMapOutput<>(codec), args);
+        return createCommand(VLINKS, new ValueDoubleMapListOutput<>(codec), args);
     }
 
     /**

src/main/java/io/lettuce/core/api/async/RedisVectorSetAsyncCommands.java

@@ -29,6 +29,7 @@
  * @param <K> Key type.
  * @param <V> Value type.
  * @author Tihomir Mateev
+ * @author hutiefang76
  * @see <a href="https://redis.io/docs/latest/develop/data-types/vector-sets/">Redis Vector Sets</a>
  * @since 6.7
  * @generated by io.lettuce.apigenerator.CreateAsyncApi
@@ -253,13 +254,12 @@ public interface RedisVectorSetAsyncCommands<K, V> {
      *
      * @param key the key of the vector set
      * @param element the name of the element in the vector set
-     * @return a list of elements that are linked to the specified element, or an empty list if the key or element does not
-     *         exist
+     * @return linked elements grouped by HNSW graph level, or an empty list if the key or element does not exist
      * @since 6.7
      * @see <a href="https://redis.io/docs/latest/commands/vlinks/">Redis Documentation: VLINKS</a>
      */
     @Experimental
-    RedisFuture<List<V>> vlinks(K key, V element);
+    RedisFuture<List<List<V>>> vlinks(K key, V element);
 
     /**
      * Returns the neighbors of the specified {@code element} in the HNSW graph along with their scores.
@@ -270,12 +270,13 @@ public interface RedisVectorSetAsyncCommands<K, V> {
      *
      * @param key the key of the vector set
      * @param element the name of the element in the vector set
-     * @return a list of elements with their similarity scores, or an empty list if the key or element does not exist
+     * @return linked elements and their scores grouped by HNSW graph level, or an empty list if the key or element does not
+     *         exist
      * @since 6.7
      * @see <a href="https://redis.io/docs/latest/commands/vlinks/">Redis Documentation: VLINKS</a>
      */
     @Experimental
-    RedisFuture<Map<V, Double>> vlinksWithScores(K key, V element);
+    RedisFuture<List<Map<V, Double>>> vlinksWithScores(K key, V element);
 
     /**
      * Returns a random element from the vector set stored at {@code key}. This command is useful for sampling elements for

src/main/java/io/lettuce/core/api/reactive/RedisVectorSetReactiveCommands.java

@@ -7,6 +7,7 @@
 package io.lettuce.core.api.reactive;
 
 import java.util.Map;
+import java.util.List;
 import io.lettuce.core.VAddArgs;
 import io.lettuce.core.VSimArgs;
 import io.lettuce.core.annotations.Experimental;
@@ -29,6 +30,7 @@
  * @param <K> Key type.
  * @param <V> Value type.
  * @author Tihomir Mateev
+ * @author hutiefang76
  * @see <a href="https://redis.io/docs/latest/develop/data-types/vector-sets/">Redis Vector Sets</a>
  * @since 6.7
  * @generated by io.lettuce.apigenerator.CreateReactiveApi
@@ -253,13 +255,12 @@ public interface RedisVectorSetReactiveCommands<K, V> {
      *
      * @param key the key of the vector set
      * @param element the name of the element in the vector set
-     * @return a list of elements that are linked to the specified element, or an empty list if the key or element does not
-     *         exist
+     * @return linked elements grouped by HNSW graph level, or an empty list if the key or element does not exist
      * @since 6.7
      * @see <a href="https://redis.io/docs/latest/commands/vlinks/">Redis Documentation: VLINKS</a>
      */
     @Experimental
-    Flux<V> vlinks(K key, V element);
+    Flux<List<V>> vlinks(K key, V element);
 
     /**
      * Returns the neighbors of the specified {@code element} in the HNSW graph along with their scores.
@@ -270,12 +271,13 @@ public interface RedisVectorSetReactiveCommands<K, V> {
      *
      * @param key the key of the vector set
      * @param element the name of the element in the vector set
-     * @return a list of elements with their similarity scores, or an empty list if the key or element does not exist
+     * @return linked elements and their scores grouped by HNSW graph level, or an empty list if the key or element does not
+     *         exist
      * @since 6.7
      * @see <a href="https://redis.io/docs/latest/commands/vlinks/">Redis Documentation: VLINKS</a>
      */
     @Experimental
-    Mono<Map<V, Double>> vlinksWithScores(K key, V element);
+    Mono<List<Map<V, Double>>> vlinksWithScores(K key, V element);
 
     /**
      * Returns a random element from the vector set stored at {@code key}. This command is useful for sampling elements for

src/main/java/io/lettuce/core/api/sync/RedisVectorSetCommands.java

@@ -28,6 +28,7 @@
  * @param <K> Key type.
  * @param <V> Value type.
  * @author Tihomir Mateev
+ * @author hutiefang76
  * @see <a href="https://redis.io/docs/latest/develop/data-types/vector-sets/">Redis Vector Sets</a>
  * @since 6.7
  * @generated by io.lettuce.apigenerator.CreateSyncApi
@@ -252,13 +253,12 @@ public interface RedisVectorSetCommands<K, V> {
      *
      * @param key the key of the vector set
      * @param element the name of the element in the vector set
-     * @return a list of elements that are linked to the specified element, or an empty list if the key or element does not
-     *         exist
+     * @return linked elements grouped by HNSW graph level, or an empty list if the key or element does not exist
      * @since 6.7
      * @see <a href="https://redis.io/docs/latest/commands/vlinks/">Redis Documentation: VLINKS</a>
      */
     @Experimental
-    List<V> vlinks(K key, V element);
+    List<List<V>> vlinks(K key, V element);
 
     /**
      * Returns the neighbors of the specified {@code element} in the HNSW graph along with their scores.
@@ -269,12 +269,13 @@ public interface RedisVectorSetCommands<K, V> {
      *
      * @param key the key of the vector set
      * @param element the name of the element in the vector set
-     * @return a list of elements with their similarity scores, or an empty list if the key or element does not exist
+     * @return linked elements and their scores grouped by HNSW graph level, or an empty list if the key or element does not
+     *         exist
      * @since 6.7
      * @see <a href="https://redis.io/docs/latest/commands/vlinks/">Redis Documentation: VLINKS</a>
      */
     @Experimental
-    Map<V, Double> vlinksWithScores(K key, V element);
+    List<Map<V, Double>> vlinksWithScores(K key, V element);
 
     /**
      * Returns a random element from the vector set stored at {@code key}. This command is useful for sampling elements for

src/main/java/io/lettuce/core/cluster/api/async/NodeSelectionVectorSetAsyncCommands.java

@@ -28,6 +28,7 @@
  * @param <K> Key type.
  * @param <V> Value type.
  * @author Tihomir Mateev
+ * @author hutiefang76
  * @see <a href="https://redis.io/docs/latest/develop/data-types/vector-sets/">Redis Vector Sets</a>
  * @since 6.7
  * @generated by io.lettuce.apigenerator.CreateAsyncNodeSelectionClusterApi
@@ -252,13 +253,12 @@ public interface NodeSelectionVectorSetAsyncCommands<K, V> {
      *
      * @param key the key of the vector set
      * @param element the name of the element in the vector set
-     * @return a list of elements that are linked to the specified element, or an empty list if the key or element does not
-     *         exist
+     * @return linked elements grouped by HNSW graph level, or an empty list if the key or element does not exist
      * @since 6.7
      * @see <a href="https://redis.io/docs/latest/commands/vlinks/">Redis Documentation: VLINKS</a>
      */
     @Experimental
-    AsyncExecutions<List<V>> vlinks(K key, V element);
+    AsyncExecutions<List<List<V>>> vlinks(K key, V element);
 
     /**
      * Returns the neighbors of the specified {@code element} in the HNSW graph along with their scores.
@@ -269,12 +269,13 @@ public interface NodeSelectionVectorSetAsyncCommands<K, V> {
      *
      * @param key the key of the vector set
      * @param element the name of the element in the vector set
-     * @return a list of elements with their similarity scores, or an empty list if the key or element does not exist
+     * @return linked elements and their scores grouped by HNSW graph level, or an empty list if the key or element does not
+     *         exist
      * @since 6.7
      * @see <a href="https://redis.io/docs/latest/commands/vlinks/">Redis Documentation: VLINKS</a>
      */
     @Experimental
-    AsyncExecutions<Map<V, Double>> vlinksWithScores(K key, V element);
+    AsyncExecutions<List<Map<V, Double>>> vlinksWithScores(K key, V element);
 
     /**
      * Returns a random element from the vector set stored at {@code key}. This command is useful for sampling elements for

src/main/java/io/lettuce/core/cluster/api/sync/NodeSelectionVectorSetCommands.java

@@ -28,6 +28,7 @@
  * @param <K> Key type.
  * @param <V> Value type.
  * @author Tihomir Mateev
+ * @author hutiefang76
  * @see <a href="https://redis.io/docs/latest/develop/data-types/vector-sets/">Redis Vector Sets</a>
  * @since 6.7
  * @generated by io.lettuce.apigenerator.CreateSyncNodeSelectionClusterApi
@@ -252,13 +253,12 @@ public interface NodeSelectionVectorSetCommands<K, V> {
      *
      * @param key the key of the vector set
      * @param element the name of the element in the vector set
-     * @return a list of elements that are linked to the specified element, or an empty list if the key or element does not
-     *         exist
+     * @return linked elements grouped by HNSW graph level, or an empty list if the key or element does not exist
      * @since 6.7
      * @see <a href="https://redis.io/docs/latest/commands/vlinks/">Redis Documentation: VLINKS</a>
      */
     @Experimental
-    Executions<List<V>> vlinks(K key, V element);
+    Executions<List<List<V>>> vlinks(K key, V element);
 
     /**
      * Returns the neighbors of the specified {@code element} in the HNSW graph along with their scores.
@@ -269,12 +269,13 @@ public interface NodeSelectionVectorSetCommands<K, V> {
      *
      * @param key the key of the vector set
      * @param element the name of the element in the vector set
-     * @return a list of elements with their similarity scores, or an empty list if the key or element does not exist
+     * @return linked elements and their scores grouped by HNSW graph level, or an empty list if the key or element does not
+     *         exist
      * @since 6.7
      * @see <a href="https://redis.io/docs/latest/commands/vlinks/">Redis Documentation: VLINKS</a>
      */
     @Experimental
-    Executions<Map<V, Double>> vlinksWithScores(K key, V element);
+    Executions<List<Map<V, Double>>> vlinksWithScores(K key, V element);
 
     /**
      * Returns a random element from the vector set stored at {@code key}. This command is useful for sampling elements for

src/main/java/io/lettuce/core/output/ValueDoubleMapListOutput.java

@@ -0,0 +1,70 @@
+/*
+ * Copyright 2026, Redis Ltd. and Contributors
+ * All rights reserved.
+ *
+ * Licensed under the MIT License.
+ */
+
+package io.lettuce.core.output;
+
+import io.lettuce.core.codec.RedisCodec;
+
+import java.nio.ByteBuffer;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * {@link List} of value-to-double maps output.
+ *
+ * @param <K> Key type.
+ * @param <V> Value type.
+ *
+ * @author hutiefang76
+ * @since 7.7
+ */
+public class ValueDoubleMapListOutput<K, V> extends CommandOutput<K, V, List<Map<V, Double>>> {
+
+    private boolean initialized;
+
+    private ValueDoubleMapOutput<K, V> nested;
+
+    public ValueDoubleMapListOutput(RedisCodec<K, V> codec) {
+        super(codec, Collections.emptyList());
+    }
+
+    @Override
+    public void set(ByteBuffer bytes) {
+        if (nested != null) {
+            nested.set(bytes);
+        }
+    }
+
+    @Override
+    public void set(double number) {
+        if (nested != null) {
+            nested.set(number);
+        }
+    }
+
+    @Override
+    public void complete(int depth) {
+        if (nested != null && !output.isEmpty()) {
+            output.set(output.size() - 1, nested.get());
+        }
+    }
+
+    @Override
+    public void multi(int count) {
+        if (!initialized) {
+            output = OutputFactory.newList(count);
+            initialized = true;
+            return;
+        }
+
+        nested = new ValueDoubleMapOutput<>(codec);
+        nested.multi(count);
+        output.add(nested.get());
+    }
+
+}