Docs data modeling improvements

[keydunov]

Check List

• Tests have been run in packages where changes have been made if available
• Linter has been run for changed code
• Tests for the changes have been added if not covered yet
• Docs have been added / updated if required

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
cubed3	🟡 Building	–	Apr 16, 2026, 4:08 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[claude]

Claude finished @keydunov's task in 3m 49s —— View job

---

Review of PR #10698 — Docs data modeling improvements

• Gather context and review PR diff
• Review navigation structure changes (docs.json)
• Review new standalone pages for completeness and accuracy
• Check for broken links and cross-references
• Review deleted content to ensure nothing important was lost
• Compile and post review feedback

---

Overall Assessment

This is a well-executed restructuring of the data modeling documentation. The old monolithic "Concepts" page (~860 lines) and its sub-pages are replaced by focused, standalone pages for Cubes, Views, Dimensions, Measures, Joins, and Multi-fact Views. The new pages are clearly written, provide both YAML and JavaScript examples, and follow a consistent structure. The navigation is now more intuitive — users can go directly to the topic they need.

Excellent work overall. A few issues to address below.

---

Broken Anchor Links

1. #join-paths anchor doesn't exist in new joins.mdx

The heading in joins.mdx is ## Join paths in calculated members (line 461), which produces the anchor #join-paths-in-calculated-members. But two files reference #join-paths:

• docs-mintlify/docs/data-modeling/concepts/syntax.mdx:1003 — [ref-join-paths]: /docs/data-modeling/joins#join-paths
• docs-mintlify/reference/core-data-apis/sql-api/joins.mdx:212 — [ref-join-paths]: /docs/data-modeling/joins#join-paths

Fix this →

2. #join-hints anchor doesn't exist in new joins.mdx

The "Join hints" section from the deleted working-with-joins.mdx was not migrated to the new joins.mdx. Two files still reference it:

• docs-mintlify/reference/core-data-apis/rest-api/query-format.mdx:693 — [ref-join-hints]: /docs/data-modeling/joins#join-hints
• docs-mintlify/reference/core-data-apis/sql-api/joins.mdx:213 — [ref-join-hints]: /docs/data-modeling/joins#join-hints

This content needs to either be added to the new joins.mdx page, or the links should point elsewhere.

---

Missing Page in Navigation

data-blending dropped from nav without redirect

The page docs/data-modeling/concepts/data-blending was part of the old "Concepts" navigation group but is not included in the new docs.json navigation structure. The file itself still exists (docs-mintlify/docs/data-modeling/concepts/data-blending.mdx), and it is still referenced from 7 files:

• docs-mintlify/docs/data-modeling/concepts/syntax.mdx:995
• docs-mintlify/reference/core-data-apis/rest-api/reference.mdx:870
• docs-mintlify/reference/data-modeling/joins.mdx:668
• docs-mintlify/reference/javascript-sdk/angular.mdx:39
• docs-mintlify/reference/javascript-sdk/react.mdx:39
• docs-mintlify/reference/javascript-sdk/vue.mdx:39
• docs-mintlify/reference/javascript-sdk/index.mdx:44

The page is now an orphan — it exists but is not reachable from the sidebar. Should it be added to the new nav structure, or should references be redirected?

---

Content Not Migrated from Deleted Pages

Several sections from the deleted pages were not carried over to the new standalone pages. This may be intentional, but worth confirming:

Deleted section	Source file	Notes
Join hints (SQL API, REST API)	working-with-joins.mdx	Referenced from query-format.mdx and sql-api/joins.mdx — actively linked, broken
Transitive join pitfalls	working-with-joins.mdx	Troubleshooting guidance for a common mistake
Measure additivity	concepts/index.mdx	Referenced from matching-pre-aggregations.mdx (now redirected to generic measures#type)
Leaf measures	concepts/index.mdx	Referenced from matching-pre-aggregations.mdx (now redirected to generic measures#type)
Join paths in views	working-with-joins.mdx	Views join_path patterns were covered there; now partially in views.mdx
Join paths in pre-aggregations	working-with-joins.mdx	How join_path works in pre-aggregations context
Bidirectional joins (standalone section)	working-with-joins.mdx	Renamed to "Using views to control direction" — good improvement, but the old anchor may be linked externally

---

Minor Issues

1. Duplicate link definition in syntax.mdx

Lines 990 and 999 both define [ref-time-dimension] with different targets:

990: [ref-time-dimension]: /reference/data-modeling/dimensions#type
999: [ref-time-dimension]: /docs/data-modeling/dimensions#time-dimensions

The second definition overrides the first. This is a pre-existing issue but the PR modified line 999, so worth cleaning up.

2. Missing newline at end of several files

Multiple modified files are missing a trailing newline (the \ No newline at end of file marker in diffs). Not a blocker, but worth a quick fix for consistency:

• docs-mintlify/docs/data-modeling/concepts/syntax.mdx
• docs-mintlify/reference/data-modeling/cube.mdx
• docs-mintlify/reference/data-modeling/measures.mdx
• Several recipe files

3. multi-fact-views.mdx Tesseract link inconsistency

In multi-fact-views.mdx:421, the Tesseract blog link uses a different URL (/introducing-tesseract) than in measures.mdx:434 which uses /introducing-next-generation-data-modeling-engine. These should be consistent (likely the latter is correct).

---

Positives

• Clear, focused structure: Each new page has a single responsibility — much easier to navigate than the old monolithic "Concepts" page
• Consistent format: All pages follow the pattern of definition → examples (YAML + JS) → advanced patterns → next steps
• Excellent examples: The new joins.mdx does a great job explaining direction of joins with concrete SQL output
• Good cross-references: The "Next steps" sections at the bottom of each page guide readers naturally through the docs
• multi-fact-views.mdx is outstanding: The step-by-step breakdown of how Cube handles multi-fact queries under the hood is very clear and well-structured
• polymorphic-cubes moved to recipes: Good organizational choice — it's a pattern/recipe, not a core concept