Natural-Language Questions

You can ask a semantic model a question in plain English, for example "top 5 regions by revenue where status is 'paid'". SemanticFed translates the question into one read-only SQL statement over the model's governed entities, dimensions, metrics and relationships, never raw source tables. It then runs the statement through the SQL endpoint, so ROW filters, COLUMN masks, ENTITY denials, row and time limits and the audit trail all apply.

Each answer shows how the question was read: the generated SQL, the interpretation steps, a confidence score and any words that were ignored. You can check the answer or open the SQL in the editor and change it.

Status

Surface	Status
GraphQL API (semAskQuestion, semTranslateQuestion)	Available
"Ask a question" panel in the SemanticFed app (Query Console page)	Available
LLM-assisted phrasing (free-form wording, synonyms the model does not register) and multi-turn follow-up questions	Roadmap

How a question is answered

The translator is a deterministic semantic parser grounded in the model. It does not call an AI model provider and reads no data while translating, so the same question on the same model always gives the same SQL.

1. Ground the words. The question's words and phrases are matched against the names and descriptions of the model's entities, dimensions and metrics. Matching handles plurals and word forms, snake_case and camelCase names, and a small set of business synonyms (for example sales, income or turnover for a revenue metric, client or buyer for a customer dimension).
2. Read the intent. It picks out the measures (total, average, how many, distinct), the groupings (by, per, for each), filters (where region is 'EU', in the US region, status = 'paid'), ordering (highest first, descending) and limits (top 5, the 3 lowest).
3. Plan the query. A metric uses its governed aggregation (a SUM metric is summed) unless the question asks for another one. Entities are joined only along the model's registered relationships.
4. Validate. The SQL is checked with the SQL endpoint's own parser and binder before it is returned, so a translated question always runs.
5. Ask instead of guessing. If the question cannot be answered reliably, the result is NEEDS_CLARIFICATION with a reason, an explanation and example questions the model can answer, and nothing is run.

Clarification reason	Meaning
EMPTY_QUESTION	No question was given. The response still carries example questions.
TOO_LONG	The question is over 1,000 characters.
NO_MATCH	Nothing in the question names an entity, dimension or metric of the model.
NO_JOIN_PATH	The question combines entities that no relationship of the model connects.
UNSUPPORTED_AGGREGATION	The question needs an aggregation the engine does not support, such as a MEDIAN metric.
INVALID_FILTER	A filter value does not fit the column's data type.
LOW_CONFIDENCE	Too much of the question matches nothing in the model to answer it reliably.
INVALID_QUERY	The interpretation did not produce a valid statement for the model.

API

Both operations use the same authenticated workspace gateway as the GraphQL API and the SQL endpoint.

Operation	Permission	Metering	Purpose
semTranslateQuestion(input)	read semanticfed-model	Not metered	Translate a question without running it
semAskQuestion(input)	execute semanticfed-query	One query run (semanticfed.query_runs.monthly)	Translate a question and return the governed rows

input takes question (required), modelId (optional when the workspace has exactly one model), maxRows (default 1,000, maximum 10,000) and timeoutMs (default 30,000, maximum 60,000).

mutation Ask($input: SemNlQuestionInput!) {
  semAskQuestion(input: $input) {
    translation {
      status
      sql
      confidence
      steps { kind entity field aggregation governed operator value direction count }
      unmatchedTerms
      clarificationReason
      clarification
      suggestions
    }
    result {
      columns { name dataType masked mask }
      rows
      rowCount
      truncated
    }
  }
}

With variables {"input": {"modelId": "<model id>", "question": "top 5 regions by revenue"}}, a model with an Orders entity, a region dimension and a SUM metric revenue returns:

SELECT region, SUM(revenue) AS revenue
FROM Orders
GROUP BY region
ORDER BY revenue DESC
LIMIT 5

and the governed rows in result. When the question needs clarification, result is null and nothing runs.

Privacy and audit

Each answered question is written to the workspace activity log with a SHA-256 hash of the question, not its text, because a question can contain sensitive values. The executed statement is also audited by the SQL endpoint. No part of the question or the model is sent to an AI model provider.

Accuracy

The translator ships with an evaluation suite in wspace-semanticfed-svc. It holds 53 reviewed question and SQL pairs, every one of which must translate exactly, plus 20 paraphrases that must reach at least 90% accuracy, and grounding checks that make sure no answer names anything the model does not register. The doctor E2E nl section asks real questions against production and checks the rows, the clarification path and policy enforcement.