{"record":{"id":"4cf8d3db6c8ffd9f","repo":"redis/go-redis","slug":"ft-hybrid-shard-k-ratio-requires-knn-method","errorCode":null,"errorMessage":"FT.HYBRID: SHARD_K_RATIO requires KNN method","messagePattern":"FT\\.HYBRID: SHARD_K_RATIO requires KNN method","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"search_commands.go","lineNumber":3915,"sourceCode":"\t\t\t}\n\t\t\targs = append(args, \"$\"+paramName)\n\t\t\tparams[paramName] = vectorBlob\n\n\t\t\tif vectorExpr.Method != \"\" {\n\t\t\t\targs = append(args, vectorExpr.Method)\n\t\t\t\tif len(vectorExpr.MethodParams) > 0 {\n\t\t\t\t\t// MethodParams should be key-value pairs, count them\n\t\t\t\t\targs = append(args, len(vectorExpr.MethodParams))\n\t\t\t\t\targs = append(args, vectorExpr.MethodParams...)\n\t\t\t\t}\n\t\t\t}\n\n\t\t\t// SHARD_K_RATIO applies to the KNN method only (Redis 8.8+, cluster only).\n\t\t\t// Zero means \"unset\" and falls back to the server default of 1.0.\n\t\t\tif vectorExpr.ShardKRatio > 0 {\n\t\t\t\tif vectorExpr.Method != \"KNN\" {\n\t\t\t\t\tcmd := newFTHybridCmd(ctx, options, args...)\n\t\t\t\t\tcmd.SetErr(fmt.Errorf(\"FT.HYBRID: SHARD_K_RATIO requires KNN method\"))\n\t\t\t\t\treturn cmd\n\t\t\t\t}\n\t\t\t\tif vectorExpr.ShardKRatio < 0.1 || vectorExpr.ShardKRatio > 1.0 {\n\t\t\t\t\tcmd := newFTHybridCmd(ctx, options, args...)\n\t\t\t\t\tcmd.SetErr(fmt.Errorf(\"FT.HYBRID: SHARD_K_RATIO must be between 0.1 and 1.0\"))\n\t\t\t\t\treturn cmd\n\t\t\t\t}\n\t\t\t\targs = append(args, \"SHARD_K_RATIO\", vectorExpr.ShardKRatio)\n\t\t\t}\n\n\t\t\tif vectorExpr.Filter != \"\" {\n\t\t\t\targs = append(args, \"FILTER\", vectorExpr.Filter)\n\t\t\t}\n\n\t\t\tif vectorExpr.YieldScoreAs != \"\" {\n\t\t\t\targs = append(args, \"YIELD_SCORE_AS\", vectorExpr.YieldScoreAs)\n\t\t\t}\n\t\t}","sourceCodeStart":3897,"sourceCodeEnd":3933,"githubUrl":"https://github.com/redis/go-redis/blob/c5cad058c72f58370553b48566302303cf8a2e89/search_commands.go#L3897-L3933","documentation":"ShardKRatio is a Redis 8.8+ cluster-only FT.HYBRID option that only applies when the KNN search method is used. The client validates that when ShardKRatio > 0 the vector expression's Method is \"KNN\", and fails the command otherwise.","triggerScenarios":"Calling FTHybridWithArgs with a HybridVectorOptions where ShardKRatio is set to a positive value while Method is not \"KNN\" (e.g. empty or another method name).","commonSituations":"Setting cluster sharding tuning options copied from an example while using a non-KNN method; leaving ShardKRatio set from a previous query configuration while switching methods.","solutions":["Set Method: \"KNN\" on the vector expression when using ShardKRatio.","Set ShardKRatio to 0 (unset) if you don't need the option.","Keep ShardKRatio within 0.1–1.0 and only enable it on Redis 8.8+ clusters."],"exampleFix":"// before\nvecOpts := redis.HybridVectorOptions{Method: \"\", ShardKRatio: 0.5, ...}\n// after\nvecOpts := redis.HybridVectorOptions{Method: \"KNN\", ShardKRatio: 0.5, ...}","handlingStrategy":"validation","validationCode":"if vecOpts.ShardKRatio > 0 && vecOpts.Method != \"KNN\" {\n    return errors.New(\"ShardKRatio requires Method \\\"KNN\\\"\")\n}","typeGuard":"func shardKRatioValid(o redis.HybridVectorOptions) bool {\n    return o.ShardKRatio == 0 || (o.Method == \"KNN\" && o.ShardKRatio >= 0.1 && o.ShardKRatio <= 1.0)\n}","tryCatchPattern":"cmd := client.FTHybridWithArgs(ctx, \"idx\", opts)\nif err := cmd.Err(); err != nil && strings.Contains(err.Error(), \"SHARD_K_RATIO requires KNN\") {\n    // unset ShardKRatio or switch Method to \"KNN\" and retry\n}","preventionTips":["Only set ShardKRatio together with Method \"KNN\"","Reset ShardKRatio to 0 when reusing option structs across queries","Confirm Redis 8.8+ cluster before using the option"],"tags":["search","vector","ft-hybrid","cluster","validation"],"backgroundTag":"incompatible-options","analyzedSha":"c5cad058c72f58370553b48566302303cf8a2e89","analyzedAt":"2026-09-01T06:50:53.388Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}