Query Operations

Execute natural language queries with automatic domain detection, pipeline routing, and vector fallback. The query endpoints interface with MainOrchestrator to process queries through the three-pipeline architecture.

POST

/api/v1/query

Execute a natural language query with automatic domain detection and intelligent pipeline routing (Knowledge Graph, Text-to-SQL, or Vector Search).

Query Processing Flow

API Request → MainOrchestrator → Intent Classification → Pipeline Routing → Knowledge Graph / Text-to-SQL / Vector Search → Answer Generation

Request Parameters

Parameter	Type	Required	Description
`query`	string	Yes	The natural language question to answer
`user_id`	string	No	User identifier for personalized responses
`max_results`	integer	No	Maximum results (1-100, default: 10)
`validate_answer`	boolean	No	Enable answer validation (default: true)
`include_citations`	boolean	No	Include source citations (default: true)
`kg_names`	string[]	No	Specific KGs to search (default: auto-detect)

Response Fields

Field	Type	Description
`answer`	string	Generated answer to the query
`pipeline_used`	string	Pipeline that processed the query: knowledge_graph, text_to_sql, or vector_search
`citations`	array	Source attributions with relevance scores
`processing_time_ms`	number	Query processing time in milliseconds
`confidence`	number	Answer confidence score (0-1)
`metadata`	object	Additional context about query processing

POST

/api/v1/query/unified

Advanced unified query interface with explicit mode control and comprehensive features. Supports auto-routing, manual pipeline selection, vector bypass, and enhanced re-ranking.

Query Modes

Mode	Description	Best For
`auto`	Automatic pipeline selection via intent detection	General queries when pipeline isn't obvious
`kg_rag`	Knowledge Graph RAG with reasoning	Complex questions requiring entity relationships
`vector`	Fast vector similarity search	Bulk document retrieval, semantic search
`sql`	Text-to-SQL for structured queries	Data retrieval, counting, filtering operations
`hybrid`	Combines multiple pipelines	Complex queries benefiting from multiple approaches

Request Parameters

Parameter	Type	Required	Description
`query`	string	Yes	The natural language question
`mode`	string	No	Query execution mode: auto, kg_rag, vector, sql, hybrid (default: auto)
`enable_reranking`	boolean	No	Enable LLM re-ranking (default: true)
`reranker_method`	string	No	Re-ranking method: listwise, pointwise, pairwise (default: listwise)
`use_vector_bypass`	boolean	No	Use vector bypass for faster retrieval (default: false)
`max_results`	integer	No	Maximum results (1-100, default: 10)
`sql_max_results`	integer	No	Max SQL results (1-1000, default: 100)
`kg_names`	string[]	No	Specific KGs to search
`response_format`	string	No	Response format: standard, detailed, compact (default: standard)

Response Fields

Field	Type	Description
`query`	string	Original query
`mode`	string	Mode used for processing
`pipeline`	string	Pipeline that processed the query
`answer`	string	Generated answer (KG-RAG queries)
`generated_sql`	string	Generated SQL query (SQL mode)
`results`	array	Query results (SQL mode)
`vector_results`	array	Retrieved documents (vector mode)
`citations`	array	Source citations with scores
`processing_time_ms`	number	Total processing time
`routing_decision`	string	Explanation for pipeline routing

Smart Routing

In auto mode, the system analyzes query intent using keywords and patterns. SQL-related terms trigger Text-to-SQL, bulk retrieval terms use vector search, and complex reasoning queries route to KG-RAG.

POST

/api/v1/query/vector-bypass

Fast vector similarity search bypassing the full RAG pipeline. Ideal for bulk document retrieval and scenarios where you need rapid results without answer generation.

Request Parameters

Parameter	Type	Required	Description
`query`	string	Yes	Search query for semantic retrieval
`top_k`	integer	No	Number of results to return (1-100, default: 20)
`include_reranking`	boolean	No	Apply LLM re-ranking to results (default: true)
`reranker_method`	string	No	Re-ranking method: listwise or pointwise (default: listwise)
`kg_names`	string[]	No	Specific KGs to search
`include_search_details`	boolean	No	Include detailed search metadata (default: false)

Performance

Vector bypass is 3-5x faster than full RAG since it skips answer generation. Best for previews, bulk retrieval, or when you'll post-process results externally.

POST

/api/v1/query-sql

Convert natural language questions to SQL queries and execute them against the knowledge graph database. Ideal for structured data retrieval and analytical queries.

Request Parameters

Parameter	Type	Required	Description
`query`	string	Yes	Natural language query to convert to SQL
`max_results`	integer	No	Maximum SQL results (1-1000, default: 100)
`include_explanation`	boolean	No	Include SQL generation explanation (default: true)
`include_execution_plan`	boolean	No	Include SQL execution plan (default: false)
`validate_query`	boolean	No	Validate SQL before execution (default: true)
`query_type`	string	No	Type hint: auto, select, aggregate, join, subquery (default: auto)
`table_hints`	string[]	No	Suggested tables to query

SQL Safety

All generated SQL queries are validated before execution. Only SELECT statements are permitted - no data modification operations.

Choosing the Right Endpoint

Endpoint	Speed	Best For	Returns
`/query`	Medium	General Q&A with automatic routing	Answer + Citations
`/query/unified`	Variable	Advanced queries with mode control	Mode-specific response
`/query/vector-bypass`	Fast	Bulk document retrieval	Ranked documents
`/query-sql`	Very Fast	Structured data queries, counts, filters	SQL results