Add ai_hint to Orders explore and referrer dimension for agent routing

[lightdash]

Review finding

"Empty response despite successful query execution on dbt_orders with referrer breakdown"

An AI agent successfully queried the Orders explore with order_date_month, referrer, and an order-count metric, but the response path suggested dbt_orders_referrer may not be reliably routed. Investigation confirmed the referrer dimension is already exposed as a plain string dimension — no field declaration or join was missing.

Root cause

The referrer field name exists in three explores (dbt_orders, dbt_orders_no_preagg, and dbt_support_requests), with no ai_hint on either the explore or the field to disambiguate. Agents lacked guidance on which explore to target for order-level referrer breakdowns, causing unreliable routing.

Change made

Two targeted ai_hint additions in models/dbt_orders.yml — no SQL changes:

1. Explore-level ai_hint (under models[dbt_orders].meta) — tells agents that Orders is the primary explore for order trends broken down by referrer, and distinguishes it from dbt_support_requests which has a referrer field in a different context.

2. Dimension-level ai_hint (on the referrer column's meta.dimension) — clarifies that this field is for order-level traffic-source attribution and directs agents to use dbt_orders (not dbt_support_requests) when the question is about order volume or revenue by referrer.

Descriptions were not changed; routing guidance is placed exclusively in ai_hint per project conventions.

[lightdash]

🔍 Lightdash preview environment ready: https://analytics.lightdash.cloud/projects/46a6c261-d7be-4b46-95b7-c3983a639ca3/home

Compiled from branch lightdash-ai-writeback/e8240f90-3ae2-4a7b-bce9-cee8ff7052d8. Explores may take a minute to appear while the project compiles.

[github-actions]

🚀 Deployed 39f5f5d to https://analytics.lightdash.cloud/projects/c6e727e3-90b5-4c75-abea-5709440f3ffe/tables

[github-actions]

Lightdash Validation Results

Validating default project 8a223608-a1e4-426e-adcd-0598ea72b9f8

/opt/hostedtoolcache/Python/3.10.20/x64/lib/python3.10/site-packages/google/api_core/_python_version_support.py:255: FutureWarning: You are using a Python version (3.10.20) which Google will stop supporting in new releases of google.api_core once it reaches its end of life (2026-10-04). Please upgrade to the latest Python version, or at least Python 3.11, to continue receiving updates for google.api_core past that date.
  warnings.warn(message, FutureWarning)
/opt/hostedtoolcache/Python/3.10.20/x64/lib/python3.10/site-packages/google/api_core/_python_version_support.py:255: FutureWarning: You are using a Python version (3.10.20) which Google will stop supporting in new releases of google.cloud.dataproc_v1 once it reaches its end of life (2026-10-04). Please upgrade to the latest Python version, or at least Python 3.11, to continue receiving updates for google.cloud.dataproc_v1 past that date.
  warnings.warn(message, FutureWarning)

- SUCCESS> dbt_users 
- SUCCESS> dbt_orders 
- SUCCESS> dbt_baskets 
- SUCCESS> dbt_orders_no_preagg 
- SUCCESS> dbt_support_requests 

Compiled 5 explores, SUCCESS=5 ERRORS=0
-   Waiting for validation to finish
✖   Validation finished in 18s with 2 errors


- Tables: 0 errors
- Charts: 1 errors
- Dashboards: 1 errors


NAME                                    LAST UPDATED BY LAST UPDATED AT ERROR                                                                           
Partner Sales by Month - Last 12 Months Rohan Bedi        2026-06-23    Metric error: the field 'monthly_partner_info_total_sales' no longer exists     
Sales Updates                           Ian Ahuja         2026-01-14    The chart 'Partner Sales by Month - Last 12 Months' is broken on this dashboard.

--> To see these errors in Lightdash, run lightdash preview

Note: 4 chart configuration warnings hidden. Use --show-chart-configuration-warnings to show.

This validation check is informational and does not block merging.