docs: fill gaps from recent SQL API, dbt push, and deployment changes

[keydunov]

Summary

Routine scan of recent merges in cube-js/cube and cubedevinc/cubejs-enterprise for customer-facing changes missing from docs-mintlify. Four small gaps found and closed with surgical edits to existing pages (no new pages needed):

• SQL API pushdown (reference/core-data-apis/sql-api/query-format.mdx, reference.mdx, recipes/data-modeling/cross-data-source-queries.mdx):
  • A UNION/UNION ALL of queries that all reach the same data source is now pushed down as a single statement, so the row limit applies once to the combined result rather than per branch (feat(cubesql): Push UNION down to the data source #11651). Cross-referenced from the existing cross-data-source-queries recipe, which documents the still-unaffected per-branch case.
  • Aggregate functions taking more than one argument, and window functions over grouped subqueries/CTEs/joins, are now supported in pushdown (fix(cubesql): push down window functions and multi-argument aggregates #11684).
• dbt push (docs/integrations/dbt.mdx): new Validation level setting (Parse only / Compile (recommended, default) / Build in a validation schema) and Validation schema field, plus the per-warehouse grant requirements and the three adapters (BigQuery, Databricks, Athena) that currently fall back to parse-only (cubedevinc/cubejs-enterprise#14392).
• Default landing deployment (admin/deployment/index.mdx, docs/preferences.mdx): accounts with multiple deployments can now set an account-wide default (admin) and/or a personal default (per user), with the resolution order documented (cubedevinc/cubejs-enterprise#14519).

All four were verified against the actual diff/PR body (not just the commit subject) and confirmed absent from docs-mintlify before writing. No changes qualified as a "big" new-page-worthy feature in this pass, so no Linear ticket was needed.

One additional gap was found but intentionally not addressed here: the funnel chart type has no docs-mintlify page at all (missing from chart-types/index.mdx), which predates the PR that added its horizontal-orientation option (cubedevinc/cubejs-enterprise#14510). Flagging for a separate pass rather than folding a new page into this change.

Test plan

• Verified each change against git show/PR body, not just the commit subject
• Searched docs-mintlify to confirm no existing coverage before editing
• Docs maintainer review for tone/placement

---

Generated by Claude Code

[mintlify]

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

Project	Status	Preview	Updated (UTC)
cubed3	🟢 Ready	View Preview	Aug 30, 2026, 12:16 AM

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

[claude]

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

---

Review: docs gap-fill for SQL API pushdown, dbt push, default deployment

Docs-only change, well-scoped and correctly placed in docs-mintlify. Verified the union and multi-argument-aggregate claims against the cubesql rewrite rules; the union behaviour matches the rule comment in union.rs exactly. 6 findings: 0 high, 3 medium, 3 low — no blockers, all inline.

Full review — findings, verification notes, todo list

Todos

• Read PR diff against origin/master
• Verify pushdown claims against rust/cubesql rewrite rules
• Verify all new internal links and anchors resolve
• Cross-check the two new default-deployment sections for consistency
• Check for existing/stale Claude review threads (none found)
• Post inline findings + summary

Findings

#	Severity	File	Issue
1	Medium	reference/core-data-apis/sql-api/reference.mdx:516	The multi-argument-aggregate example is wrong — PERCENTILE_CONT in the documented WITHIN GROUP form takes one argument. The rule comment from #11684 names the real case, APPROX_PERCENTILE_CONT(expr, 0.5). The claim is also stated unconditionally, but transform_agg_fun_expr still gates on the per-dialect functions/<FUN> template.
2	Medium	docs/preferences.mdx:76-81	Contradicts the resolution order added in admin/deployment/index.mdx:23-25 — the preferences text drops the "last deployment they switched to" step, so it tells a user with Account default they'll land on the admin's pin when they'd actually land on their last-switched-to deployment.
3	Medium	sql-api/query-format.mdx:207-211	This paragraph and the recipe paragraph that cross-links to it name two different limits for the same behaviour: queries#row-limit (the 50k regular-query cap) here vs. configuration#maximum-row-limit in the recipe. Round-tripping the cross-reference, "the limit" changes identity.
4	Low	sql-api/reference.mdx:562-564	"Two kinds are supported, including over a grouped subquery, CTE, or join:" — the including clause modifies "two kinds" but actually qualifies the window's input; it reads as if there were more than two kinds.
5	Low	docs/integrations/dbt.mdx:614-615	Option is Build in a validation schema in one row and Build in the next and in the <Note> — looks like two settings. Also unclear whether Validation schema is required-but-ignored or hidden on the three adapters that fall back to parse-only.
6	Low	docs/integrations/dbt.mdx:666	"runs dbt deps plus the configured Validation level" — you run a check, not a level.

What checked out

• Union pushdown — rules/wrapper/union.rs confirms the same-data-source constraint (?input_data_source is a top-level element variable, so a union spanning two sources falls back to post-processing) and that both UNION and UNION ALL are handled via wrapper-push-down-distinct-to-union. The doc's framing matches. The row-limit consequence is a reasonable inference from "pushed down as a single statement" rather than something the code states — worth a maintainer confirming, separately from finding 3.
• Multi-argument aggregates — confirmed in aggregate_function.rs: agg_fun_expr_var_arg now matches the whole argument list. Behaviour is real; only the example is off.
• Links and anchors — /admin/deployment#default-deployment, #list-of-deployments, /docs/preferences#default-deployment, #query-pushdown and the new [ref-cross-data-source-queries] definition all resolve. {#custom-anchor} heading syntax is already used elsewhere in the repo (embedding/iframe/events.mdx), so that's consistent — though redundant here, since the auto-generated anchor would be identical.
• The dbt-push and default-deployment behaviours originate in cubedevinc/cubejs-enterprise and aren't verifiable from this repo; findings 2, 5 and 6 are internal-consistency and wording issues only. A maintainer should confirm the resolution order and the per-adapter fallback against the actual implementation.

Notes on the PR description

Flagging the missing funnel chart page as out of scope rather than folding it in was the right call. No test coverage applies (docs-only); mintlify broken-links per .cursor/rules/mintlify-mdx-gotchas.mdc would be the relevant check and I could not run it here (no dev-server/deps install in this environment).

· branch [`claude/gallant-ramanujan-0b34qw`](https://github.com/cube-js/cube/tree/claude/gallant-ramanujan-0b34qw)

[claude]

Claude finished @keydunov's task in 45s —— View job

---

Docs review — new commit addresses 1 of 6 prior threads; 5 still open (all low/medium, wording & link consistency)

Full review

• Gather context (PR diff vs origin/master, both commits)
• Re-check prior review threads against the current diff
• Resolve threads that the new commit addressed
• Verify anchors/links resolve within docs-mintlify
• Post review

What changed in 11fd421

docs-mintlify/reference/core-data-apis/sql-api/reference.mdx — the multi-argument aggregate paragraph was rewritten to use APPROX_PERCENTILE_CONT(expr, 0.5) and to say argument count is no longer the blocker while per-dialect support still is. That's the accurate description of the #11684 rule change (rust/cubesql/cubesql/src/compile/rewrite/rules/wrapper/aggregate_function.rs, transform_agg_fun_expr still gating on can_rewrite_template). Thread resolved.

Still open (re-affirmed, no duplicate comments posted)

File	Line	Concern
reference/core-data-apis/sql-api/query-format.mdx	211	The new pushdown paragraph links [ref-query-default-limit] → /reference/core-data-apis/queries#row-limit, while the recipe it cross-links to says "maximum row limit" → /docs/data-modeling/configuration#maximum-row-limit. Same behaviour, two different limits named on the round trip.
docs/preferences.mdx	81	Resolution order here omits "last deployment they switched to", contradicting admin/deployment/index.mdx:23-25.
docs/integrations/dbt.mdx	615	Build in a validation schema vs. Build read as two settings; and the Validation schema row still says "Required when … Build" without saying what happens on BigQuery/Databricks/Athena, where the <Note> says Build falls back to Parse only.
docs/integrations/dbt.mdx	667	"runs dbt deps plus the configured Validation level" — you run the check the level selects, not the level.
reference/core-data-apis/sql-api/reference.mdx	565	"Two kinds are supported, including over a grouped subquery, CTE, or join" — the "including" clause modifies the wrong noun; it qualifies the window's input, not the two kinds.

Each already has an unresolved thread with a suggestion block, so I didn't re-post.

One new, low-priority observation

reference.mdx:516 — "is no longer excluded from pushdown by its argument count" describes a delta rather than current behaviour. Reference docs are read by people who don't know which release changed what; "An aggregate function that takes more than one argument … can be pushed down, provided the target data source supports that function" says the same thing without dating itself. (This is my own suggested wording from the last pass, so: my miss — worth tightening before merge, not blocking.)

Verified clean

• All new anchors resolve: #default-deployment (both pages), #list-of-deployments, #query-pushdown (query-format.mdx:195).
• New link reference [ref-cross-data-source-queries] is defined and points at an existing page.
• All edits are in /docs-mintlify (active site), none in the deprecated /docs tree — matches CLAUDE.md.
• Mintlify component usage (<Note>, <Step>) and root-relative internal links follow the repo conventions.

Nothing security-, performance-, or test-related applies: this PR is documentation only.

· branch [`claude/gallant-ramanujan-0b34qw`](https://github.com/cube-js/cube/tree/claude/gallant-ramanujan-0b34qw)

[claude]

Claude Code is working…

I'll analyze this and get back to you.

View job run

[keydunov]

Addressed the tense observation from the second review pass too (reference.mdx:517, "no longer excluded" → stated as current behavior rather than a changelog-style delta). Pushed in de67fb5.

---

Generated by Claude Code

[claude]

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

---

Docs review — all 6 prior threads addressed; no new blocking findings (0 high, 0 medium, 1 low nit)

Full review

Todos

• Read the PR diff vs origin/master (all 4 commits)
• Re-check the 6 prior review threads against the current diff
• Verify anchors/link references resolve inside docs-mintlify
• Re-verify the union-pushdown claim against rust/cubesql rewrite rules
• Check cross-page consistency (deployment resolution order, row-limit naming)
• Post review

What the last two commits fixed

Prior finding	Status in current diff
PERCENTILE_CONT multi-arg example wrong	Fixed — reference.mdx:516 now uses APPROX_PERCENTILE_CONT(expr, 0.5) and states it as current behaviour ("can be pushed down, provided the target data source supports that function"), which also drops the release-delta phrasing I flagged last pass.
Two different limits named across the round trip	Fixed — query-format.mdx:207 now uses "maximum row limit" → /docs/data-modeling/configuration#maximum-row-limit, matching cross-data-source-queries.mdx:366.
preferences.mdx resolution order contradicted the admin page	Fixed — now restates "last switched to → admin pin → most recently created", consistent with admin/deployment/index.mdx:23-25.
"runs the configured Validation level"	Fixed — "runs dbt deps followed by the check your Validation level selects".
"Two kinds are supported, including over a grouped subquery…"	Fixed — the input clause now stands on its own sentence before the enumeration.
Build in a validation schema vs. Build; adapter fallback unclear	Fixed — shorthand defined on first mention, and the <Note> now says the form still requires a schema on BigQuery/Databricks/Athena while the run only parses and the schema goes unused.

All six threads are resolved (they were resolved by the author, not by me) and none of the concerns recur in the current text, so I posted no new inline comments.

Re-verified against code

• rules/wrapper/union.rs:20-25 — ?input_data_source is a top-level element variable, so a union spanning two sources falls back to post-processing. The doc's same-data-source framing and the recipe's "this per-half limit applies specifically because the two halves reach different data sources" both match the rule.
• rules/wrapper/aggregate_function.rs — agg_fun_expr_var_arg matches the whole argument list; transform_agg_fun_expr still gates on the per-dialect template, which the new "provided the target data source supports that function" wording now covers correctly.
• Anchors all resolve: ### Query pushdown → #query-pushdown (query-format.mdx:195), ## Maximum row limit (configuration.mdx:52), #default-deployment on both pages, #list-of-deployments. New reference [ref-cross-data-source-queries] is defined at query-format.mdx:457 and points at an existing page. Pre-existing [ref-query-default-limit] is still used at line 386, so it isn't orphaned.
• All edits are in /docs-mintlify; nothing touches the deprecated /docs tree. Mintlify component and root-relative-link conventions followed.

One low nit (non-blocking)

docs/integrations/dbt.mdx:615 — "Required by the form whenever Validation level is Build, on every adapter." The trailing "on every adapter" reads as a qualifier on the requirement rather than a pointer to the fallback caveat below. "Required whenever Validation level is Build, including on adapters that fall back to Parse only (see below)" ties the two rows together more directly. Purely wording.

Still worth a maintainer's eye (not a defect)

The row-limit consequence of union pushdown ("the limit applies once, to the combined result") is a reasonable inference from "pushed down as a single statement" but isn't something the rewrite rules state directly. Someone who has run the query should confirm it before merge.

Nothing security-, performance-, or test-related applies: this PR is documentation only. mintlify broken-links (per .cursor/rules/mintlify-mdx-gotchas.mdc) is the relevant check and I could not run it in this environment — link/anchor verification above was done by grep instead.

· branch claude/gallant-ramanujan-0b34qw ·

[claude]

Claude finished @keydunov's task in 43s —— View job

---

Docs review — 567319b closes the last open nit; no findings. Ready to merge (0 high, 0 medium, 0 low)

Full review

Todos

• Read the PR diff vs origin/master (all 5 commits)
• Re-check the 6 prior review threads against the current diff
• Resolve my own stale threads (all 6 were already resolved by the author)
• Verify anchors and link references resolve inside docs-mintlify
• Post review

What 567319b changed

docs-mintlify/docs/integrations/dbt.mdx:615 — the Validation schema row now reads "Required whenever Validation level is Build, including on adapters that fall back to Parse only (see below)" instead of "Required by the form … on every adapter". That was the one low nit left from the previous pass: the trailing qualifier now points at the <Note> two paragraphs down rather than reading as a property of the requirement. Addressed.

Thread state

All six threads I opened are isResolved: true and the concerns don't recur in the current text, so I posted no new inline comments and had nothing of my own to resolve. No unresolved threads remain on this PR.

Re-verified

• Anchors: ## Maximum row limit (docs/data-modeling/configuration.mdx:52), ### Query pushdown (query-format.mdx:195), ## List of deployments (admin/deployment/index.mdx:11), ## Default deployment {#default-deployment} on both the admin page and docs/preferences.mdx.
• Link references: [ref-cross-data-source-queries] defined at query-format.mdx:457, used at 212; pre-existing [ref-query-default-limit] still used at 386, so not orphaned by the switch to the max-row-limit wording.
• Cross-page consistency: preferences.mdx:76-81 and admin/deployment/index.mdx:23-25 now state the same resolution order (own pin → last switched to → account default → most recently created).
• Pushdown claims still match rust/cubesql (rules/wrapper/union.rs same-data-source constraint; rules/wrapper/aggregate_function.rs whole-argument-list match with the per-dialect template gate, which the "provided the target data source supports that function" wording covers).
• All edits are in /docs-mintlify; nothing touches the deprecated /docs tree. Mintlify components and root-relative links follow repo conventions.

Still worth a maintainer's eye (not a defect)

The row-limit consequence of union pushdown — "the limit applies once, to the combined result" — is a reasonable inference from "pushed down as a single statement" but isn't stated by the rewrite rules themselves. Someone who has run such a query should confirm it before merge.

Nothing security-, performance-, or test-related applies: this PR is documentation only. mintlify broken-links (per .cursor/rules/mintlify-mdx-gotchas.mdc) is the relevant check and I couldn't run it in this environment — anchor/link verification above was done by grep instead.

· branch [`claude/gallant-ramanujan-0b34qw`](https://github.com/cube-js/cube/tree/claude/gallant-ramanujan-0b34qw)