Wren Ontology Manual for Analysts

Why

You cannot check a change if you do not know the correct answer first.

Who

Analyst, with the business owner

Needs

A trusted report or checked SQL result

1. Write the business question in one sentence.
2. Name the person who owns the definition.
3. Write what one output row represents (the grain).
4. List the output columns.
5. List the filters and the exclusions.
6. Write the date column and the time zone (UTC or WIB).
7. Write the currency and the rounding rule.
8. Record the expected row counts and totals.
9. Record the source and the date of the trusted result.

Business question:
Definition owner:
One output row represents:
Required columns:
Filters and exclusions:
Date column and time zone:
Currency and rounding:
Trusted comparison and date:
Expected counts and totals:
Known exceptions:
Affected models, views, rules, and SQL pairs:
dbt environment and deployed revision:
Reviewer:

Why

You must know where each column comes from before you change its meaning.

Who

Analyst, with the data engineer

Needs

dbt repository (../data-transformation), read access to Trino

1. Open the model file models/<name>/metadata.yml.
2. If the model has ref_sql.sql, open that file also.
3. Record each physical table that the model reads.
4. Find the dbt model that builds each table.
5. Read its SQL, configuration, macros, and column descriptions.
6. Read the dbt tests for uniqueness and nulls.
7. Ask the data engineer to confirm the deployed environment and revision.
8. Run DESCRIBE on the table in Trino.
9. Compare the Trino columns with the Wren column list.
10. Record each difference before you change a definition.

Example: trace product_data

DESCRIBE tiptip_datalake_prd_s7jc.data_staging.content_svc_product_clean;

-- Check a proposed primary key
SELECT
    COUNT(*)           AS row_count,
    COUNT(id)          AS nonnull_id_count,
    COUNT(DISTINCT id) AS distinct_id_count
FROM tiptip_datalake_prd_s7jc.data_staging.content_svc_product_clean;

Example

Add product publication status status_name to product_data. This is a proposed change.

Before

Complete Task A and Task B.

1. Make sure that Trino shows status_name as a text column.
2. Open wren-project/models/product_data/metadata.yml.
3. Add the item below inside the existing columns list.
4. Keep the existing columns and primary_key: id.
5. Write a description that tells what the column is not, if confusion is possible.
6. Do Task F to add the matching rule.

  - name: status_name
    type: VARCHAR
    properties:
      description: >-
        Product publication status from the cleaned dbt product model.
        This is not an order, booking, or refund status.

Make a new model only if necessary

First look in models/ for a model with the same source and grain. Extend that model if it exists. A new table model has this structure:

name: <model_name>
table_reference:
  catalog: tiptip_datalake_prd_s7jc
  schema: data_staging
  table: <physical_table>
properties:
  description: One row per <thing>. Use <key> to connect <other model>.
columns:
  - name: id
    type: BIGINT
    properties:
      description: Internal identifier.
primary_key: id

Why

A wrong relationship copies rows and makes totals too large.

See the fan-out problem

Procedure

1. Write the grain of both models.
2. Count null keys on both sides.
3. Check the "one" side for duplicate keys. Use the query below.
4. Count the rows before the join and after the join.
5. Compare the money totals before the join and after the join.
6. Count the rows that have no match.
7. If all checks pass, add the relationship to relationships.yml.

-- Step 3: must return no rows
SELECT id, COUNT(*) AS key_rows
FROM product_data
GROUP BY id
HAVING COUNT(*) > 1
LIMIT 20;

-- Step 4: for MANY_TO_ONE + LEFT JOIN, both counts must be equal
SELECT COUNT(*) AS source_rows FROM event_refund_transactions;

SELECT COUNT(*) AS joined_rows
FROM event_refund_transactions t
LEFT JOIN product_data p ON t.content_id = p.id;

  - name: event_refund_transactions_product
    models:
      - event_refund_transactions
      - product_data
    join_type: MANY_TO_ONE
    condition: event_refund_transactions.content_id = product_data.id

Rule

Shared data preparation goes in dbt. Wren-only meaning and reusable query shapes go in Wren.

Change model SQL

