Merge branch 'redis:master' into master

Author: gh73962

.github/workflows/spellcheck.yml

@@ -8,7 +8,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
       - name: Check Spelling
-        uses: rojopolis/spellcheck-github-actions@0.47.0
+        uses: rojopolis/spellcheck-github-actions@0.48.0
         with:
           config_path: .github/spellcheck-settings.yml
           task_name: Markdown

CONTRIBUTING.md

@@ -112,3 +112,7 @@ The core team regularly looks at pull requests. We will provide
 feedback as soon as possible. After receiving our feedback, please respond
 within two weeks. After that time, we may close your PR if it isn't
 showing any activity.
+
+## Support
+
+Maintainers can provide limited support to contributors on discord: https://discord.gg/W4txy5AeKM

README.md

@@ -3,8 +3,14 @@
 [![build workflow](https://github.com/redis/go-redis/actions/workflows/build.yml/badge.svg)](https://github.com/redis/go-redis/actions)
 [![PkgGoDev](https://pkg.go.dev/badge/github.com/redis/go-redis/v9)](https://pkg.go.dev/github.com/redis/go-redis/v9?tab=doc)
 [![Documentation](https://img.shields.io/badge/redis-documentation-informational)](https://redis.uptrace.dev/)
+[![Go Report Card](https://goreportcard.com/badge/github.com/redis/go-redis/v9)](https://goreportcard.com/report/github.com/redis/go-redis/v9)
 [![codecov](https://codecov.io/github/redis/go-redis/graph/badge.svg?token=tsrCZKuSSw)](https://codecov.io/github/redis/go-redis)
-[![Chat](https://discordapp.com/api/guilds/752070105847955518/widget.png)](https://discord.gg/rWtp5Aj)
+
+[![Discord](https://img.shields.io/discord/697882427875393627.svg?style=social&logo=discord)](https://discord.gg/W4txy5AeKM)
+[![Twitch](https://img.shields.io/twitch/status/redisinc?style=social)](https://www.twitch.tv/redisinc)
+[![YouTube](https://img.shields.io/youtube/channel/views/UCD78lHSwYqMlyetR0_P4Vig?style=social)](https://www.youtube.com/redisinc)
+[![Twitter](https://img.shields.io/twitter/follow/redisinc?style=social)](https://twitter.com/redisinc)
+[![Stack Exchange questions](https://img.shields.io/stackexchange/stackoverflow/t/go-redis?style=social&logo=stackoverflow&label=Stackoverflow)](https://stackoverflow.com/questions/tagged/go-redis)
 
 > go-redis is the official Redis client library for the Go programming language. It offers a straightforward interface for interacting with Redis servers. 
 
@@ -44,7 +50,7 @@ in the `go.mod` to `go 1.24` in one of the next releases.
 ## Resources
 
 - [Discussions](https://github.com/redis/go-redis/discussions)
-- [Chat](https://discord.gg/rWtp5Aj)
+- [Chat](https://discord.gg/W4txy5AeKM)
 - [Reference](https://pkg.go.dev/github.com/redis/go-redis/v9)
 - [Examples](https://pkg.go.dev/github.com/redis/go-redis/v9#pkg-examples)
 

command.go

@@ -3831,7 +3831,8 @@ func (cmd *MapStringStringSliceCmd) readReply(rd *proto.Reader) error {
 }
 
 // -----------------------------------------------------------------------
-// MapStringInterfaceCmd represents a command that returns a map of strings to interface{}.
+
+// MapMapStringInterfaceCmd represents a command that returns a map of strings to interface{}.
 type MapMapStringInterfaceCmd struct {
 	baseCmd
 	val map[string]interface{}

commands.go

@@ -81,6 +81,8 @@ func appendArg(dst []interface{}, arg interface{}) []interface{} {
 		return dst
 	case time.Time, time.Duration, encoding.BinaryMarshaler, net.IP:
 		return append(dst, arg)
+	case nil:
+		return dst
 	default:
 		// scan struct field
 		v := reflect.ValueOf(arg)
@@ -332,7 +334,7 @@ func (info LibraryInfo) Validate() error {
 	return nil
 }
 
-// Hello Set the resp protocol used.
+// Hello sets the resp protocol used.
 func (c statefulCmdable) Hello(ctx context.Context,
 	ver int, username, password, clientName string,
 ) *MapStringInterfaceCmd {

commands_test.go

@@ -7255,6 +7255,17 @@ var _ = Describe("Commands", func() {
 			Expect(err).NotTo(HaveOccurred())
 			Expect(vals).To(Equal([]interface{}{int64(12), proto.RedisError("error"), "abc"}))
 		})
+
+		It("returns empty values when args are nil", func() {
+			vals, err := client.Eval(
+				ctx,
+				"return {ARGV[1]}",
+				[]string{},
+				nil,
+			).Result()
+			Expect(err).NotTo(HaveOccurred())
+			Expect(vals).To(BeEmpty())
+		})
 	})
 
 	Describe("EvalRO", func() {
@@ -7278,6 +7289,17 @@ var _ = Describe("Commands", func() {
 			Expect(err).NotTo(HaveOccurred())
 			Expect(vals).To(Equal([]interface{}{int64(12), proto.RedisError("error"), "abc"}))
 		})
+
+		It("returns empty values when args are nil", func() {
+			vals, err := client.EvalRO(
+				ctx,
+				"return {ARGV[1]}",
+				[]string{},
+				nil,
+			).Result()
+			Expect(err).NotTo(HaveOccurred())
+			Expect(vals).To(BeEmpty())
+		})
 	})
 
 	Describe("Functions", func() {

doctests/home_json_example_test.go

@@ -152,6 +152,32 @@ func ExampleClient_search_json() {
 	// >>> Tel Aviv
 	// STEP_END
 
+	// STEP_START query2count_only
+	citiesResult2, err := rdb.FTSearchWithArgs(
+		ctx,
+		"idx:users",
+		"Paul",
+		&redis.FTSearchOptions{
+			Return: []redis.FTSearchReturn{
+				{
+					FieldName: "$.city",
+					As:        "city",
+				},
+			},
+			CountOnly: true,
+		},
+	).Result()
+
+	if err != nil {
+		panic(err)
+	}
+
+	// The `Total` field has the correct number of docs found
+	// by the query but the `Docs` slice is empty.
+	fmt.Println(len(citiesResult2.Docs)) // >>> 0
+	fmt.Println(citiesResult2.Total)     // >>> 2
+	// STEP_END
+
 	// STEP_START query3
 	aggOptions := redis.FTAggregateOptions{
 		GroupBy: []redis.FTAggregateGroupBy{
@@ -196,6 +222,112 @@ func ExampleClient_search_json() {
 	// {1 [{user:3 <nil> <nil> <nil> map[$:{"age":35,"city":"Tel Aviv","email":"paul.zamir@example.com","name":"Paul Zamir"}]}]}
 	// London
 	// Tel Aviv
+	// 0
+	// 2
 	// London - 1
 	// Tel Aviv - 2
 }
+
+func ExampleClient_search_hash() {
+	ctx := context.Background()
+
+	rdb := redis.NewClient(&redis.Options{
+		Addr:     "localhost:6379",
+		Password: "", // no password docs
+		DB:       0,  // use default DB
+		Protocol: 2,
+	})
+
+	// REMOVE_START
+	rdb.Del(ctx, "huser:1", "huser:2", "huser:3")
+	rdb.FTDropIndex(ctx, "hash-idx:users")
+	// REMOVE_END
+
+	// STEP_START make_hash_index
+	_, err := rdb.FTCreate(
+		ctx,
+		"hash-idx:users",
+		// Options:
+		&redis.FTCreateOptions{
+			OnHash: true,
+			Prefix: []interface{}{"huser:"},
+		},
+		// Index schema fields:
+		&redis.FieldSchema{
+			FieldName: "name",
+			FieldType: redis.SearchFieldTypeText,
+		},
+		&redis.FieldSchema{
+			FieldName: "city",
+			FieldType: redis.SearchFieldTypeTag,
+		},
+		&redis.FieldSchema{
+			FieldName: "age",
+			FieldType: redis.SearchFieldTypeNumeric,
+		},
+	).Result()
+
+	if err != nil {
+		panic(err)
+	}
+	// STEP_END
+
+	user1 := map[string]interface{}{
+		"name":  "Paul John",
+		"email": "paul.john@example.com",
+		"age":   42,
+		"city":  "London",
+	}
+
+	user2 := map[string]interface{}{
+		"name":  "Eden Zamir",
+		"email": "eden.zamir@example.com",
+		"age":   29,
+		"city":  "Tel Aviv",
+	}
+
+	user3 := map[string]interface{}{
+		"name":  "Paul Zamir",
+		"email": "paul.zamir@example.com",
+		"age":   35,
+		"city":  "Tel Aviv",
+	}
+
+	// STEP_START add_hash_data
+	_, err = rdb.HSet(ctx, "huser:1", user1).Result()
+
+	if err != nil {
+		panic(err)
+	}
+
+	_, err = rdb.HSet(ctx, "huser:2", user2).Result()
+
+	if err != nil {
+		panic(err)
+	}
+
+	_, err = rdb.HSet(ctx, "huser:3", user3).Result()
+
+	if err != nil {
+		panic(err)
+	}
+	// STEP_END
+
+	// STEP_START query1_hash
+	findPaulHashResult, err := rdb.FTSearch(
+		ctx,
+		"hash-idx:users",
+		"Paul @age:[30 40]",
+	).Result()
+
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Println(findPaulHashResult)
+	// >>> {1 [{huser:3 <nil> <nil> <nil> map[age:35 city:Tel Aviv...
+	// STEP_END
+
+	// Output:
+	// {1 [{huser:3 <nil> <nil> <nil> map[age:35 city:Tel Aviv email:paul.zamir@example.com name:Paul Zamir]}]}
+}

hash_commands.go

@@ -13,6 +13,7 @@ type HashCmdable interface {
 	HGetDel(ctx context.Context, key string, fields ...string) *StringSliceCmd
 	HGetEX(ctx context.Context, key string, fields ...string) *StringSliceCmd
 	HGetEXWithArgs(ctx context.Context, key string, options *HGetEXOptions, fields ...string) *StringSliceCmd
+	HIncrBy(ctx context.Context, key, field string, incr int64) *IntCmd
 	HIncrByFloat(ctx context.Context, key, field string, incr float64) *FloatCmd
 	HKeys(ctx context.Context, key string) *StringSliceCmd
 	HLen(ctx context.Context, key string) *IntCmd
@@ -223,7 +224,10 @@ type HExpireArgs struct {
 
 // HExpire - Sets the expiration time for specified fields in a hash in seconds.
 // The command constructs an argument list starting with "HEXPIRE", followed by the key, duration, any conditional flags, and the specified fields.
-// For more information - https://redis.io/commands/hexpire/
+// Available since Redis 7.4 CE.
+// For more information refer to [HEXPIRE Documentation].
+//
+// [HEXPIRE Documentation]: https://redis.io/commands/hexpire/
 func (c cmdable) HExpire(ctx context.Context, key string, expiration time.Duration, fields ...string) *IntSliceCmd {
 	args := []interface{}{"HEXPIRE", key, formatSec(ctx, expiration), "FIELDS", len(fields)}
 
@@ -238,7 +242,10 @@ func (c cmdable) HExpire(ctx context.Context, key string, expiration time.Durati
 // HExpireWithArgs - Sets the expiration time for specified fields in a hash in seconds.
 // It requires a key, an expiration duration, a struct with boolean flags for conditional expiration settings (NX, XX, GT, LT), and a list of fields.
 // The command constructs an argument list starting with "HEXPIRE", followed by the key, duration, any conditional flags, and the specified fields.
-// For more information - https://redis.io/commands/hexpire/
+// Available since Redis 7.4 CE.
+// For more information refer to [HEXPIRE Documentation].
+//
+// [HEXPIRE Documentation]: https://redis.io/commands/hexpire/
 func (c cmdable) HExpireWithArgs(ctx context.Context, key string, expiration time.Duration, expirationArgs HExpireArgs, fields ...string) *IntSliceCmd {
 	args := []interface{}{"HEXPIRE", key, formatSec(ctx, expiration)}
 
@@ -267,7 +274,10 @@ func (c cmdable) HExpireWithArgs(ctx context.Context, key string, expiration tim
 // HPExpire - Sets the expiration time for specified fields in a hash in milliseconds.
 // Similar to HExpire, it accepts a key, an expiration duration in milliseconds, a struct with expiration condition flags, and a list of fields.
 // The command modifies the standard time.Duration to milliseconds for the Redis command.
-// For more information - https://redis.io/commands/hpexpire/
+// Available since Redis 7.4 CE.
+// For more information refer to [HPEXPIRE Documentation].
+//
+// [HPEXPIRE Documentation]: https://redis.io/commands/hpexpire/
 func (c cmdable) HPExpire(ctx context.Context, key string, expiration time.Duration, fields ...string) *IntSliceCmd {
 	args := []interface{}{"HPEXPIRE", key, formatMs(ctx, expiration), "FIELDS", len(fields)}
 
@@ -279,6 +289,13 @@ func (c cmdable) HPExpire(ctx context.Context, key string, expiration time.Durat
 	return cmd
 }
 
+// HPExpireWithArgs - Sets the expiration time for specified fields in a hash in milliseconds.
+// It requires a key, an expiration duration, a struct with boolean flags for conditional expiration settings (NX, XX, GT, LT), and a list of fields.
+// The command constructs an argument list starting with "HPEXPIRE", followed by the key, duration, any conditional flags, and the specified fields.
+// Available since Redis 7.4 CE.
+// For more information refer to [HPEXPIRE Documentation].
+//
+// [HPEXPIRE Documentation]: https://redis.io/commands/hpexpire/
 func (c cmdable) HPExpireWithArgs(ctx context.Context, key string, expiration time.Duration, expirationArgs HExpireArgs, fields ...string) *IntSliceCmd {
 	args := []interface{}{"HPEXPIRE", key, formatMs(ctx, expiration)}
 
@@ -307,7 +324,10 @@ func (c cmdable) HPExpireWithArgs(ctx context.Context, key string, expiration ti
 // HExpireAt - Sets the expiration time for specified fields in a hash to a UNIX timestamp in seconds.
 // Takes a key, a UNIX timestamp, a struct of conditional flags, and a list of fields.
 // The command sets absolute expiration times based on the UNIX timestamp provided.
-// For more information - https://redis.io/commands/hexpireat/
+// Available since Redis 7.4 CE.
+// For more information refer to [HExpireAt Documentation].
+//
+// [HExpireAt Documentation]: https://redis.io/commands/hexpireat/
 func (c cmdable) HExpireAt(ctx context.Context, key string, tm time.Time, fields ...string) *IntSliceCmd {
 
 	args := []interface{}{"HEXPIREAT", key, tm.Unix(), "FIELDS", len(fields)}
@@ -347,7 +367,10 @@ func (c cmdable) HExpireAtWithArgs(ctx context.Context, key string, tm time.Time
 
 // HPExpireAt - Sets the expiration time for specified fields in a hash to a UNIX timestamp in milliseconds.
 // Similar to HExpireAt but for timestamps in milliseconds. It accepts the same parameters and adjusts the UNIX time to milliseconds.
-// For more information - https://redis.io/commands/hpexpireat/
+// Available since Redis 7.4 CE.
+// For more information refer to [HExpireAt Documentation].
+//
+// [HExpireAt Documentation]: https://redis.io/commands/hexpireat/
 func (c cmdable) HPExpireAt(ctx context.Context, key string, tm time.Time, fields ...string) *IntSliceCmd {
 	args := []interface{}{"HPEXPIREAT", key, tm.UnixNano() / int64(time.Millisecond), "FIELDS", len(fields)}
 
@@ -387,7 +410,10 @@ func (c cmdable) HPExpireAtWithArgs(ctx context.Context, key string, tm time.Tim
 // HPersist - Removes the expiration time from specified fields in a hash.
 // Accepts a key and the fields themselves.
 // This command ensures that each field specified will have its expiration removed if present.
-// For more information - https://redis.io/commands/hpersist/
+// Available since Redis 7.4 CE.
+// For more information refer to [HPersist Documentation].
+//
+// [HPersist Documentation]: https://redis.io/commands/hpersist/
 func (c cmdable) HPersist(ctx context.Context, key string, fields ...string) *IntSliceCmd {
 	args := []interface{}{"HPERSIST", key, "FIELDS", len(fields)}
 
@@ -402,6 +428,10 @@ func (c cmdable) HPersist(ctx context.Context, key string, fields ...string) *In
 // HExpireTime - Retrieves the expiration time for specified fields in a hash as a UNIX timestamp in seconds.
 // Requires a key and the fields themselves to fetch their expiration timestamps.
 // This command returns the expiration times for each field or error/status codes for each field as specified.
+// Available since Redis 7.4 CE.
+// For more information refer to [HExpireTime Documentation].
+//
+// [HExpireTime Documentation]: https://redis.io/commands/hexpiretime/
 // For more information - https://redis.io/commands/hexpiretime/
 func (c cmdable) HExpireTime(ctx context.Context, key string, fields ...string) *IntSliceCmd {
 	args := []interface{}{"HEXPIRETIME", key, "FIELDS", len(fields)}
@@ -417,6 +447,10 @@ func (c cmdable) HExpireTime(ctx context.Context, key string, fields ...string)
 // HPExpireTime - Retrieves the expiration time for specified fields in a hash as a UNIX timestamp in milliseconds.
 // Similar to HExpireTime, adjusted for timestamps in milliseconds. It requires the same parameters.
 // Provides the expiration timestamp for each field in milliseconds.
+// Available since Redis 7.4 CE.
+// For more information refer to [HExpireTime Documentation].
+//
+// [HExpireTime Documentation]: https://redis.io/commands/hexpiretime/
 // For more information - https://redis.io/commands/hexpiretime/
 func (c cmdable) HPExpireTime(ctx context.Context, key string, fields ...string) *IntSliceCmd {
 	args := []interface{}{"HPEXPIRETIME", key, "FIELDS", len(fields)}
@@ -432,7 +466,10 @@ func (c cmdable) HPExpireTime(ctx context.Context, key string, fields ...string)
 // HTTL - Retrieves the remaining time to live for specified fields in a hash in seconds.
 // Requires a key and the fields themselves. It returns the TTL for each specified field.
 // This command fetches the TTL in seconds for each field or returns error/status codes as appropriate.
-// For more information - https://redis.io/commands/httl/
+// Available since Redis 7.4 CE.
+// For more information refer to [HTTL Documentation].
+//
+// [HTTL Documentation]: https://redis.io/commands/httl/
 func (c cmdable) HTTL(ctx context.Context, key string, fields ...string) *IntSliceCmd {
 	args := []interface{}{"HTTL", key, "FIELDS", len(fields)}
 
@@ -447,6 +484,10 @@ func (c cmdable) HTTL(ctx context.Context, key string, fields ...string) *IntSli
 // HPTTL - Retrieves the remaining time to live for specified fields in a hash in milliseconds.
 // Similar to HTTL, but returns the TTL in milliseconds. It requires a key and the specified fields.
 // This command provides the TTL in milliseconds for each field or returns error/status codes as needed.
+// Available since Redis 7.4 CE.
+// For more information refer to [HPTTL Documentation].
+//
+// [HPTTL Documentation]: https://redis.io/commands/hpttl/
 // For more information - https://redis.io/commands/hpttl/
 func (c cmdable) HPTTL(ctx context.Context, key string, fields ...string) *IntSliceCmd {
 	args := []interface{}{"HPTTL", key, "FIELDS", len(fields)}
@@ -479,7 +520,7 @@ func (c cmdable) HGetEX(ctx context.Context, key string, fields ...string) *Stri
 	return cmd
 }
 
-// ExpirationType represents an expiration option for the HGETEX command.
+// HGetEXExpirationType represents an expiration option for the HGETEX command.
 type HGetEXExpirationType string
 
 const (