docs: add custom ordering for categorical values recipe

[keydunov]

Add a recipe showing how to sort categorical dimensions (e.g., pipeline stages) in a business-meaningful order using a CASE expression, both at query time in semantic SQL and as a permanent dimension in the data model.

Made-with: Cursor

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 11, 2026, 4:31 PM

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

[claude]

Claude finished @keydunov's task in 1m 39s —— View job

---

Review of PR #10671

• Read and analyze changed files
• Review documentation content and accuracy
• Check navigation/config changes
• Post review feedback

---

Overall: This is a well-written recipe that clearly explains two approaches to custom ordering of categorical values. The writing is clean, the examples are practical, and the structure follows existing recipe patterns well. A few minor items below.

Issues

1. Result table column name mismatch (minor)

The result table at line 167 uses funnel_order as the column header, which matches the query-level approach (line 46: AS funnel_order). However, the data model approach names the dimension forecast_category_order (line 86/114) and the second SQL query on line 152 selects forecast_category_order — not funnel_order.

Since the "Result" section says "Both approaches produce the same result," the table is slightly misleading for the data model approach where the column would actually be named forecast_category_order. Consider either:

• Adding a note that the column name differs between approaches, or
• Showing two small result tables (one per approach), or
• Aliasing the column in the second query: forecast_category_order AS funnel_order

Fix this →

2. Unused reference links (nitpick)

Two reference-style links defined at the bottom of custom-order.mdx are never used in the body:

• [ref-data-apis] (line 183) — not referenced anywhere in the text
• [ref-custom-sorting] (line 185) — not referenced anywhere in the text

These are harmless but add unnecessary clutter. Consider removing them or adding relevant cross-references to the existing Custom sorting recipe (which covers REST API-level sorting and could be a nice "see also" from this recipe).

Fix this →

Looks Good

• Recipe structure: Follows the established pattern (Use case → approaches → data model examples with YAML/JS CodeGroup → Result).
• Reference syntax: {forecast_category} in YAML and ${forecast_category} in JS are consistent with other recipes (e.g., nested-aggregates.mdx).
• MEASURE() usage: Correctly used in semantic SQL examples, consistent with other recipes.
• Navigation: docs.json entry added at the end of the data modeling recipe list — clean placement.
• Index page: The new card is properly added to the "Data Modeling" section, recipe count updated to 39 (verified: matches actual Card count).
• Writing quality: Clear, concise prose. Good framing of when to use each approach (ad-hoc vs. permanent).