1. Open the model's ref_sql.sql.
2. Check each source table and each join.
3. Add the new expression to the SELECT list.
4. Add the output column to metadata.yml.
5. Check the grain and the totals again.

Add a view

1. Make sure that no existing object answers the question.
2. Make the folder wren-project/views/<view_name>/.
3. Make the file metadata.yml in that folder.
4. Write the grain in the description.
5. Write the SQL with Wren model names only.

name: published_product_directory
properties:
  description: One row per product with the publication status Published.
statement: |
  SELECT id, product_uid, title
  FROM product_data
  WHERE status_name = 'Published'

Why

Rules tell the AI about meanings that the schema cannot show.

1. Make the file wren-project/knowledge/rules/<topic>.md.
2. Write one statement per line. Use short sentences.
3. Write what the term means and what it does not mean.
4. Verify each statement against data or the owner.
5. Record the owner and the source in the change record.

## Product publication

Use product_data to resolve product identifiers.
Use id to connect product_data with transaction content_id.
Use product_uid to resolve an external event detail identifier.
Titles can repeat.

status_name describes product publication.
It does not describe payment, order, booking, or refund status.
Published status alone does not prove current ticket availability.

Why

The AI finds similar examples with recall_queries and copies their pattern.

Before

The query passes Task H against the trusted result.

1. Make the file wren-project/knowledge/sql/<question>.md.
2. Write the question in nl as a user would ask it.
3. Write the approved modeled SQL in sql.
4. Add a note about the limits of the example.
5. Remove customer data, IDs from real cases, and credentials.
6. If a definition changes, update all related examples in the same change.

---
nl: "List product identifiers and titles for products with publication status Published."
sql: |
  SELECT id, product_uid, title
  FROM product_data
  WHERE status_name = 'Published'
  ORDER BY id
source: user
datasource: trino
tags:
  - products
  - publication
---

This query uses product publication status.
It does not check ticket availability or payment status.
Check result limits before treating the returned list as complete.

Where

A separate checkout or a staging deployment

Image

wrenai==0.14.0, wren-core-py==0.7.6

1. In the candidate checkout, build to a temporary file.
2. Fix each build error. Build again.
3. Load the candidate into a separate staging Wren MCP service.
4. Start a new chat with the staging service.
5. Call get_instructions. Look for the new rule.
6. Call describe_model for each changed model.
7. Call recall_queries with the test question.
8. Call dry_plan. Read the translated tables, joins, and filters.
9. Call dry_run for the proposed SQL.
10. Call run_sql for the approved read-only checks.
11. Compare the results with the change record from Task A.
12. If you changed War Room SQL, run the synthetic tests.

# Step 1 — build without replacing the production manifest
docker compose run --rm --no-deps --entrypoint wren wren-mcp \
  context build --path /project --output /tmp/wren-validation-mdl.json

# Step 12 — synthetic checks (staging)
docker compose exec -T wren-mcp python /project/tests/test_war_room.py
docker compose exec -T wren-mcp python /project/tests/test_war_room_satusatu.py

Acceptance checks

Who

Deployment operator

Needs

Reviewed files, recorded checks, approved release window, a recoverable previous version

1. Record the current deployed Git revision.
2. Publish the reviewed source files to the deployment checkout.
3. Restart the Wren MCP service.
4. Read the startup log.
5. Make sure that the log shows "Built:" before "Starting Wren MCP Server".
6. Start a new chat with the deployed MCP service.
7. Do steps 5 to 11 of Task H again.
8. Record the release revision, the check time, and the result.

docker compose restart wren-mcp
docker compose logs --since=5m wren-mcp

==> Building Wren context...
Built: <model-count> models, <view-count> views → /project/target/mdl.json
==> Starting Wren MCP Server on port 8080...

When

The build fails, or the new definition gives wrong results.

1. If reports use the wrong definition, stop those reports.
2. Find the previous approved Git revision.
3. Restore the models, views, relationships, rules, and SQL pairs together.
4. Restart Wren with the commands in Task I.
5. Make sure that the build succeeds in the log.
6. Ask the previous acceptance questions in a new chat.
7. Record the failure and the restored revision.