Weaviate Cloud only Search Mode combines AI-powered semantic search with structured filtering and returns the matching Weaviate objects directly. For example, you could ask: > "Find me some vintage shoes under $70" And the agent will perform semantic search for `vintage shoes`, apply a filter for `price < 70`, and return the matching objects from your collections, ready for you to render or post-process. You could also ask: > "Something comfortable to wear on a long flight" And the agent will use AI-powered search to find relevant objects, even when terms like `comfortable` or `long flight` never appear in your data. Under the hood, Search Mode does more than embed your query as-is. The agent writes one or more optimized semantic and structured queries, executes them against your collections, and reranks the retrieved objects by how well each one matches your original request. For more details, see the page for [the Python client](https://weaviate-python-client.readthedocs.io/en/stable/weaviate-agents-python-client/docs/weaviate_agents.query.html#weaviate_agents.query.QueryAgent.search) or [the Typescript Client](https://weaviate.github.io/agents-typescript-client/classes/QueryAgent.html#search). ## Usage Like all features of the Query Agent, it requires instantiation of the `QueryAgent` class, which is connected to your Weaviate `client`. [See the class instantiation page for more detail](../agents-configuration/instantiation.md). Note, locally running Weaviate instances do not support the Query Agent. :::code-group{sync="languages"} ```python title="Python" import os import weaviate from weaviate.agents.query import QueryAgent from weaviate.classes.init import Auth client = weaviate.connect_to_weaviate_cloud( cluster_url=os.environ.get("WEAVIATE_URL"), auth_credentials=Auth.api_key(os.environ.get("WEAVIATE_API_KEY")), ) qa = QueryAgent( client=client, collections=["ECommerce"], ) ``` ```typescript title="JavaScript/TypeScript" import weaviate from 'weaviate-client'; import { QueryAgent } from 'weaviate-agents'; ``` ::: Make sure to include your API keys in your environment, and specify whichever collection you want to search over. :::callout{intent="note" title="Async"} In Python, the Query Agent supports both synchronous and asynchronous usage. The Python examples on this page use the synchronous client, but can be easily replaced with the async equivalents — see the [async section](#async) for details. In JavaScript/TypeScript, all calls are asynchronous by default and use `await`. ::: ### Parameters The `.search()` method accepts several arguments: ::::tabs{sync="languages"} :::tab{title="Python"} | Parameter | Type | Description | | ------------------ | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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](../agents-configuration/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](../agents-configuration/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. | | `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. | | `effort` | `Literal["medium", "high", "ultrahigh"] \| None` | The amount of effort the agent puts into the search. Higher effort may improve result quality at the expense of increased latency and cost. See [Effort](#effort) below. | ::: :::tab{title="JavaScript/TypeScript"} | Parameter | Type | Description | | ----------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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](../agents-configuration/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](../agents-configuration/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. | | `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. | | `effort` | `"medium" \| "high" \| "ultrahigh"` | The amount of effort the agent puts into the search. Higher effort may improve result quality at the expense of increased latency and cost. See [Effort](#effort) below. | ::: :::: For more advanced searches, you can also specify _additional filters_ within the collection configuration. [See the page on additional filters for more detail](../agents-configuration/additional-filters.md). ### Effort The optional `effort` parameter controls the amount of effort the agent puts into the search. It accepts one of `"medium"`, `"high"`, or `"ultrahigh"`. Higher effort may improve result quality at the expense of increased latency and cost. :::code-group{sync="languages"} ```python title="Python" search_response = qa.search( "What are Setwise Rerankers?", limit=10, effort="ultrahigh", ) for obj in search_response.search_results.objects: print(obj.properties) ``` ```typescript title="JavaScript/TypeScript" const effortResponse = await qa.search("What are Setwise Rerankers?", { limit: 10, effort: "ultrahigh", }); for (const obj of effortResponse.searchResults.objects) { console.log(obj.properties); } ``` ::: ### Customized filtering 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. - **`"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. :::code-group{sync="languages"} ```python title="Python" search_response = qa.search( "Find me some vintage shoes under $70", filtering="precision", limit=10, ) for obj in search_response.search_results.objects: print(f"Product: {obj.properties['name']} - ${obj.properties['price']}") ``` ```typescript title="JavaScript/TypeScript" const filteringResponse = await qa.search("Find me some vintage shoes under $70", { filtering: "precision", limit: 10, }); for (const obj of filteringResponse.searchResults.objects) { console.log(`Product: ${obj.properties['name']} - $${obj.properties['price']}`); } ``` ::: ### Diversity ranking `Search` supports adding diversity weighting to result rankings using Maximal Marginal Relevance (MMR). This is enabled by passing a `diversity_weight` parameter in the range of `0.0` to `1.0` — higher values favor more varied results over the most relevant ones. To use diversity ranking with target vectors, set the single target vector you want to use in the Query Agent's constructor. Diversity ranking is not yet supported with collections using multi-vector embeddings, and will only work across multiple collections if they share the same embedding model. :::code-group{sync="languages"} ```python title="Python" qa = QueryAgent( client=client, collections=[ QueryAgentCollectionConfig( name="ECommerce", target_vector=["name_description_brand_vector"], ) ] ) search_response = qa.search( "summer shoes", limit=10, diversity_weight=0.5, ) for obj in search_response.search_results.objects: print(f"Product: {obj.properties['name']} - ${obj.properties['price']}") ``` ```typescript title="JavaScript/TypeScript" const diversitySearchResponse = await qa.search("summer shoes", { limit: 10, diversityWeight: 0.5, collections: [{ name: "ECommerce", targetVector: ["name_description_brand_vector"], }], }); for (const obj of diversitySearchResponse.searchResults.objects) { console.log(`Product: ${obj.properties['name']} - $${obj.properties['price']}`); } ``` ::: ## Response The Search Mode response has the following properties: ::::tabs{sync="languages"} :::tab{title="Python"} | Field | Type | Description | | --------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `searches` | `list[QueryResultWithCollectionNormalized]` | A list of searches the agent carried out. Each contains the search query, filters, and the collection the search was run against. | | `usage` | `ModelUnitUsage` | A `ModelUnitUsage` instance providing detail on the model units used during the run. The `model_units` are effectively token usage measurements normalized by cost. | | `total_time` | `float` | Total time taken (seconds). | | `search_results` | `QueryReturn` | A `QueryReturn` object whose `.objects` field is the list of matching Weaviate objects, each with `properties` and `metadata` (including the relevance `score`). | | `next(limit, offset)` | `SearchModeResponse` | A method that returns the next page of results, reusing the same underlying searches for consistency. See [Pagination](#pagination) below. | [See the client documentation for more detail.](https://weaviate-python-client.readthedocs.io/en/latest/weaviate-agents-python-client/docs/weaviate_agents.classes.html#weaviate_agents.classes.SearchModeResponse) ::: :::tab{title="JavaScript/TypeScript"} ```typescript import { SearchModeResponse } from 'weaviate-agents'; ``` | Field | Type | Description | | ------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `searches` | `Search[]` | A list of searches the agent carried out. Each contains the search query, filters, and the collection the search was run against. | | `usage` | `ModelUnitUsage` | A `ModelUnitUsage` object providing detail on the model units used during the run. The `modelUnits` are effectively token usage measurements normalized by cost. | | `totalTime` | `number` | Total time taken (seconds). | | `searchResults` | `WeaviateReturnWithCollection` | A `WeaviateReturnWithCollection` object whose `.objects` field is the list of matching Weaviate objects, each with `properties` and `metadata` (including the relevance `score`). | | `next({ limit, offset })` | `Promise` | A method that returns the next page of results, reusing the same underlying searches for consistency. See [Pagination](#pagination) below. | [See the client documentation for more detail.](https://weaviate.github.io/agents-typescript-client/types/SearchModeResponse.html) ::: :::: :::callout{intent="note" title="Result scores"} The `search_results` / `searchResults` field reuses Weaviate's native `QueryReturn` / `WeaviateReturnWithCollection` type, so results have the same shape as a standard Weaviate query. However, the `score` in each object's metadata is replaced with Search Mode's own ranking score rather than the original Weaviate search score. ::: ### Pagination Search returns results one page at a time. To fetch additional pages, call `.next()` on the previous response — the underlying searches are reused so results stay consistent across pages. :::code-group{sync="languages"} ```python title="Python" # Search with pagination response_page_1 = qa.search( "Find summer shoes and accessories between $50 and $100 that have the tag 'sale'", limit=3, ) # Get the next page of results response_page_2 = response_page_1.next(limit=3, offset=3) # Continue paginating response_page_3 = response_page_2.next(limit=3, offset=6) # Access results from each page for page_num, page_response in enumerate( [response_page_1, response_page_2, response_page_3], 1 ): print(f"Page {page_num}:") for obj in page_response.search_results.objects: # Safely access properties in case they don't exist name = obj.properties.get("name", "Unknown Product") price = obj.properties.get("price", "Unknown Price") print(f" {name} - ${price}") print() ``` ```typescript title="JavaScript/TypeScript" // Search with pagination const responsePage1 = await qa.search( "Find summer shoes and accessories between $50 and $100 that have the tag 'sale'", { limit: 3, }); // Get the next page of results const responsePage2 = await responsePage1.next({ limit: 3, offset: 3 }); // Continue paginating const responsePage3 = await responsePage2.next({ limit: 3, offset: 6 }); const pages = [responsePage1, responsePage2, responsePage3]; pages.forEach((pageResponse, index) => { const pageNum = index + 1; console.log(`Page ${pageNum}:`); pageResponse.searchResults.objects.forEach(obj => { // Safely access properties in case they don't exist const name = obj.properties.name || "Unknown Product"; const price = obj.properties.price || "Unknown Price"; console.log(` ${name} - $${price}`); }); }); ``` ::: ## Async ::::tabs{sync="languages"} :::tab{title="Python"} In Python, the above examples use the synchronous client, but Search Mode can also be called asynchronously. This requires the `AsyncQueryAgent` class (instantiated the same way as its sync counterpart) together with an async Weaviate client. ```python from weaviate.agents.query import AsyncQueryAgent async_client = weaviate.use_async_with_weaviate_cloud( cluster_url=os.environ.get("WEAVIATE_URL"), auth_credentials=Auth.api_key(os.environ.get("WEAVIATE_API_KEY")), ) await async_client.connect() async_qa = AsyncQueryAgent( client=async_client, collections=[ QueryAgentCollectionConfig( name="ECommerce", target_vector=["name_description_brand_vector"], ) ] ) ``` The `.search()` method must be awaited: ```python await async_qa.search( query="Find me some vintage shoes under $70", limit=10, ) ``` ::: :::tab{title="JavaScript/TypeScript"} In JavaScript/TypeScript, the `QueryAgent` is asynchronous by default — the examples in the previous sections already are asynchronous, and no separate async setup is needed. ::: :::: ## Questions and feedback Have a question or feedback? Here's how to reach us. ::::card-grid :::card{title="Community Forum" href="https://forum.weaviate.io/c/support" icon="messages-square"} Ask questions and connect with other developers on our **Community forum**. ::: :::card{title="Support" href="/guides/support-overview" icon="life-buoy"} Weaviate Cloud user or customer? Find the right channel on the **Support page**. ::: :::: ## Related pages - [Agents](./agents-index.md) - [AI-assisted Weaviate code generation](./ai-assisted-vibe-coding-index.md) - [APIs](./apis-index.md) - [Authorization and authentication](./authorization-and-authentication-index.md) - [Benchmarks](./benchmarks-index.md) - [Best practices](./best-practices-index.md) - [Client libraries](./clients-index.md) - [Client Libraries / SDKs](./client-libraries-index.md) - [Cloud](./cloud-index.md) - [Cloud account management](./cloud-account-management-index.md) # Agent Instructions This portal answers questions programmatically. To receive a synthesized, source-cited answer instead of crawling page by page, append the `?ask=` query parameter to any page URL on this site: /guides/quickstart?ask=how+do+I+authenticate Optional parameters: - `&goal=` steers the answer toward your objective (e.g. `&goal=write+a+python+client`). - `&version=