---
title: "Resolve structured intent into an exact executable plan"
method: POST
path: "/v1/resolve"
tags: ["Semantic Query"]
---

# Resolve structured intent into an exact executable plan

`POST /v1/resolve`

## Request

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

**Bounded deterministic planner.**

This endpoint resolves structured intent into an exact plan for `POST /v1/query`.
It only uses registered-source metadata, join graph metadata, planner cache, and precomputed statistics. It does not scan datasets or execute queries.

**Scope rules:**
- Provide `dataset_id` for dataset-scoped planning, or
- set `allow_org_scope=true` to plan across all visible datasets.

**Deterministic guarantees:**
- identical intent_signature + schema_revision + scope => identical output
- ambiguity clarifies or rejects; it never expands search
- no fallback to slower planning paths exists

## Request body

- ResolveRequest: Bounded planning request that returns an exact executable plan.
  - `dataset_id` string, nullable: Public dataset ID alias for a registered source. Required unless allow_org_scope=true or only one visible dataset exists.
  - `metric` MetricSpec: Structural role target. The LLM selects based on what the user wants. Use 'derived_measure' for revenue, spend, total value — the computed aggregate. Use 'base_measure' for counts, quantities, discrete amounts. Use 'unit_measure' for prices, rates, per-unit values. Use 'ratio' for percentages, margins, fill rates. Use 'metric' to let the engine pick the best numeric column.
    - `role` string: Structural role. One of: base_measure, category, component, derived_measure, identifier, metric, ratio, text, time, unit_measure. derived_measure = computed aggregate (revenue, total value). base_measure = count/quantity. unit_measure = price/rate. ratio = percentage/margin. metric = best numeric column.
    - `hint` string, nullable: Optional weak signal — a word from the user's question. Used only as a tiebreaker when multiple columns share the same role. Never the primary signal. Examples: 'revenue', 'quantity', 'price'.
  - `group_by` string[]
  - `preferred_source` string, nullable
  - `reject_on_ambiguity` boolean
  - `min_source_confidence` number
  - `aggregation` string: sum | avg | count | max | min
  - `filter` FilterSpec: Time or value filter.
    - `time_filter` string, nullable: Relative time window. One of: last_quarter, this_quarter, last_month, this_month, last_year, this_year.
    - `conditions` FilterConditionSpec[]: Optional deterministic non-time predicates applied on the metric source. These are record predicates over normalized rows, not SQL clauses. Use exact column when schema is known, or dimension_hint for categorical dimensions when only the semantic label is known, including Redis and other non-SQL sources after normalization. Supported ops: eq, in, gt, gte, lt, lte, is_null, is_not_null.
      - `column` string, nullable: Exact source column name for this filter when schema is known.
      - `dimension_hint` string, nullable: Weak semantic label for the filter dimension when the exact column name is not known yet. Best for status/type/category style filters.
      - `op` 'eq' | 'in' | 'gt' | 'gte' | 'lt' | 'lte' | 'is_null' | 'is_not_null': Deterministic filter operator.
      - `value` unknown
      - `values` unknown[], nullable: List comparison values for in.
        - unknown
  - `limit` integer, nullable: Top-N limit
  - `order` string: desc | asc
  - `constraints` ConstraintSpec
    - `requires_derived` boolean: Reject if metric column is not a derived_measure (formula-proven).
    - `no_cross_source` boolean: Reject if query requires a cross-source join.
    - `min_column_confidence` number: Reject if column_confidence component < this value.
    - `max_join_hops` integer: Safe default join-path budget for planner-generated cross-source queries. Defaults to 4 hops; explicit opt-in can raise this to 6 hops (7 tables).
  - `raw_text` string, nullable: Optional non-authoritative raw text hint. Structured intent remains the source of truth.
  - `include_explanation` boolean
  - `allow_org_scope` boolean: When true, resolve can consider all visible datasets in the org.

## Response `200`

Successful Response

