HRANDFIELD feature

src/StackExchange.Redis/Enums/RedisCommand.cs

@@ -65,6 +65,7 @@ internal enum RedisCommand
         HLEN,
         HMGET,
         HMSET,
+        HRANDFIELD,
         HSCAN,
         HSET,
         HSETNX,

src/StackExchange.Redis/Interfaces/IDatabase.cs

@@ -337,6 +337,32 @@ public interface IDatabase : IRedis, IDatabaseAsync
         /// <remarks>https://redis.io/commands/hlen</remarks>
         long HashLength(RedisKey key, CommandFlags flags = CommandFlags.None);
 
+        /// <summary>
+        /// Gets a random field from a hash.
+        /// </summary>
+        /// <param name="key">The key of the hash.</param>
+        /// <param name="flags">The flags to use for this operation.</param>
+        /// <returns>A random hash field name or <see cref="RedisValue.Null"/> if the hash is empty.</returns>
+        RedisValue HashRandomField(RedisKey key, CommandFlags flags = CommandFlags.None);
+
+        /// <summary>
+        /// Retrieves <paramref name="count"/> field names from a hash.
+        /// </summary>
+        /// <param name="key">The key of the hash.</param>
+        /// <param name="count">The number of fields to return.</param>
+        /// <param name="flags">The flags to use for this operation.</param>
+        /// <returns>An array of hash field names of size of at most <paramref name="count"/>.</returns>
+        RedisValue[] HashRandomFields(RedisKey key, long count, CommandFlags flags = CommandFlags.None);
+
+        /// <summary>
+        /// Retrieves <paramref name="count"/> field names from a hash.
+        /// </summary>
+        /// <param name="key">The key of the hash.</param>
+        /// <param name="count">The number of fields to return.</param>
+        /// <param name="flags">The flags to use for this operation.</param>
+        /// <returns>An array of hash entries of size of at most <paramref name="count"/>.</returns>
+        HashEntry[] HashRandomFieldsWithValues(RedisKey key, long count, CommandFlags flags = CommandFlags.None);
+
         /// <summary>
         /// The HSCAN command is used to incrementally iterate over a hash.
         /// </summary>

src/StackExchange.Redis/Interfaces/IDatabaseAsync.cs

@@ -324,6 +324,32 @@ public interface IDatabaseAsync : IRedisAsync
         /// <remarks>https://redis.io/commands/hlen</remarks>
         Task<long> HashLengthAsync(RedisKey key, CommandFlags flags = CommandFlags.None);
 
+        /// <summary>
+        /// Gets a random field from a hash.
+        /// </summary>
+        /// <param name="key">The key of the hash.</param>
+        /// <param name="flags">The flags to use for this operation.</param>
+        /// <returns>A random hash field name or <see cref="RedisValue.Null"/> if the hash is empty.</returns>
+        Task<RedisValue> HashRandomFieldAsync(RedisKey key, CommandFlags flags = CommandFlags.None);
+
+        /// <summary>
+        /// Retrieves <paramref name="count"/> field names from a hash.
+        /// </summary>
+        /// <param name="key">The key of the hash.</param>
+        /// <param name="count">The number of fields to return.</param>
+        /// <param name="flags">The flags to use for this operation.</param>
+        /// <returns>An array of hash field names of size of at most <paramref name="count"/>.</returns>
+        Task<RedisValue[]> HashRandomFieldsAsync(RedisKey key, long count, CommandFlags flags = CommandFlags.None);
+
+        /// <summary>
+        /// Retrieves <paramref name="count"/> field names from a hash.
+        /// </summary>
+        /// <param name="key">The key of the hash.</param>
+        /// <param name="count">The number of fields to return.</param>
+        /// <param name="flags">The flags to use for this operation.</param>
+        /// <returns>An array of hash entries of size of at most <paramref name="count"/>.</returns>
+        Task<HashEntry[]> HashRandomFieldsWithValuesAsync(RedisKey key, long count, CommandFlags flags = CommandFlags.None);
+
         /// <summary>
         /// The HSCAN command is used to incrementally iterate over a hash.
         /// Note: to resume an iteration via <i>cursor</i>, cast the original enumerable or enumerator to <see cref="IScanningCursor"/>.

