Suggest Queries Mode

Weaviate Cloud only

The Query Agent can suggest queries based on the data in your collections. This is useful for helping users discover what kinds of questions they can ask, or for generating example queries for a new dataset.

Usage

The method can be called with a set of instructions and/or specifications:

Python (Agents)JavaScript/TypeScript (Agents)

from weaviate.agents.query import QueryAgent
qa = QueryAgent(client=client)

response = qa.suggest_queries(
    collections=["FinancialContracts"],
    num_queries=3,
    instructions="High-level themes and open-ended exploration",
)

import weaviate from 'weaviate-client';
import { QueryAgent } from 'weaviate-agents';

const client = await weaviate.connectToWeaviateCloud(
    process.env.WEAVIATE_URL as string, {
    authCredentials: new weaviate.ApiKey(process.env.WEAVIATE_API_KEY as string),
});

let qa = new QueryAgent(client);

const response = await qa.suggestQueries({
    collections: ['FinancialContracts'],
    numQueries: 3,
    instructions: 'High-level themes and open-ended exploration',
});

Or can be called without any additional arguments, to use the defaults.

Python (Agents)JavaScript/TypeScript (Agents)

qa = QueryAgent(client=client, collections=["FinancialContracts"])

qa.suggest_queries()

qa = new QueryAgent(client, {
    collections: ['FinancialContracts'],
});

await qa.suggestQueries();

Parameters

Suggest Queries can be called with the following arguments:

Python (Agents)JavaScript/TypeScript (Agents)

Parameter	Type	Description
collections	list[str | QueryAgentCollectionConfig] | None	Override the collections configured at instantiation. See the page on collection configuration for more detail.
num_queries	int	The number of queries to suggest (default: 3).
instructions	str | None	Guide the style or focus of the suggested queries. This is provided in addition to any system instructions. Useful for e.g. specifying language.

Parameter	Type	Description
collections	(string | QueryAgentCollectionConfig)[]	Override the collections configured at instantiation. See the page on collection configuration for more detail.
numQueries	number	The number of queries to suggest (default: 3).
instructions	string	Guide the style or focus of the suggested queries. This is provided in addition to any system instructions. Useful for e.g. specifying language.

Response

The SuggestQueryResponse class has the following properties:

Python (Agents)JavaScript/TypeScript (Agents)

Field	Type	Description
queries	list[SuggestedQuery]	A list of SuggestedQuery objects, each with a single property query, a suggested query that the user could run against their data.
collection_count	int	The number of collections that were considered when generating the suggested queries.
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).

See the client documentation for more detail.

Field	Type	Description
queries	SuggestedQuery[]	A list of SuggestedQuery objects, each with a single property query, a suggested query that the user could run against their data.
collectionCount	number	The number of collections that were considered when generating the suggested queries.
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).

See the client documentation for more detail.

Async

Python (Agents)JavaScript/TypeScript (Agents)

In Python, the above examples use the synchronous client, but Suggest Queries can also be called asynchronously. This requires the AsyncQueryAgent class (instantiated the same way as its sync counterpart) together with an async Weaviate client.

import os
import weaviate
from weaviate.classes.init import Auth
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)

The .suggest_queries() method must be awaited:

await async_qa.suggest_queries(
    collections=["FinancialContracts"],
    num_queries=3,
    instructions="High-level themes and open-ended exploration",
)

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

If you have any questions or feedback, let us know in the user forum.

Technical questions

If you have questions feel free to post on our Community forum.

Documentation feedback

Leave feedback by opening a GitHub issue.