- ResolveResponse
  - `resolved_plan` ResolvedPlanOutput
    - `source_name` string, required
    - `metric_column` string, required
    - `aggregation` string: sum | avg | count | max | min
    - `group_column` string, nullable
    - `join_path` JoinPathSpec: Explicit multi-hop join contract replacing single-hop join fields.
      - `base_source` string, required: Source that owns the metric column and anchors the path.
      - `group_source` string, nullable: Final source expected to provide the group column, if different from base_source.
      - `edges` JoinEdgeSpec[]: Ordered join edges from base_source toward the dimension source.
        - `left_source` string, required: Source on the left side of the join edge.
        - `right_source` string, required: Source on the right side of the join edge.
        - `left_key` string, required: Exact join key column in left_source.
        - `right_key` string, required: Exact join key column in right_source.
        - `join_type` string: Join type. Initial implementation supports inner.
        - `min_confidence` number: Minimum acceptable confidence for this hop.
        - `expected_cardinality` string, nullable: Optional expected cardinality such as one_to_many, many_to_one, or many_to_many.
        - `allow_many_to_many` boolean: If false, planner/executor must reject many_to_many fanout on this hop.
      - `max_hops` integer: Maximum allowed join hops for this request. Defaults to 4; explicit opt-in can raise this to 6 hops (7 tables).
      - `min_path_confidence` number: Minimum acceptable composed confidence across the full join path.
      - `reject_on_ambiguity` boolean: Reject if more than one viable path exists with insufficient score separation.
      - `reject_on_fanout` boolean: Reject if estimated path fanout exceeds safe execution thresholds.
    - `filter` FilterSpec: Time or value filter.
      - `time_filter` string, nullable: Relative time window. One of: last_quarter, this_quarter, last_month, this_month, last_year, this_year.
      - `conditions` FilterConditionSpec[]: Optional deterministic non-time predicates applied on the metric source. These are record predicates over normalized rows, not SQL clauses. Use exact column when schema is known, or dimension_hint for categorical dimensions when only the semantic label is known, including Redis and other non-SQL sources after normalization. Supported ops: eq, in, gt, gte, lt, lte, is_null, is_not_null.
        - `column` string, nullable: Exact source column name for this filter when schema is known.
        - `dimension_hint` string, nullable: Weak semantic label for the filter dimension when the exact column name is not known yet. Best for status/type/category style filters.
        - `op` 'eq' | 'in' | 'gt' | 'gte' | 'lt' | 'lte' | 'is_null' | 'is_not_null': Deterministic filter operator.
        - `value` unknown
        - `values` unknown[], nullable: List comparison values for in.
          - unknown
    - `limit` integer, nullable
    - `order` string: desc | asc
    - `constraints` ConstraintSpec
      - `requires_derived` boolean: Reject if metric column is not a derived_measure (formula-proven).
      - `no_cross_source` boolean: Reject if query requires a cross-source join.
      - `min_column_confidence` number: Reject if column_confidence component < this value.
      - `max_join_hops` integer: Safe default join-path budget for planner-generated cross-source queries. Defaults to 4 hops; explicit opt-in can raise this to 6 hops (7 tables).
    - `schema_revision` string, required
  - `confidence` number, required
  - `plan` string[], required
  - `explanation` string[]
  - `resolved_column` string
  - `resolved_role` string
  - `resolved_source` string
  - `candidates` CandidateColumn[]
    - `source` string, required
    - `column` string, required
    - `role` string, required
    - `magnitude` string, required
    - `formula` string, nullable, required
    - `confidence` number, required
    - `score_components` object
    - `notes` string[]
  - `source_scores` object
  - `latency_ms` number, required
  - `decision_path` string, required
  - `plan_hash` string, nullable
  - `schema_revision` string, required
  - `validated` boolean, required
  - `deterministic_scope` string, required
  - `confidence_source` string, required
  - `clarification_required` boolean
  - `rejection_reason` string, nullable
  - `request_id` string, nullable
  - `intent_signature` string, required
  - `source_set` string[]
  - `join_path` object[]
  - `planner_mode` string

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/codna/apis/algenta-api.md) · [All operations](https://skmtc.dev/codna/apis/algenta-api/llms.txt) · [OpenAPI document](https://skmtc.dev/codna/apis/algenta-api/revisions/35d30f84a5df?raw)