docs(query-agent): make search-mode filtering a required argument

The Query Agent service now requires the search-mode `filtering` argument to be
"recall" or "precision"; the latest client (weaviate-agents 1.6.0) still
defaults it to None and sends null, so every `.search()` call that omits
`filtering` fails with a 422. Document `filtering` as required (recommending
"recall") and pass `filtering="recall"` in every initial search-mode snippet
(Python + TypeScript); the precision FilteringExample and pagination/ask calls
are unchanged.

Author: g-despot

_includes/code/llms-txt/python/query_agent.py

@@ -28,7 +28,7 @@
 print(response.final_answer)
 
 # Retrieval only (no generation)
-search_response = qa.search("sci-fi movies", limit=5)
+search_response = qa.search("sci-fi movies", filtering="recall", limit=5)
 # END llms_query_agent
 
 assert response.final_answer

_includes/code/python/quickstart.short.query_agent.py

@@ -18,7 +18,7 @@
     qa = QueryAgent(client=client, collections=["Movie"])
 
     # Step 2.3: Perform a query using Search Mode
-    response = qa.search("Find a cool sci-fi movie.", limit=1)
+    response = qa.search("Find a cool sci-fi movie.", filtering="recall", limit=1)
     # highlight-end
 
     # Print the response

docs/query-agent/_includes/code/query_agent.mts

@@ -141,6 +141,7 @@ clothingResponse.display();
 // START BasicSearchQuery
 // Perform a search using Search Mode (retrieval only, no answer generation)
 const basicSearchResponse = await qa.search("Find me some vintage shoes under $70", {
+    filtering: "recall",
     limit: 10
 })
 
