Skip to content

DEV: (cmds) update FT.PROFILE and FT.HYBRID commands #3340

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dwdougherty merged 2 commits into from
May 19, 2026
Merged

DEV: (cmds) update FT.PROFILE and FT.HYBRID commands #3340

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
972a46f
DEV: (cmds) update FT.PROFILE and FT.HYBRID commands
dwdougherty May 18, 2026
d487a33
Tweak command page and add add'l info to vector search page
dwdougherty May 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions content/commands/ft.hybrid.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -504,7 +504,7 @@ railroad_diagram: /images/railroad/ft.hybrid.svg
since: 8.4.0
summary: Performs hybrid search combining text search and vector similarity search
syntax_fmt: "FT.HYBRID index\n SEARCH query\n [SCORER scorer]\n [YIELD_SCORE_AS\
\ name]\n VSIM vector_field $vector_param\n [KNN count K k [EF_RUNTIME ef_runtime]]\n\
\ name]\n VSIM vector_field $vector_param\n [KNN count K k [EF_RUNTIME ef_runtime]] [SHARD_K_RATIO shard_k_ratio]]\n\
\ [RANGE count RADIUS radius [EPSILON epsilon]]\n [YIELD_SCORE_AS name]\n\
\ [FILTER filter]\n [COMBINE RRF count [CONSTANT constant] [WINDOW window]\
\ [YIELD_SCORE_AS name]]\n [COMBINE LINEAR count [[ALPHA alpha] [BETA beta]] [WINDOW\
Expand Down Expand Up @@ -566,9 +566,9 @@ assigns an alias to the search score for use in post-processing operations like
</details>

<details open>
<summary><code>KNN count K top-k [EF_RUNTIME ef-value] [YIELD_SCORE_AS name]</code></summary>
<summary><code>KNN count K top-k [EF_RUNTIME ef-value] [SHARD_K_RATIO shard-k-ratio] [YIELD_SCORE_AS name]</code></summary>

configures K-nearest neighbors search for vector similarity. The `count` parameter indicates the number of following parameters. `K` specifies the number of nearest neighbors to find. `EF_RUNTIME` controls the search accuracy vs. speed tradeoff. `YIELD_SCORE_AS` assigns an alias to the score value.
configures K-nearest neighbors search for vector similarity. The `count` parameter indicates the number of following parameters. `K` specifies the number of nearest neighbors to find. `EF_RUNTIME` controls the search accuracy vs. speed tradeoff. `SHARD_K_RATIO` controls the number of results each shard retrieves relative to the requested `top_k` in cluster setups. `YIELD_SCORE_AS` assigns an alias to the score value. See the [vector search]({{< relref "/develop/ai/search-and-query/vectors#cluster-optimization-examples" >}}) documentation for more information about `SHARD_K_RATIO`.
</details>

<details open>
Expand Down
18 changes: 9 additions & 9 deletions content/commands/ft.profile.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,13 +45,13 @@ module: Search
railroad_diagram: /images/railroad/ft.profile.svg
since: 2.2.0
stack_path: docs/interact/search-and-query
summary: Performs a `FT.SEARCH` or `FT.AGGREGATE` command and collects performance
summary: Performs a `FT.SEARCH`, `FT.HYBRID`, or `FT.AGGREGATE` command and collects performance
information
syntax_fmt: FT.PROFILE index <SEARCH | AGGREGATE> [LIMITED] QUERY query
syntax_fmt: FT.PROFILE index <SEARCH | HYBRID | AGGREGATE> [LIMITED] QUERY query
title: FT.PROFILE
---

