Asking a question¶
from arango_ai_sdk.models import QueryType
answer = retriever.ask(
"What do the contracts say about renewal?",
query_type=QueryType.UNIFIED,
)
print(answer.run_id)
print(answer.result)
One call sends one question to this retriever and returns the answer. You do not choose an endpoint or a query mode by string. The retriever must already be deployed and serving; see Deploying a retriever.
ask reloads the project first and refuses, before anything is sent, when
this retriever is no longer listed there.
Parameters¶
Parameter |
Type |
Meaning |
|---|---|---|
|
|
The question, in natural language. Required. A blank string is rejected and nothing is sent. |
|
|
How the retriever searches. Default |
|
|
Style instructions for the answer, such as |
|
|
Whether the response includes retrieval metadata. Default |
|
sequence of |
Restrict retrieval to these partitions. Omitted lets the service choose the relevant partitions itself. |
|
|
Whether to keep inline citations in the answer. Omitted leaves the service default, which keeps them. |
|
|
Chat model for this question only, instead of the model stored at deploy. The embedding model is unchanged. |
How the retriever searches¶
query_type is a QueryType, not a string.
QueryType.LOCALStarts from the people, companies and other entities named in the question and follows their relationships. Fits a specific fact.
QueryType.GLOBALReads the summaries of each part of the graph. Fits a question about themes across the whole corpus. It needs full-graph partitions. On a partition that is vectors only, the service cannot answer this way.
QueryType.UNIFIEDCombines matching text passages with the graph. This is the default, and it works on both vectors-only partitions and full-graph partitions. Use it when you are not sure which of the other two fits.
QueryType.CUSTOM is a value the service defines. ask will send it,
but the SDK does not take the custom-tool arguments that mode needs, so
leave it unset.
The service’s own default, if you never chose a mode, would be global. The
SDK does not leave it unset: omitting query_type sends UNIFIED, so a
project whose clusters are vectors only still answers.
What ask does not take¶
The retriever service can plan a question across several hops
(use_llm_planner) and can stream the answer. Neither is a parameter of
ask. A question is one request and one complete answer. To change how
much of the corpus becomes a full graph, set complexity when you
ingest or strategize,
not when you ask.
Return value¶
A GraphRagQueryResponse.
resultThe answer text.
run_idThe id of this query as the platform stored it. Keep it if you need to point at this answer later. The SDK cannot list past runs.
metadataExtra retrieval detail, only when you passed
include_metadata=True. Otherwise it is empty. It is a string, not a parsed object.
A response the service completed with a non-empty error_code is not
returned. ask raises instead, so a failed question never looks like an
empty result.
Errors¶
ValueErrorqueryis empty or only whitespace. Nothing was sent.AutoRagNotDeployedErrorThis retriever is no longer in the project, so nothing was sent.
askalso raises it when the query endpoint answers404, which right after a deploy can be the gateway still registering the route; callwait_until_readybefore the first question.QueryFailedErrorThe service answered, including with HTTP 200, but the body carried a failure code instead of an answer.
failure_codeis that code, for exampleINSUFFICIENT_QUOTAorINVALID_API_KEY.run_idis the stored run, or empty when the service stored none.status_codeis 200 for this case: the call reached the retriever and the retriever reported the failure in the body.
A global question against a vectors-only partition has no communities to read.
The retriever then returns that as a normal answer, with result set to
"No communities found at the specified level." It does not raise.
QueryFailedError is a non-empty error_code on the response.
Any other failure surfaces as one of the general SDK exceptions described in Errors.
Example¶
from arango_ai_sdk.exceptions import AutoRagNotDeployedError, QueryFailedError
from arango_ai_sdk.models import QueryType
questions = [
(QueryType.LOCAL, "Who signed the latest renewal?"),
(QueryType.GLOBAL, "What themes run through these contracts?"),
(QueryType.UNIFIED, "Which agreements mention late fees?"),
]
for query_type, question in questions:
try:
answer = retriever.ask(question, query_type=query_type)
except AutoRagNotDeployedError:
print("Retriever is gone; deploy again.")
break
except QueryFailedError as exc:
print(query_type.name, exc.failure_code, exc.run_id)
else:
print(query_type.name, answer.run_id)
print(answer.result)