DEV: document search limitation inside MULTI/EXEC

Author: dwdougherty

content/commands/ft.aggregate.md

@@ -529,3 +529,4 @@ One of the following:
 - [Aggregations]({{< relref "/develop/ai/search-and-query/advanced-concepts/aggregations" >}})
 - [Key and field expiration behavior]({{< relref "/develop/ai/search-and-query/advanced-concepts/expiration" >}})
 - [RediSearch]({{< relref "/develop/ai/search-and-query" >}})
+- [Search commands in MULTI/EXEC transactions and Lua scripts]({{< relref "/develop/ai/search-and-query/advanced-concepts/transactions" >}})

content/commands/ft.cursor-read.md

@@ -101,4 +101,5 @@ One of the following:
 
 ## Related topics
 
-[RediSearch]({{< relref "/develop/ai/search-and-query/" >}})
+- [RediSearch]({{< relref "/develop/ai/search-and-query/" >}})
+- [Search commands in MULTI/EXEC transactions and Lua scripts]({{< relref "/develop/ai/search-and-query/advanced-concepts/transactions" >}})

content/commands/ft.hybrid.md

@@ -823,3 +823,4 @@ One of the following:
 
 - [Vector search concepts]({{< relref "/develop/ai/search-and-query/vectors" >}})
 - [Combined search]({{< relref "/develop/ai/search-and-query/query/combined/" >}})
+- [Search commands in MULTI/EXEC transactions and Lua scripts]({{< relref "/develop/ai/search-and-query/advanced-concepts/transactions" >}})

content/commands/ft.profile.md

@@ -464,5 +464,6 @@ One of the following:
 
 ## Related topics
 
-[RediSearch]({{< relref "/develop/ai/search-and-query/" >}})
+- [RediSearch]({{< relref "/develop/ai/search-and-query/" >}})
+- [Search commands in MULTI/EXEC transactions and Lua scripts]({{< relref "/develop/ai/search-and-query/advanced-concepts/transactions" >}})
 

content/commands/ft.search.md

@@ -883,3 +883,4 @@ One of the following:
 - [Key and field expiration behavior]({{< relref "/develop/ai/search-and-query/advanced-concepts/expiration" >}})
 - [Query syntax]({{< relref "/develop/ai/search-and-query/query/" >}})
 - [RediSearch]({{< relref "/develop/ai/search-and-query/" >}})
+- [Search commands in MULTI/EXEC transactions and Lua scripts]({{< relref "/develop/ai/search-and-query/advanced-concepts/transactions" >}})

content/develop/ai/search-and-query/advanced-concepts/_index.md

@@ -45,6 +45,7 @@ Redis Open Source supports the following Redis Search features. This article pro
 * Geo-filtering using Redis [geo commands]({{< relref "/commands/" >}}?group=geo)
 * [Vector search]({{< relref "/develop/ai/search-and-query/vectors" >}})
 * [Key and field expiration behavior]({{< relref "/develop/ai/search-and-query/advanced-concepts/expiration" >}})
+* [Search commands in MULTI/EXEC transactions and Lua scripts]({{< relref "/develop/ai/search-and-query/advanced-concepts/transactions" >}})
 
 
 ## Full-text search features

content/develop/ai/search-and-query/advanced-concepts/transactions.md

@@ -0,0 +1,62 @@
+---
+categories:
+- docs
+- develop
+- stack
+- oss
+- rs
+- rc
+- oss
+- kubernetes
+- clients
+description: How Redis Search commands behave inside MULTI/EXEC transactions and Lua scripts
+linkTitle: Search in transactions
+title: Search commands in MULTI/EXEC transactions and Lua scripts
+weight: 36
+---
+
+Redis Search commands ([`FT.SEARCH`]({{< relref "/commands/ft.search" >}}),
+[`FT.AGGREGATE`]({{< relref "/commands/ft.aggregate" >}}),
+[`FT.HYBRID`]({{< relref "/commands/ft.hybrid" >}}),
+[`FT.PROFILE`]({{< relref "/commands/ft.profile" >}}), and
+[`FT.CURSOR READ`]({{< relref "/commands/ft.cursor-read" >}}))
+can be used inside [`MULTI`]({{< relref "/commands/multi" >}})/[`EXEC`]({{< relref "/commands/exec" >}})
+transactions and [Lua scripts]({{< relref "/develop/programmability/lua-api" >}}),
+but the behavior differs depending on your deployment topology.
+
+## Standalone and single-shard deployments
+
+Redis Search commands inside a `MULTI`/`EXEC` block or a Lua script execute synchronously
+on the main Redis thread, regardless of the
+[`search-workers`]({{< relref "/develop/ai/search-and-query/administration/configuration#search-workers" >}})
+setting.
+
+The worker thread pool is bypassed in this context because Redis transactions
+require all commands to complete sequentially without yielding to other clients.
+As a result, queries inside transactions do not benefit from the parallelism
+provided by `search-workers > 0`, but they execute correctly and return results
+as expected.
+
+## Multi-shard deployments (OSS Cluster and Redis Software with multiple shards)
+
+Redis Search commands inside a `MULTI`/`EXEC` block or a Lua script are rejected with
+the following error:
+
+```
+Cannot perform FT.SEARCH: Cannot block
+```
+
+This is because the coordinator must fan out the query to multiple shards and
+collect results asynchronously, which is incompatible with the sequential
+execution model of transactions. This limitation applies regardless of the
+`search-workers` setting.
+
+## Related commands
+
+- [`FT.SEARCH`]({{< relref "/commands/ft.search" >}})
+- [`FT.AGGREGATE`]({{< relref "/commands/ft.aggregate" >}})
+- [`FT.HYBRID`]({{< relref "/commands/ft.hybrid" >}})
+- [`FT.PROFILE`]({{< relref "/commands/ft.profile" >}})
+- [`FT.CURSOR READ`]({{< relref "/commands/ft.cursor-read" >}})
+- [`MULTI`]({{< relref "/commands/multi" >}})
+- [`EXEC`]({{< relref "/commands/exec" >}})