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

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",
)

JavaScript/TypeScript

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

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

Python

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

qa.suggest_queries()

JavaScript/TypeScript

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

await qa.suggestQueries();

Parameters

Suggest Queries can be called with the following arguments:

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.
`conversation`	`list[ChatMessage] \| None`	A conversation history used to generate follow-up query suggestions.

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.
`conversation`	`ChatMessage[]`	A conversation history used to generate follow-up query suggestions.

Follow-up queries

You can pass a conversation to Suggest Queries to generate follow-up query suggestions based on the conversation history. This is useful for guiding users toward relevant next questions after an initial exchange.

The conversation parameter accepts a list of ChatMessage objects, using the same format as multi-turn conversations.

Python

from weaviate.agents.classes import ChatMessage

# Build a conversation history
conversation = [
    ChatMessage(role="user", content="What are some popular machine learning frameworks?"),
    ChatMessage(
        role="assistant",
        content="Some popular ML frameworks include TensorFlow, PyTorch, and JAX.",
    ),
]

# Suggest follow-up queries based on the conversation context
response = qa.suggest_queries(
    conversation=conversation,
    num_queries=3,
)

for suggested_query in response.queries:
    print(suggested_query.query)

JavaScript/TypeScript

import { ChatMessage } from 'weaviate-agents';

// Build a conversation history
const suggestConversation: ChatMessage[] = [
    {
        role: 'user',
        content: 'What are some popular machine learning frameworks?',
    },
    {
        role: 'assistant',
        content: 'Some popular ML frameworks include TensorFlow, PyTorch, and JAX.',
    },
];

// Suggest follow-up queries based on the conversation context
const suggestWithConvoResponse = await qa.suggestQueries({
    conversation: suggestConversation,
    numQueries: 3,
});

for (const suggestedQuery of suggestWithConvoResponse.queries) {
    console.log(suggestedQuery.query);
}

Response

The SuggestQueryResponse class has the following properties:

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

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.

Python

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:

Python

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

Have a question or feedback? Here's how to reach us.

Community Forum

Ask questions and connect with other developers on our Community forum.

Support

Weaviate Cloud user or customer? Find the right channel on the Support page.