@@ -154,6 +155,7 @@ for (const obj of basicSearchResponse.searchResults.objects) {
 // Diversity ranking needs a vectorizer it can resolve. Scope the call to a
 // single collection with a target vector so the agent knows what to use.
 const diversitySearchResponse = await qa.search("summer shoes", {
+    filtering: "recall",
     limit: 10,
     diversityWeight: 0.5,
     collections: [{
@@ -179,6 +181,7 @@ basicResponse.display();
 // START SearchModeResponseStructure
 // SearchModeResponse structure for TypeScript
 const searchResponse = await qa.search("winter boots for under $100", {
+    filtering: "recall",
     limit: 5
 })
 
@@ -206,6 +209,7 @@ for (const obj of searchResponse.searchResults.objects) {
 // Search with pagination
 const responsePage1 = await qa.search(
     "Find summer shoes and accessories between $50 and $100 that have the tag 'sale'", {
+    filtering: "recall",
     limit: 3,
 })
 

docs/query-agent/_includes/code/query_agent.py

@@ -211,7 +211,7 @@
 
 # START BasicSearchQuery
 # Perform a search using Search Mode (retrieval only, no answer generation)
-search_response = qa.search("Find me some vintage shoes under $70", limit=10)
+search_response = qa.search("Find me some vintage shoes under $70", filtering="recall", limit=10)
 
 # Access the search results
 for obj in search_response.search_results.objects:
@@ -220,7 +220,7 @@
 
 # START SearchModeResponseStructure
 # SearchModeResponse structure for Python
-search_response = qa.search("winter boots for under $100", limit=5)
+search_response = qa.search("winter boots for under $100", filtering="recall", limit=5)
 
 # Access different parts of the response
 print(f"Original query: {search_response.searches[0].query}")
@@ -244,6 +244,7 @@
 # Search with pagination
 response_page_1 = qa.search(
     "Find summer shoes and accessories between $50 and $100 that have the tag 'sale'",
+    filtering="recall",
     limit=3,
 )
 
@@ -269,6 +270,7 @@
 # START DiversityRanking
 search_response = qa.search(
     "summer shoes",
+    filtering="recall",
     limit=10,
     diversity_weight=0.5,
     collections=[

docs/query-agent/_includes/code/query_agent_get_started.py

@@ -135,6 +135,7 @@
 # START SearchMode
 search_response = agent.search(
     "Find me some vintage shoes under $70",
+    filtering="recall",
     limit=10,
 )
 

docs/query-agent/_includes/code/quickstart.mts

@@ -51,6 +51,7 @@ qa = new QueryAgent(client, {
 // START BasicSearchQuery
 const searchResponse = await qa.search(
     "Find me some vintage shoes under $70", {
+    filtering: "recall",
     limit: 10,
 });
 // END BasicSearchQuery

docs/query-agent/_includes/code/quickstart.py

@@ -53,7 +53,8 @@
 
 # START BasicSearchQuery
 search_response = qa.search(
-    "Find me some vintage shoes under $70", 
+    "Find me some vintage shoes under $70",
+    filtering="recall",
     limit=10
 )
 # END BasicSearchQuery

docs/query-agent/_includes/code/search_mode.mts

@@ -39,6 +39,7 @@ await populateWeaviate(client);
 
 // START BasicSearchMode
 const searchResponse = await qa.search("Find me some vintage shoes under $70", {
+    filtering: "recall",
     limit: 10,
 });
 
@@ -50,6 +51,7 @@ for (const obj of searchResponse.searchResults.objects) {
 
 // START DiversityRanking
 const diversitySearchResponse = await qa.search("summer shoes", {
+    filtering: "recall",
     limit: 10,
     diversityWeight: 0.5,
     collections: [{
@@ -67,6 +69,7 @@ for (const obj of diversitySearchResponse.searchResults.objects) {
 // Search with pagination
 const responsePage1 = await qa.search(
     "Find summer shoes and accessories between $50 and $100 that have the tag 'sale'", {
+    filtering: "recall",
     limit: 3,
 });
 

docs/query-agent/_includes/code/search_mode.py

@@ -41,6 +41,7 @@
 # START BasicSearchMode
 search_response = qa.search(
     query="Find me some vintage shoes under $70",
+    filtering="recall",
     limit=10,
 )
 
@@ -62,6 +63,7 @@
 
 search_response = qa.search(
     "summer shoes",
+    filtering="recall",
     limit=10,
     diversity_weight=0.5,
 )
@@ -74,6 +76,7 @@
 # Search with pagination
 response_page_1 = qa.search(
     "Find summer shoes and accessories between $50 and $100 that have the tag 'sale'",
+    filtering="recall",
     limit=3,
 )
 
@@ -135,6 +138,7 @@
 # START AsyncSearch
 await async_qa.search(
     query="Find me some vintage shoes under $70",
+    filtering="recall",
     limit=10,
 )
 # END AsyncSearch
@@ -161,6 +165,7 @@ async def _async_run_for_testing():
 
     await async_qa.search(
         query="Find me some vintage shoes under $70",
+        filtering="recall",
         limit=10,
     )
     await async_client.close()

docs/query-agent/guides/search_mode.md

@@ -67,7 +67,7 @@ The `.search()` method accepts several arguments:
 | `query` | `str \| list[ChatMessage]` | The user query you want the agent to search with. This can be a simple string (`"Find me some vintage shoes under $70"`) or a list of chat messages (for conversational context). [See the page on multi-turn conversations for more detail](../reference/multi_turn_conversations.md). |
 | `collections` | `list[str \| QueryAgentCollectionConfig] \| None` | The name(s) of the collections to search. You can pass one or many collection names as a list of strings (e.g., `["ECommerce", "BookSales"]`), or provide collection configuration objects for more control. If specified in the `ask` method, it will overwrite those defined in the instantiation of `QueryAgent`. [See the page on collection configuration for more detail](../reference/advanced_collections.md). |
 | `limit` | `int` | The maximum number of results returned in this page of results. Defaults to `20`. Use [`.next()`](#pagination) to fetch additional pages. |
-| `filtering` | `Literal["recall", "precision"]` | Either `"recall"` or `"precision"` to control filter generation. `"recall"` favors more results across filter interpretations; `"precision"` favors strict intent match. See [Customized filtering](#customized-filtering) below. |
+| `filtering` | `Literal["recall", "precision"]` | **Required.** Either `"recall"` or `"precision"` to control filter generation. `"recall"` favors more results across filter interpretations; `"precision"` favors strict intent match. Pass `"recall"` for most cases. See [Customized filtering](#customized-filtering) below. |
 | `diversity_weight` | `float \| None` | A value between `0.0` and `1.0` that biases the result ranking towards diversity using Maximal Marginal Relevance (MMR). See [Diversity ranking](#diversity-ranking) below. |
 
 </TabItem>
@@ -77,7 +77,7 @@ The `.search()` method accepts several arguments:
 | `query` | `string \| ChatMessage[]` | The user query you want the agent to search with. This can be a simple string (`"Find me some vintage shoes under $70"`) or a list of chat messages (for conversational context). [See the page on multi-turn conversations for more detail](../reference/multi_turn_conversations.md). |
 | `collections` | `(string \| QueryAgentCollectionConfig)[]` | The name(s) of the collections to search. You can pass one or many collection names as a list of strings (e.g., `["ECommerce", "BookSales"]`), or provide collection configuration objects for more control. If specified in the `ask` method, it will overwrite those defined in the instantiation of `QueryAgent`. [See the page on collection configuration for more detail](../reference/advanced_collections.md). |
 | `limit` | `number` | The maximum number of results returned in this page of results. Defaults to `20`. Use [`.next()`](#pagination) to fetch additional pages. |
-| `filtering` | `"recall" \| "precision"` | Either `"recall"` or `"precision"` to control filter generation. `"recall"` favors more results across filter interpretations; `"precision"` favors strict intent match. See [Customized filtering](#customized-filtering) below. |
+| `filtering` | `"recall" \| "precision"` | **Required.** Either `"recall"` or `"precision"` to control filter generation. `"recall"` favors more results across filter interpretations; `"precision"` favors strict intent match. Pass `"recall"` for most cases. See [Customized filtering](#customized-filtering) below. |
 | `diversityWeight` | `number` | A value between `0.0` and `1.0` that biases the result ranking towards diversity using Maximal Marginal Relevance (MMR). See [Diversity ranking](#diversity-ranking) below. |
 
 </TabItem>
@@ -89,7 +89,9 @@ For more advanced searches, you can also specify _additional filters_ within the
 
 Search Mode uses query rewriting to transform your original query into one or multiple Weaviate queries, each with either a search query, metadata filters, or both. The `filtering` parameter controls how many Weaviate queries are generated.
 
-- **`"recall"`** (default): Generates multiple Weaviate queries spanning different filters and interpretations of the user query. You should use these when you prefer to get results, even if they don't match every criteria in your query.
+`filtering` is a required argument; pass either `"recall"` or `"precision"`. `"recall"` is recommended when you want more results.
+
+- **`"recall"`** (recommended): Generates multiple Weaviate queries spanning different filters and interpretations of the user query. You should use these when you prefer to get results, even if they don't match every criteria in your query.
 
 - **`"precision"`**: Generates a single Weaviate query targeting the most likely interpretation of the user query. You should use this when you want the results to follow your query intent closely, even if that means potentially receiving no results.