Natural Language to AQL Translation Service - API Reference

Txt2AqlService provides natural language to AQL translation capabilities. It includes endpoints for both direct text processing and AQL query generation.

HTTP Bindings

Endpoint	Method	RPC Method	Body
/v1/health	GET	HealthCheck
/v1/process_text	POST	ProcessText	*
/v1/process_text_stream	POST	ProcessTextStream	*
/v1/translate_query	POST	TranslateQuery	*

Methods

Method Name	Request Type	Response Type
HealthCheck	HealthCheckRequest	HealthCheckResponse
HealthCheck returns the health status of the service. Use this endpoint for monitoring and readiness checks.
ProcessText	TextRequest	TextResponse
ProcessText accepts a text input and returns a processed response. This is a general-purpose endpoint for text processing tasks.
ProcessTextStream	TextRequest	ResponseChunk stream
ProcessTextStream streams processed text chunks as they are generated.
TranslateQuery	NLQuery	TranslatedQueryResponse
TranslateQuery converts natural language queries into AQL. It uses ArangoGraphQAChain for translation and can return multiple output formats.

HealthCheckRequest

HealthCheckRequest is an empty message for health check requests.

HealthCheckResponse

HealthCheckResponse contains the health status of the service.

Field	Type	Label	Description
status	string		status can be "SERVING" or "NOT_SERVING"

Metadata

Metadata contains auxiliary info for a stream

Field	Type	Label	Description
model	string	optional
request_id	string	optional
safety_flags	string	repeated

NLQuery

NLQuery represents a natural language query with optional configuration.

Field	Type	Label	Description
input_text	string		The natural language query text
options	QueryOptions		Configuration options for the query

QueryOptions

QueryOptions configures how the query should be processed and returned.

Field	Type	Label	Description
output_formats	OutputFormat	repeated	Desired output formats
graph_name	string	optional	Target graph for the query
request_timeout	int32	optional	ArangoDB request timeout in seconds

ResponseChunk

ResponseChunk represents a streaming delta plus optional metadata and usage

Field	Type	Label	Description
text_delta	string
done	bool
event	string		e.g., "delta", "status", "error"
completion_reason	string		set on terminal chunk
error	string	optional	optional error text
metadata	Metadata	optional	optional metadata
usage	Usage		cumulative usage

TextRequest

TextRequest represents the input text to be processed.

Field	Type	Label	Description
input_text	string		The text to be processed
mode	string	optional	Optional processing mode. When set to "aqlizer", the service will build an AQL-oriented prompt similar to the Rust-based AQL Oracle and stream that.
response_instruction	string	optional	Optional response instruction/prompt that can be injected into the constructed prompt (mirrors unified_query strategy in retrievers).

TextResponse

TextResponse contains the processed text output.

Field	Type	Label	Description
response_text	string		The processed response

TranslatedQueryResponse

TranslatedQueryResponse contains the query translation results.

Field	Type	Label	Description
original_query	string	optional	The original natural language query
nl_response	string	optional	Natural language response
aql_result	string	optional	Results from executing the AQL query
aql_query	string	optional	The generated AQL query

Usage

Usage tracks output token count

Field	Type	Label	Description
output_tokens	int32

OutputFormat

OutputFormat specifies the format for the query response.

Name	Number	Description
JSON	0	Return results in JSON format
RAW	1	Return raw query results
NL	2	Return results in natural language
AQL	3	Return the generated AQL query

Scalar Value Types