src/StackExchange.Redis/KeyspaceIsolation/DatabaseWrapper.cs

@@ -93,6 +93,15 @@ public RedisValue[] HashKeys(RedisKey key, CommandFlags flags = CommandFlags.Non
         public long HashLength(RedisKey key, CommandFlags flags = CommandFlags.None) =>
             Inner.HashLength(ToInner(key), flags);
 
+        public RedisValue HashRandomField(RedisKey key, CommandFlags flags = CommandFlags.None) =>
+            Inner.HashRandomField(ToInner(key), flags);
+
+        public RedisValue[] HashRandomFields(RedisKey key, long count, CommandFlags flags = CommandFlags.None) =>
+            Inner.HashRandomFields(ToInner(key), count, flags);
+
+        public HashEntry[] HashRandomFieldsWithValues(RedisKey key, long count, CommandFlags flags = CommandFlags.None) =>
+            Inner.HashRandomFieldsWithValues(ToInner(key), count, flags);
+
         public bool HashSet(RedisKey key, RedisValue hashField, RedisValue value, When when = When.Always, CommandFlags flags = CommandFlags.None) =>
             Inner.HashSet(ToInner(key), hashField, value, when, flags);
 

src/StackExchange.Redis/KeyspaceIsolation/WrapperBase.cs

@@ -96,6 +96,16 @@ public Task<RedisValue[]> HashKeysAsync(RedisKey key, CommandFlags flags = Comma
         public Task<long> HashLengthAsync(RedisKey key, CommandFlags flags = CommandFlags.None) =>
             Inner.HashLengthAsync(ToInner(key), flags);
 
+        public Task<RedisValue> HashRandomFieldAsync(RedisKey key, CommandFlags flags = CommandFlags.None) =>
+            Inner.HashRandomFieldAsync(ToInner(key), flags);
+
+        public Task<RedisValue[]> HashRandomFieldsAsync(RedisKey key, long count, CommandFlags flags = CommandFlags.None) =>
+            Inner.HashRandomFieldsAsync(ToInner(key), count, flags);
+
+        public Task<HashEntry[]> HashRandomFieldsWithValuesAsync(RedisKey key, long count, CommandFlags flags = CommandFlags.None) =>
+            Inner.HashRandomFieldsWithValuesAsync(ToInner(key), count, flags);
+
+
         public IAsyncEnumerable<HashEntry> HashScanAsync(RedisKey key, RedisValue pattern, int pageSize, long cursor, int pageOffset, CommandFlags flags) =>
             Inner.HashScanAsync(ToInner(key), pattern, pageSize, cursor, pageOffset, flags);
 

src/StackExchange.Redis/PublicAPI.Shipped.txt

@@ -505,6 +505,9 @@ StackExchange.Redis.IDatabase.HashIncrement(StackExchange.Redis.RedisKey key, St
 StackExchange.Redis.IDatabase.HashIncrement(StackExchange.Redis.RedisKey key, StackExchange.Redis.RedisValue hashField, long value = 1, StackExchange.Redis.CommandFlags flags = StackExchange.Redis.CommandFlags.None) -> long
 StackExchange.Redis.IDatabase.HashKeys(StackExchange.Redis.RedisKey key, StackExchange.Redis.CommandFlags flags = StackExchange.Redis.CommandFlags.None) -> StackExchange.Redis.RedisValue[]!
 StackExchange.Redis.IDatabase.HashLength(StackExchange.Redis.RedisKey key, StackExchange.Redis.CommandFlags flags = StackExchange.Redis.CommandFlags.None) -> long
+StackExchange.Redis.IDatabase.HashRandomField(StackExchange.Redis.RedisKey key, StackExchange.Redis.CommandFlags flags = StackExchange.Redis.CommandFlags.None) -> StackExchange.Redis.RedisValue
+StackExchange.Redis.IDatabase.HashRandomFields(StackExchange.Redis.RedisKey key, long count, StackExchange.Redis.CommandFlags flags = StackExchange.Redis.CommandFlags.None) -> StackExchange.Redis.RedisValue[]!
+StackExchange.Redis.IDatabase.HashRandomFieldsWithValues(StackExchange.Redis.RedisKey key, long count, StackExchange.Redis.CommandFlags flags = StackExchange.Redis.CommandFlags.None) -> StackExchange.Redis.HashEntry[]!
 StackExchange.Redis.IDatabase.HashScan(StackExchange.Redis.RedisKey key, StackExchange.Redis.RedisValue pattern = default(StackExchange.Redis.RedisValue), int pageSize = 250, long cursor = 0, int pageOffset = 0, StackExchange.Redis.CommandFlags flags = StackExchange.Redis.CommandFlags.None) -> System.Collections.Generic.IEnumerable<StackExchange.Redis.HashEntry>!
 StackExchange.Redis.IDatabase.HashScan(StackExchange.Redis.RedisKey key, StackExchange.Redis.RedisValue pattern, int pageSize, StackExchange.Redis.CommandFlags flags) -> System.Collections.Generic.IEnumerable<StackExchange.Redis.HashEntry>!
 StackExchange.Redis.IDatabase.HashSet(StackExchange.Redis.RedisKey key, StackExchange.Redis.HashEntry[]! hashFields, StackExchange.Redis.CommandFlags flags = StackExchange.Redis.CommandFlags.None) -> void
@@ -706,6 +709,9 @@ StackExchange.Redis.IDatabaseAsync.HashIncrementAsync(StackExchange.Redis.RedisK
 StackExchange.Redis.IDatabaseAsync.HashIncrementAsync(StackExchange.Redis.RedisKey key, StackExchange.Redis.RedisValue hashField, long value = 1, StackExchange.Redis.CommandFlags flags = StackExchange.Redis.CommandFlags.None) -> System.Threading.Tasks.Task<long>!
 StackExchange.Redis.IDatabaseAsync.HashKeysAsync(StackExchange.Redis.RedisKey key, StackExchange.Redis.CommandFlags flags = StackExchange.Redis.CommandFlags.None) -> System.Threading.Tasks.Task<StackExchange.Redis.RedisValue[]!>!
 StackExchange.Redis.IDatabaseAsync.HashLengthAsync(StackExchange.Redis.RedisKey key, StackExchange.Redis.CommandFlags flags = StackExchange.Redis.CommandFlags.None) -> System.Threading.Tasks.Task<long>!
+StackExchange.Redis.IDatabaseAsync.HashRandomFieldAsync(StackExchange.Redis.RedisKey key, StackExchange.Redis.CommandFlags flags = StackExchange.Redis.CommandFlags.None) -> System.Threading.Tasks.Task<StackExchange.Redis.RedisValue>!
+StackExchange.Redis.IDatabaseAsync.HashRandomFieldsAsync(StackExchange.Redis.RedisKey key, long count, StackExchange.Redis.CommandFlags flags = StackExchange.Redis.CommandFlags.None) -> System.Threading.Tasks.Task<StackExchange.Redis.RedisValue[]!>!
+StackExchange.Redis.IDatabaseAsync.HashRandomFieldsWithValuesAsync(StackExchange.Redis.RedisKey key, long count, StackExchange.Redis.CommandFlags flags = StackExchange.Redis.CommandFlags.None) -> System.Threading.Tasks.Task<StackExchange.Redis.HashEntry[]!>!
 StackExchange.Redis.IDatabaseAsync.HashScanAsync(StackExchange.Redis.RedisKey key, StackExchange.Redis.RedisValue pattern = default(StackExchange.Redis.RedisValue), int pageSize = 250, long cursor = 0, int pageOffset = 0, StackExchange.Redis.CommandFlags flags = StackExchange.Redis.CommandFlags.None) -> System.Collections.Generic.IAsyncEnumerable<StackExchange.Redis.HashEntry>!
 StackExchange.Redis.IDatabaseAsync.HashSetAsync(StackExchange.Redis.RedisKey key, StackExchange.Redis.HashEntry[]! hashFields, StackExchange.Redis.CommandFlags flags = StackExchange.Redis.CommandFlags.None) -> System.Threading.Tasks.Task!
 StackExchange.Redis.IDatabaseAsync.HashSetAsync(StackExchange.Redis.RedisKey key, StackExchange.Redis.RedisValue hashField, StackExchange.Redis.RedisValue value, StackExchange.Redis.When when = StackExchange.Redis.When.Always, StackExchange.Redis.CommandFlags flags = StackExchange.Redis.CommandFlags.None) -> System.Threading.Tasks.Task<bool>!

src/StackExchange.Redis/RedisDatabase.cs

@@ -402,12 +402,48 @@ public long HashLength(RedisKey key, CommandFlags flags = CommandFlags.None)
             return ExecuteSync(msg, ResultProcessor.Int64);
         }
 
+        public RedisValue HashRandomField(RedisKey key, CommandFlags flags = CommandFlags.None)
+        {
+            var msg = Message.Create(Database, flags, RedisCommand.HRANDFIELD, key);
+            return ExecuteSync(msg, ResultProcessor.RedisValue);
+        }
+
+        public RedisValue[] HashRandomFields(RedisKey key, long count, CommandFlags flags = CommandFlags.None)
+        {
+            var msg = Message.Create(Database, flags, RedisCommand.HRANDFIELD, key, count);
+            return ExecuteSync(msg, ResultProcessor.RedisValueArray, defaultValue: Array.Empty<RedisValue>());
+        }
+
+        public HashEntry[] HashRandomFieldsWithValues(RedisKey key, long count, CommandFlags flags = CommandFlags.None)
+        {
+            var msg = Message.Create(Database, flags, RedisCommand.HRANDFIELD, key, count, RedisLiterals.WITHVALUES);
+            return ExecuteSync(msg, ResultProcessor.HashEntryArray, defaultValue: Array.Empty<HashEntry>());
+        }
+
         public Task<long> HashLengthAsync(RedisKey key, CommandFlags flags = CommandFlags.None)
         {
             var msg = Message.Create(Database, flags, RedisCommand.HLEN, key);
             return ExecuteAsync(msg, ResultProcessor.Int64);
         }
 
+        public Task<RedisValue> HashRandomFieldAsync(RedisKey key, CommandFlags flags = CommandFlags.None)
+        {
+            var msg = Message.Create(Database, flags, RedisCommand.HRANDFIELD, key);
+            return ExecuteAsync(msg, ResultProcessor.RedisValue);
+        }
+
+        public Task<RedisValue[]> HashRandomFieldsAsync(RedisKey key, long count, CommandFlags flags = CommandFlags.None)
+        {
+            var msg = Message.Create(Database, flags, RedisCommand.HRANDFIELD, key, count);
+            return ExecuteAsync(msg, ResultProcessor.RedisValueArray, defaultValue: Array.Empty<RedisValue>());
+        }
+
+        public Task<HashEntry[]> HashRandomFieldsWithValuesAsync(RedisKey key, long count, CommandFlags flags = CommandFlags.None)
+        {
+            var msg = Message.Create(Database, flags, RedisCommand.HRANDFIELD, key, count, RedisLiterals.WITHVALUES);
+            return ExecuteAsync(msg, ResultProcessor.HashEntryArray, defaultValue: Array.Empty<HashEntry>());
+        }
+
         IEnumerable<HashEntry> IDatabase.HashScan(RedisKey key, RedisValue pattern, int pageSize, CommandFlags flags)
             => HashScanAsync(key, pattern, pageSize, CursorUtils.Origin, 0, flags);
 
@@ -3620,7 +3656,7 @@ private Message GetStreamPendingMessagesMessage(RedisKey key, RedisValue groupNa
 
             if (consumerName != RedisValue.Null)
             {
-                values[4] = consumerName; 
+                values[4] = consumerName;
             }
 
             return Message.Create(Database,

src/StackExchange.Redis/RedisLiterals.cs

@@ -109,6 +109,7 @@ public static readonly RedisValue
             TYPE = "TYPE",
             WEIGHTS = "WEIGHTS",
             WITHSCORES = "WITHSCORES",
+            WITHVALUES = "WITHVALUES",
             XOR = "XOR",
             XX = "XX",
 

tests/StackExchange.Redis.Tests/Hashes.cs

@@ -596,5 +596,79 @@ public async Task TestWhenAlwaysAsync()
                 Assert.False(result4, "Duplicate se key 1 variant");
             }
         }
+
+        [Fact]
+        public async Task HashRandomFieldAsync()
+        {
+            using var muxer = Create();
+            var db = muxer.GetDatabase();
+            Skip.IfBelow(muxer, RedisFeatures.v6_2_0);
+            var hashKey = Me();
+            var items = new HashEntry[] {new("new york", "yankees"), new("baltimore","orioles"), new("boston","red sox"), new("Tampa Bay","rays"), new("Toronto", "blue jays") };
+            await db.HashSetAsync(hashKey, items);
+
+            var singleField = await db.HashRandomFieldAsync(hashKey);
+            var multiFields = await db.HashRandomFieldsAsync(hashKey, 3);
+            var withValues = await db.HashRandomFieldsWithValuesAsync(hashKey, 3);
+            Assert.Equal(3, multiFields.Length);
+            Assert.Equal(3, withValues.Length);
+            Assert.Contains(items, x =>x.Name == singleField);
+
+            foreach (var field in multiFields)
+            {
+                Assert.Contains(items, x =>x.Name == field);
+            }
+
+            foreach (var field in withValues)
+            {
+                Assert.Contains(items, x =>x.Name == field.Name);
+            }
+        }
+
+        [Fact]
+        public void HashRandomField()
+        {
+            using var muxer = Create();
+            var db = muxer.GetDatabase();
+            Skip.IfBelow(muxer, RedisFeatures.v6_2_0);
+            var hashKey = Me();
+            var items = new HashEntry[] {new("new york", "yankees"), new("baltimore","orioles"), new("boston","red sox"), new("Tampa Bay","rays"), new("Toronto", "blue jays") };
+            db.HashSet(hashKey, items);
+
+            var singleField = db.HashRandomField(hashKey);
+            var multiFields = db.HashRandomFields(hashKey, 3);
+            var withValues = db.HashRandomFieldsWithValues(hashKey, 3);
+            Assert.Equal(3, multiFields.Length);
+            Assert.Equal(3, withValues.Length);
+            Assert.Contains(items, x =>x.Name == singleField);
+
+            foreach (var field in multiFields)
+            {
+                Assert.Contains(items, x =>x.Name == field);
+            }
+
+            foreach (var field in withValues)
+            {
+                Assert.Contains(items, x =>x.Name == field.Name);
+            }
+        }
+
+        [Fact]
+        public void HashRandomFieldEmptyHash()
+        {
+            using var muxer = Create();
+            var db = muxer.GetDatabase();
+            Skip.IfBelow(muxer, RedisFeatures.v6_2_0);
+            var hashKey = Me();
+
+            var singleField = db.HashRandomField(hashKey);
+            var multiFields = db.HashRandomFields(hashKey, 3);
+            var withValues = db.HashRandomFieldsWithValues(hashKey, 3);
+
+            Assert.Equal(RedisValue.Null, singleField);
+            Assert.Empty(multiFields);
+            Assert.Empty(withValues);
+
+        }
     }
 }