Wren Engine Documentation

Wren Engine is an open context engine designed to provide AI agents with a semantic, governed layer for business data. Instead of agents interacting with raw database tables, Wren Engine allows them to reason over business concepts.

Core Workflow

1. Modeling: Describe your business domain using Wren's semantic model and Modeling Definition Language (MDL).
2. Context Capture: Wren Engine captures models, metrics, relationships, and access rules.
3. Intent Analysis: The engine analyzes natural language intent and plans correct queries across underlying data sources.
4. Interaction: MCP clients and AI agents interact with this context through a clean interface.

Key Benefits for Agents

• Understand models instead of raw tables.
• Use trusted metrics instead of inventing SQL.
• Follow relationships instead of guessing joins.
• Respect governance instead of bypassing it.

Wren Engine uses a rewrite pipeline to transform your SQL. It injects Common Table Expressions (CTEs) that expand each MDL (Model Definition Language) model into its underlying database query.

The Rewrite Pipeline:

1. Parse & Qualify: Uses sqlglot to parse your SQL and qualify column references.
2. Identify: Detects which models and columns are referenced in your query.
3. Expand: For each model, wren-core expands the model definition into a CTE.
4. Inject: The model CTEs are injected into your query.
5. Output: The final SQL is produced in the target database dialect.

Example Transformation: If you have a model orders backed by table public.orders with columns o_orderkey, o_custkey, and o_totalprice:

Your Input:

SELECT o_custkey, SUM(o_totalprice) FROM orders GROUP BY 1

Engine Output (via dry-plan):

WITH "orders" AS (
  SELECT "public"."orders"."o_orderkey",
         "public"."orders"."o_custkey",
         "public"."orders"."o_totalprice"
  FROM "public"."orders"
)
SELECT o_custkey, SUM(o_totalprice) FROM orders GROUP BY 1

The CTE named "orders" shadows the model name, allowing the rest of your SQL to run against the CTE as if it were a standard table.

-- You write:
SELECT o_custkey, SUM(o_totalprice) FROM orders GROUP BY 1

-- Engine produces (via dry-plan):
WITH "orders" AS (
  SELECT "public"."orders"."o_orderkey",
         "public"."orders"."o_custkey",
         "public"."orders"."o_totalprice"
  FROM "public"."orders"
)
SELECT o_custkey, SUM(o_totalprice) FROM orders GROUP BY 1

The Wren MDL is a JSON manifest that defines the catalog, schema, data source, models (tables), columns, and relationships.

Key Mapping Rules for Generation:

• catalog: Use "wren" unless specified otherwise.
• schema: Use the target schema name (e.g., "public").
• dataSource: Use the enum value of the data source (e.g., "POSTGRES").
• tableReference.catalog: Set this to the actual database name, not "wren".
• models: Each table in the database corresponds to one Model entry.
• columns: Each column in the table corresponds to one Column entry. Mark primary keys with "isPrimaryKey": true and update the model's primaryKey field.
• relationships: Define links between models using joinType and a condition string.

{
  "catalog": "wren",
  "schema": "public",
  "dataSource": "POSTGRES",
  "models": [
    {
      "name": "orders",
      "tableReference": {
        "catalog": "my_db_name",
        "schema": "public",
        "table": "orders"
      },
      "columns": [
        {
          "name": "order_id",
          "type": "INTEGER",
          "isPrimaryKey": true,
          "isCalculated": false,
          "notNull": true
        }
      ],
      "primaryKey": "order_id"
    }
  ],
  "relationships": [
    {
      "name": "orders_customer",
      "models": ["orders", "customers"],
      "joinType": "MANY_TO_ONE",
      "condition": "orders.customer_id = customers.customer_id"
    }
  ]
}