Describe the model in its asset definition

Document decisions, not obvious syntax

Good documentation tells a future analyst what the model means, who can answer questions about it, and where its limits are. Repeating SUM(recognized_revenue) in prose does not explain why pending and refunded orders are excluded.

Documentation also gives reviewers a stable place to challenge a metric definition before dashboards depend on it.

Add ownership and column descriptions

Expand the Bruin header in commerce/assets/analytics/customer_daily_revenue.sql with these fields. Keep the materialization and checks you already added.

description: >-
  Daily customer order activity. In this course, recognized revenue means
  paid order amount and excludes pending or refunded orders.
owner: [email protected]
tags:
  - layer:mart
  - domain:commerce
meta:
  business_owner: [email protected]
  metric_definition: >-
    Course metric: sum of order amount where normalized order status is paid.
  currency: Source currency; this version does not convert currencies.
  expected_update: daily
  known_limitation: >-
    Customer country uses the current customer record. This is not an
    accounting revenue-recognition policy.
columns:
  - name: customer_id
    type: string
    description: Customer identifier from the operational order system.
    primary_key: true
    checks:
      - name: not_null
  - name: order_date
    type: date
    description: Calendar date derived from the order timestamp.
    primary_key: true
    checks:
      - name: not_null
  - name: country
    type: string
    description: Current country from the customer dimension.
  - name: total_orders
    type: integer
    description: Count of all orders received for the customer and date.
  - name: paid_orders
    type: integer
    description: Count of orders whose normalized status is paid.
  - name: recognized_revenue
    type: decimal
    description: Paid order amount in the source currency.
    checks:
      - name: non_negative
  - name: refunded_amount
    type: decimal
    description: Order amount whose normalized status is refunded.

Use real team addresses in a working project. The example addresses make the two responsibilities visible: the analytics owner maintains the model, while the finance owner approves the business definition.

This course treats a paid order amount as its recognized_revenue metric. That is a teaching shortcut, not a financial revenue-recognition policy. Production finance reporting needs the policy, timing rules, and adjustments approved by the finance team.

Keep the metric context with the model

The asset header is the source of truth for this metric. It records the model owner, business owner, metric definition, source-currency limitation, update schedule, and column meanings beside the SQL that produces the table.

The limitations are part of the contract. Hiding them does not make the metric more accurate.

Ask your coding agent

Check sample rows

Compare two rows with the source:

bruin query --connection duckdb-default \
  --description "inspect source order facts for two sample customers" \
  --query "SELECT order_id, customer_id, order_date, order_status, order_amount FROM analytics.fct_orders WHERE customer_id IN ('C001', 'C004') ORDER BY order_id;"
bruin query --connection duckdb-default \
  --description "reconcile daily revenue for two sample customers" \
  --query "SELECT * FROM analytics.customer_daily_revenue WHERE customer_id IN ('C001', 'C004') ORDER BY order_date, customer_id;"

Keep the result with your local command output:

C001 on 2026-01-01: two orders, one paid, recognized revenue 49.00.
C004 on 2026-01-03: one paid order, recognized revenue 120.00.

Checkpoint

Another analyst should now be able to find what one row represents, the metric definition, the owner, the update schedule, and the known limitation without reading the SQL body.