Apply [`FT.SEARCH`]({{< relref "commands/ft.search/" >}}) or [`FT.AGGREGATE`]({{< relref "commands/ft.aggregate/" >}}) command to collect performance details. For usage, see [Examples](#examples).
Apply [`FT.SEARCH`]({{< relref "commands/ft.search/" >}}), [`FT.HYBRID`]({{< relref "commands/ft.hybrid/" >}}), or [`FT.AGGREGATE`]({{< relref "commands/ft.aggregate/" >}}) command to collect performance details. For usage, see [Examples](#examples).

## Required arguments

Expand All @@ -62,9 +62,9 @@ is the name of an index created using [`FT.CREATE`]({{< relref "commands/ft.crea
</details>

<details open>
<summary><code>SEARCH | AGGREGATE</code></summary>
<summary><code>SEARCH | HYBRID | AGGREGATE</code></summary>

represents the profile type, either [`FT.SEARCH`]({{< relref "commands/ft.search/" >}}) or [`FT.AGGREGATE`]({{< relref "commands/ft.aggregate/" >}}).
represents the profile type, either [`FT.SEARCH`]({{< relref "commands/ft.search/" >}}), [`FT.HYBRID`]({{< relref "commands/ft.hybrid/" >}}), or [`FT.AGGREGATE`]({{< relref "commands/ft.aggregate/" >}}).
</details>

<details open>
Expand All @@ -76,7 +76,7 @@ removes details of any `reader` iterators.
<details open>
<summary><code>QUERY {query}</code></summary>

is the query string, sent to `FT.SEARCH` or `FT.AGGREGATE`.
is the query string, sent to `FT.SEARCH`, `FT.HYBRID`, or `FT.AGGREGATE`.
</details>

<note><b>Note:</b> To reduce the size of the output, use `NOCONTENT` or `LIMIT 0 0` to reduce the number of reply results, or `LIMITED` to not reply with details of `reader iterators` inside built-in unions, such as `fuzzy` or `prefix` iterators.</note>
Expand All @@ -88,7 +88,7 @@ This page contains the up-to-date profile output as of RediSearch v2.8.33, v2.10
The output format itself may differ between RediSearch versions, and RESP protocol versions.
{{< /note >}}

`FT.PROFILE` returns a two-element array reply. The first element contains the results of the provided `FT.SEARCH` or `FT.AGGREGATE` command.
`FT.PROFILE` returns a two-element array reply. The first element contains the results of the provided `FT.SEARCH`, `FT.HYBRID`, or `FT.AGGREGATE` command.
The second element contains information about query creation, iterator profiles, and result processor profiles.
Details of the second element follow in the sections below.

Expand All @@ -103,7 +103,7 @@ If there's only one shard, the label will be omitted.
| `Shard ID` | String containing the unique shard ID. In Redis Open Source, this identifier is denoted as the node ID, and is received from the `RedisModule_GetMyClusterID()` API. (Available as of RediSearch v8.4.3) |
| `Total`&nbsp;`profile`&nbsp;`time` | The total run time (ms) of the query. Normally just a few ms. |
| `Parsing`&nbsp;`time` | The time (ms) spent parsing the query and its parameters into a query plan. Normally just a few ms. |
| `Pipeline`&nbsp;`creation`&nbsp;`time` | The creation time (ms) of the execution plan, including iterators, result processors, and reducers creation. Normally just a few ms for `FT.SEARCH` queries, but expect a larger number for `FT.AGGREGATE` queries. |
| `Pipeline`&nbsp;`creation`&nbsp;`time` | The creation time (ms) of the execution plan, including iterators, result processors, and reducers creation. Normally just a few ms for `FT.SEARCH` or `FT.HYBRID` queries, but expect a larger number for `FT.AGGREGATE` queries. |
| `Total`&nbsp;`GIL`&nbsp;`time` | In multi-threaded deployments, the total time (ms) the query spent holding and waiting for the Redis Global Lock (referred to as GIL) during execution. Note: this value is only valid in the shards profile section. |
| `Warning` | Errors that occurred during query execution. |
| `Internal`&nbsp;`cursor`&nbsp;`reads` | The number of times the coordinator fetched result batches from a given shard during a distributed `AGGREGATE` query in cluster mode. Includes the initial request plus any subsequent batch fetches. |
Expand Down Expand Up @@ -460,7 +460,7 @@ One of the following:

## See also

[`FT.SEARCH`]({{< relref "commands/ft.search/" >}}) | [`FT.AGGREGATE`]({{< relref "commands/ft.aggregate/" >}})
[`FT.SEARCH`]({{< relref "commands/ft.search/" >}}) | [`FT.HYBRID`]({{< relref "commands/ft.hybrid/" >}}) | [`FT.AGGREGATE`]({{< relref "commands/ft.aggregate/" >}})

## Related topics

Expand Down
6 changes: 6 additions & 0 deletions content/develop/ai/search-and-query/vectors/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -564,6 +564,12 @@ Use a higher ratio for better accuracy when precision is more important than per
FT.SEARCH products "*=>[KNN 20 @product_embedding $BLOB]=>{$SHARD_K_RATIO: 0.8; $YIELD_DISTANCE_AS: similarity}" PARAMS 2 BLOB "\x12\xa9\xf5\x6c" SORTBY similarity DIALECT 2
```

[`FT.HYBRID`]({{< relref "/commands/ft.hybrid" >}}) also supports `SHARD_K_RATIO` as part of its `KNN` clause. The following query combines a text search for `laptop` with vector similarity, returning the top 100 nearest neighbors with each shard providing 50% of the requested results:

```
FT.HYBRID products-idx SEARCH "laptop" VSIM @description_vector $query_vec KNN 4 K 100 SHARD_K_RATIO 0.5 PARAMS 2 query_vec "\x12\xa9\xf5\x6c"
```

### Cluster considerations and best practices

When using `$SHARD_K_RATIO` in Redis cluster environments, consider the following behavioral characteristics and best practices:
Expand Down
Loading