Natural Language Queries

The Natural Language interface allows users to ask business questions in plain English. The Semantic Layer translates these questions into structured metric queries using WrenAI, then compiles and executes them against the underlying data. This provides an intuitive way for non-technical users to access analytics without writing SQL.

How It Works

User: "What was total revenue by region last quarter?"
    |
    v
WrenAI Translation Engine
    |
    v
Semantic Query:
  model: sales_analytics
  metrics: [total_revenue]
  dimensions: [region]
  timeDimension: order_date
  timeGrain: QUARTER
  relativeTimeRange: "last quarter"
    |
    v
SQL Compilation and Execution
    |
    v
Query Results

Available Endpoints

Translate Endpoint

Translates a natural language question into a structured semantic query without executing it.

Request:

{
  "modelId": "550e8400-e29b-41d4-a716-446655440000",
  "question": "What was total revenue by region last quarter?"
}

Response:

{
  "question": "What was total revenue by region last quarter?",
  "semanticQuery": {
    "modelId": "550e8400-e29b-41d4-a716-446655440000",
    "metrics": ["total_revenue"],
    "dimensions": ["region"],
    "timeDimension": "order_date",
    "timeGrain": "QUARTER",
    "relativeTimeRange": "last quarter"
  },
  "status": "success"
}

Ask Endpoint

Translates and executes a natural language question in a single request, returning data results.

Request:

{
  "modelId": "550e8400-e29b-41d4-a716-446655440000",
  "question": "How many orders were placed this month?"
}

Response:

The response follows the standard ExecuteResult format with data, columns, totalRows, executionTimeMs, fromCache, and sql fields.

Query Suggestions

The suggestions endpoint provides autocomplete-style recommendations based on partial input and the model's available metrics and dimensions.

Example Request:

GET /api/v1/nl/suggestions?modelId=550e8400...&query=total

Example Response:

[
  "What is the total revenue?",
  "What is the total order count by region?",
  "What is the total revenue trend over the last 12 months?",
  "What is the total revenue by product category?"
]

Query Explanation

The explain endpoint generates a human-readable description of what a semantic query will compute.

Request: A standard ExecuteRequest body with metrics, dimensions, filters, etc.

Response:

{
  "explanation": "This query will compute total_revenue grouped by region where order_date >= 2026-01-01 at month granularity (limited to 100 results).",
  "query": { ... }
}

Validation

The validate endpoint checks whether a natural language question can be answered using the specified model. This is useful for providing real-time feedback to users before executing a query.

Response:

{
  "isValid": true,
  "message": "Question can be answered",
  "semanticQuery": { ... }
}

A question is considered valid if the translation produces at least one metric or dimension.

WrenAI Integration

The natural language engine is powered by WrenAI, which uses the semantic model definitions to understand the available data schema. WrenAI maps natural language concepts to specific metrics, dimensions, and filters defined in the MDL.

Best Practices

• Define clear, descriptive metric and dimension names that match business terminology
• Use the validate endpoint to check questions before executing them
• Provide a model ID to scope translation to relevant metrics and dimensions
• Use the suggestions endpoint to guide users toward well-formed questions
• Review translated queries before execution for sensitive data access