Semantic Query

Execute a structured query — schema-free, zero domain assumptions

Structured query execution engine.

This endpoint takes structured intent — produced by an LLM from the user's natural-language question. It does NOT accept raw text.

Separation of concerns:

  • LLM: language → structured intent, ambiguity resolution, user interaction
  • Algenta: schema understanding, math relationships, fast execution, correctness

Role resolution:

  1. Detect derived formulas across all numeric column triples (Mojo, ~100ms)
  2. Assign structural roles: derived_measure, base_measure, unit_measure…
  3. Match requested role → best column
  4. Execute aggregation, return result + all candidates for LLM disambiguation

Ambiguity handling: If confidence < 0.7, check candidates — multiple columns may match the role. The LLM can present options to the user or pick the most contextually appropriate one.

post/v1/query

Request

  • Base URL: https://api.algenta.ai
  • URL: https://api.algenta.ai/v1/query
  • Auth: one of:
    • HTTP bearer
    • API key in header X-API-Key

Request body

dataset_idstring nullable

Public dataset ID alias for a registered source. When provided, query execution is scoped to that one registered dataset.

source_namestring nullable

EXACT source name from the registry (e.g. 'Bookings'). Bypasses source resolver entirely. Get this from POST /v1/sources/schema or the registration response.

metric_columnstring nullable

EXACT column name for the metric (e.g. 'EXT_PRICE'). Bypasses column resolver. The engine validates this column exists in source_name.

group_columnstring nullable

EXACT column name for group-by (e.g. 'CUSTOMER'). Bypasses group resolver. Can be in source_name or in the terminal source of join_path.

group_bystring[]

Hint mode only: dimension words from the user's question (e.g. ['customer', 'region']). Ignored when group_column is set.

preferred_sourcestring nullable

Hint mode only: source name the LLM believes is correct. Hard-locks the source resolver. Ignored when source_name is set.

reject_on_ambiguityboolean

Hint mode only: when True and resolver confidence < 0.40, return null result with source candidates instead of guessing.

min_source_confidencenumber

Hint mode only: minimum resolver confidence threshold.

aggregationstring

sum | avg | count | max | min

limitinteger nullable

Top-N limit

orderstring

desc | asc

min_confidencenumber

Response

Successful Response

query_idstring required
resultunknown required
result_typestring required
confidencenumber required
planstring[] required
resolved_columnstring required
resolved_rolestring required
resolved_sourcestring required
row_countinteger required
source_scoresobject required
ambiguousboolean required
exact_specboolean required
explanationstring[]
latency_msnumber required
decision_pathstring required
plan_hashstring required
schema_revisionstring nullable
validatedboolean required
deterministic_scopestring required
confidence_sourcestring required
clarification_requiredboolean
rejection_reasonstring nullable
request_idstring nullable
source_setstring[]
join_pathobject[]
planner_modestring

Changes

No recorded changes to this operation across all 1 revision of this API.