docs: add MDL reference docs for Model, Relationship, and View

[goldmedal]

Summary

• Add docs/mdl/model.md — full reference for Model fields, data source options (table_reference, ref_sql, base_object), column types (regular, calculated, relationship), column-level access control via selective exposure, and engine internals (physical schema registration, is_hidden, expression resolution)
• Add docs/mdl/relationship.md — reference for Relationship fields, join types, condition syntax, usage in queries and calculated columns, and engine internals (resolution pipeline, TO_MANY aggregate subqueries)
• Add docs/mdl/view.md — reference for View fields, Model vs View comparison, jaffle_shop examples, and engine internals (ExpandWrenViewRule, session registration, recursive expansion)

All three docs use the jaffle_shop dataset for consistent examples throughout.

Test plan

• Review docs for accuracy against source code
• Verify jaffle_shop examples are consistent across all three files
• Check internal cross-links (./relationship.md, ./model.md) resolve correctly

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added comprehensive documentation for Models, covering definition, required components, field specifications, and usage examples.
  • Added detailed guide for Relationships, explaining join types, configuration, and automatic query resolution.
  • Added documentation for Views, including structure, querying patterns, and schema inference from SQL statements.

[coderabbitai]

📝 Walkthrough

Walkthrough

Three new documentation files are introduced describing MDL features: Model (comprehensive overview of structure, fields, and internals), Relationship (join paths between models with validation and resolution details), and View (named SQL queries with schema inference and query expansion behavior).

Changes

Cohort / File(s)

Summary

MDL Documentation docs/mdl/model.md, docs/mdl/relationship.md, docs/mdl/view.md

Added three reference documents covering Model (definition, components, YAML/JSON representation, fields, data sources, columns, cross-model relationships), Relationship (join paths, join types, condition syntax, resolution pipeline, aggregate handling), and View (named queries, schema inference, session registration, query-time expansion via ExpandWrenViewRule). Includes examples, schemas, and engine internals for each feature.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~10 minutes

Suggested reviewers

• douenergy

Poem

🐰 With whiskers twitching, ears held high,
Three docs now bloom beneath the sky,
Models, Views, and Relationships true—
The MDL path is crystal clear and new!
Hop, hop, hooray for knowledge shared! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title accurately and concisely summarizes the main change: adding three MDL reference documentation files for Model, Relationship, and View features.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

docs/mdl/model.md (2)

407-419: Add language specifier to fenced code block.

The code block at line 407 should specify a language (or text) for proper syntax highlighting and markdown linting compliance.

📝 Suggested fix

-```
+```text
 Column definition
 │
 ├── is_hidden: true       → stripped from symbol table; invisible to all clients

As per coding guidelines, static analysis tool markdownlint-cli2 flagged this as MD040 (fenced-code-language).

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/mdl/model.md` around lines 407 - 419, The fenced code block that begins
with "Column definition" lacks a language specifier, causing markdownlint MD040;
update the opening fence for that block (the triple-backtick preceding the
"Column definition" text) to include a language token such as "text" (e.g.,
change ``` to ```text) so the block is explicitly marked and syntax
highlighting/linting passes.

---

187-187: Add language specifier to fenced code block.

The code block at line 187 should specify a language for proper syntax highlighting and markdown linting compliance.

📝 Suggested fix

-```
+```text
 raw_orders ──► stg_orders ──► orders
 raw_customers ──► stg_customers ──► customers
 raw_payments ──► stg_payments

</details>

As per coding guidelines, static analysis tool markdownlint-cli2 flagged this as MD040 (fenced-code-language).

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @docs/mdl/model.md at line 187, The fenced code block containing the diagram
lines "raw_orders ──► stg_orders ──► orders" etc. lacks a language specifier;
update that fenced block to include a language (e.g., add "text" after the
opening triple backticks so it becomes ```text) to satisfy markdownlint MD040
and enable proper syntax highlighting for that block.

</details>

</blockquote></details>

</blockquote></details>

<details>
<summary>🤖 Prompt for all review comments with AI agents</summary>

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @docs/mdl/relationship.md:

• Line 155: The docs incorrectly state that relation_chain builds a LEFT JOIN;
  update the sentence in docs/mdl/relationship.md to state that relation_chain
  resolves the join path using a RIGHT JOIN (matching the implementation in
  relation_chain.rs); reference the implementation which uses
  LogicalPlanBuilder::join_on with datafusion::logical_expr::JoinType::Right so
  the documentation and the code (relation_chain) remain consistent.

---

Nitpick comments:
In @docs/mdl/model.md:

• Around line 407-419: The fenced code block that begins with "Column
  definition" lacks a language specifier, causing markdownlint MD040; update the
  opening fence for that block (the triple-backtick preceding the "Column
  definition" text) to include a language token such as "text" (e.g., change totext) so the block is explicitly marked and syntax highlighting/linting
  passes.
• Line 187: The fenced code block containing the diagram lines "raw_orders ──►
  stg_orders ──► orders" etc. lacks a language specifier; update that fenced block
  to include a language (e.g., add "text" after the opening triple backticks so it
  becomes ```text) to satisfy markdownlint MD040 and enable proper syntax
  highlighting for that block.

</details>

---

<details>
<summary>ℹ️ Review info</summary>

<details>
<summary>⚙️ Run configuration</summary>

**Configuration used**: defaults

**Review profile**: CHILL

**Plan**: Pro

**Run ID**: `6feee006-96d9-4dee-b330-24026d824341`

</details>

<details>
<summary>📥 Commits</summary>

Reviewing files that changed from the base of the PR and between fc1c54b1112b4ba22349d2375abc864cfb9b0900 and 49e7dd6cf043d7d0cfa87b45471f582fa6384c04.

</details>

<details>
<summary>📒 Files selected for processing (3)</summary>

* `docs/mdl/model.md`
* `docs/mdl/relationship.md`
* `docs/mdl/view.md`

</details>

</details>

<!-- This is an auto-generated comment by CodeRabbit for review status -->