docs: document regtype casts, branch staging-env toggle, and Sort & limit merge - #11568
docs: document regtype casts, branch staging-env toggle, and Sort & limit merge#11568keydunov wants to merge 2 commits into
Conversation
…imit merge Cross-checked recent cube-js/cube and cubejs-enterprise changes against docs-mintlify and filled three gaps: - SQL API: `regtype`/`regtype[]` casts for BI-tool introspection queries (#11503). - CLI/Platform API: `cube data-model enable-branch`/`disable-branch` and the equivalent REST endpoint for keeping a shared branch's staging environment always active (cubejs-enterprise#13535). - Workbooks: the Sort and Row limit controls merged into one "Sort & limit" popover (cubejs-enterprise#14064).
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
|
Claude finished @keydunov's task in 2m 4s —— View job Docs review: 1 medium, 1 medium, 2 low — 3 inline comments postedDocs-only change; edits are appropriately small and land on the right (Mintlify) site. Main issue: the Full reviewChecklist
Findings1.
The doc says "casting a value … resolves it to the matching OID" and then closes with "BI tools that inspect column types by casting to 2. Platform API link doesn't lead to the endpoint (medium) —
3. Trailing newline still missing (low) — The PR touches the last line but keeps 4. Redundant back-reference in the workbooks page (low, not commented inline) — "The row limit shares the same popover, in its own Row limit section — see Limiting above." largely restates what the Limiting section now says about the Sort & limit control. Harmless, but the two-way cross-link is more plumbing than a reader needs; dropping one direction would read cleaner. Both Verified as correct
Not verifiable hereThe workbook UI claims (reset buttons, the merged Sort & limit popover) and the |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
| Casting a value to `regtype` or `regtype[]` resolves it to the matching | ||
| Postgres [object identifier (OID)][link-postgres-oid], e.g., `'int4'::regtype` | ||
| or `'{int,int8}'::regtype[]`. Both `pg_type.typname` values (`int4`) and their | ||
| canonical or SQL-standard aliases (`integer`, `int`) are understood. This | ||
| supports BI tools that inspect column types by casting to `regtype` as part of | ||
| their introspection queries. |
There was a problem hiding this comment.
"Casting a value to regtype" is broader than what the implementation does, and the two halves of the paragraph describe different behaviors.
In rust/cubesql/cubesql/src/sql/statement.rs, only a string literal cast to regtype becomes an OID (visit_cast, the Expr::Value(val) arm → Expr::Value(Number(oid))). A column cast to regtype is rewritten to format_type(col, NULL), i.e. it renders the type name, not an OID (Expr::Identifier(_) | Expr::CompoundIdentifier(_) arm just above). The last sentence ("BI tools that inspect column types by casting to regtype") describes exactly that column case, so as written a reader would expect atttypid::regtype to yield 23 when it actually yields integer.
Also worth stating: a literal that doesn't resolve is left as-is rather than erroring (the None => trace! branch), which is a useful expectation to set.
| Casting a value to `regtype` or `regtype[]` resolves it to the matching | |
| Postgres [object identifier (OID)][link-postgres-oid], e.g., `'int4'::regtype` | |
| or `'{int,int8}'::regtype[]`. Both `pg_type.typname` values (`int4`) and their | |
| canonical or SQL-standard aliases (`integer`, `int`) are understood. This | |
| supports BI tools that inspect column types by casting to `regtype` as part of | |
| their introspection queries. | |
| Casting a type name literal to `regtype` or `regtype[]` resolves it to the | |
| matching Postgres [object identifier (OID)][link-postgres-oid], e.g., | |
| `'int4'::regtype` or `'{int,int8}'::regtype[]`. Both `pg_type.typname` values | |
| (`int4`) and their canonical or SQL-standard aliases (`integer`, `int`) are | |
| understood; a name that doesn't resolve is left uncast rather than raising an | |
| error. Casting a column to `regtype` instead renders the type's name, as | |
| `format_type` does. Together these support BI tools that inspect column types | |
| by casting to `regtype` as part of their introspection queries. |
| The same toggle is available from the [CLI][ref-cli] (`cube data-model | ||
| enable-branch`/`disable-branch`) and the [Platform API][ref-platform-api], so | ||
| a shared branch's staging environment can also be kept always active from a | ||
| script or CI job. |
There was a problem hiding this comment.
The [Platform API][ref-platform-api] link resolves to /api-reference/introduction, but there is no enable/disable-branch endpoint in docs-mintlify/api-reference/api.yaml — the only branch paths there are /build/api/v1/deployments/{deploymentId}/branches (list/create) plus the dev-mode/commit/merge operations. So a reader who follows this link to find "the REST equivalent" mentioned in the PR description won't find it.
Two options, either is fine: name the endpoint inline (POST /build/api/v1/deployments/{deploymentId}/branches/...) so the sentence is self-sufficient, or add the operation to api.yaml next to the sibling branch operations and deep-link it. Leaving a bare link to the API introduction is the one option that doesn't help.
Nit on wording: "The same toggle" reads oddly for a pair of commands — "The same setting can also be changed from …" is closer to what happens.
| [ref-version-channel]: /admin/deployment#update-channels No newline at end of file | ||
| [ref-version-channel]: /admin/deployment#update-channels | ||
| [ref-cli]: /reference/cli | ||
| [ref-platform-api]: /api-reference/introduction No newline at end of file |
There was a problem hiding this comment.
Nit: the file still ends without a trailing newline. Since this PR already edits the last line, it's a free fix.
| [ref-platform-api]: /api-reference/introduction | |
| [ref-platform-api]: /api-reference/introduction |
…penAPI spec Ran scripts/extract-api.mjs against the current cubejs-enterprise public spec to pick up drift that had accumulated: the new branch staging-environment toggle endpoint (pairs with the CLI/prose docs in the previous commit), dbt sync status/result/cancel endpoints, and schema updates already covered elsewhere in prose (timezone settings, Spacer/Divider widgets, source reports).
|
Claude finished @keydunov's task in 2m 22s —— View job Docs review (re-run after
|
| Thread | Status |
|---|---|
regtype described more broadly than implemented (medium) |
Still applies. Re-verified against statement.rs:1213-1250: the Expr::Identifier | Expr::CompoundIdentifier arm rewrites a column cast to format_type(col, NULL) (a type name), only the Expr::Value arm resolves to an OID, and regtype_name_to_oid returning None leaves the cast in place rather than erroring. The reference page still says a cast "resolves it to the matching OID" and then closes on the column case. |
| Platform API link doesn't lead to the endpoint (medium) | Half addressed. 82965d5 adds PUT /build/api/v1/deployments/{deploymentId}/branches/staging-environment to api.yaml and registers it in docs.json — so the endpoint now exists. But environments.mdx:58 still links to the generic /api-reference/introduction. Given the tag/summary, the page slug should be /api-reference/data-model/enable-or-disable-a-branchs-staging-environment (matching the /api-reference/data-model/list-a-deployments-branches convention used in introduction.mdx). |
| Missing trailing newline (low) | Still applies — environments.mdx diff still ends with \ No newline at end of file. |
The low-severity note about the redundant #limiting back-reference in querying-data.mdx:174 is unchanged and remains a matter of taste — not worth a thread.
Scope note on 82965d5
The commit is described as a regeneration, and it is — but it lands changes well outside the three items in the PR description, some of them subtractive:
- Removes
POST /api/v1/deployments/{deploymentId}/workbooks/{workbookId}/dashboard/ai-widget-threadand itsUpdatePublishedAiWidgetThreadInputschema (and the matchingdocs.jsonnav entry). - Removes
TABS_CONTAINERfrom bothDashboardWidgetTypeenums, addingSPACER/DIVIDER/CONTAINER. - Adds three dbt-sync polling endpoints, a
reffield on the dbt-sync request,timezoneSettings,isSourceReport, and a new env-var naming constraint.
If those removals reflect real deletions upstream, nothing to do — but silently dropping a previously documented endpoint from a PR titled "document regtype casts, branch staging-env toggle, and Sort & limit merge" is easy to miss on review. Worth a line in the PR description, or splitting the regeneration into its own PR.
Verified as correct
- All
$reftargets introduced by the regeneration resolve:BranchResponse,TimezoneSettings,DbtSyncGeneratedFile,DbtSyncManifestStats,DbtSyncProgressare all defined incomponents.schemas. docs.jsonandapi.yamlagree on the added/removed operations (staging-environment, the three dbt-sync paths, the removed ai-widget-thread page).- The
x-mintnote referencingGET /api/v1/deployments/{deploymentId}/environments?type=stagingis accurate — that operation does declare atypequery param with astagingenum value. [ref-cli]: /reference/cliresolves; thedata-modelCLI row follows the page's existingenable-x/disable-xphrasing.#sortingand#limitinganchors both exist as headings on the workbooks page.
Not verifiable here
The workbook UI claims (reset buttons, the merged Sort & limit popover) and the cube data-model enable-branch CLI surface live in cubedevinc/cubejs-enterprise — they need a reviewer with access to that repo. Whether 82965d5 faithfully reproduces the enterprise OpenAPI spec is likewise unverifiable from here. No tests, lint, or build apply to a docs-only change.
| SetBranchStagingEnvironmentRequest: | ||
| properties: | ||
| branchId: | ||
| oneOf: | ||
| - type: integer | ||
| - type: 'null' | ||
| branchName: | ||
| oneOf: | ||
| - type: string | ||
| - type: 'null' | ||
| enabled: | ||
| type: boolean | ||
| required: | ||
| - enabled | ||
| type: object |
There was a problem hiding this comment.
As documented, this request body doesn't say how the branch is identified. enabled is the only required field and both branchId and branchName are optional-and-nullable, so {"enabled": true} reads as a valid body — but there's no branch in it. Presumably the server requires exactly one of the two (an either/or that got flattened on generation).
The rendered page is the whole contract for a reader, and "pick one of these two, and one is mandatory" is not recoverable from the schema. Since the sibling operation already carries an x-mint.content block, the cheapest fix is to state it there — e.g. append to the x-mint content on PUT /build/api/v1/deployments/{deploymentId}/branches/staging-environment:
Identify the branch by either
branchIdorbranchName; exactly one is required.
Alternatively express it structurally with oneOf + required on each variant, if the upstream generator can emit that.
Same question applies to branchName: is it the raw Git branch name, or the Cube-side name shown in the branches list? Worth one clause either way.
2 participants
Check List
Description of Changes Made
Found while cross-checking recent code changes against docs-mintlify for undocumented customer-facing features:
regtype/regtype[]cast support, added to let BI tools (e.g. Domo) run introspection queries against the SQL API (feat(cubesql): Supportregtypeandregtype[]casts #11503).cube data-model enable-branch/disable-branchCLI commands and their REST equivalent, which keep a shared branch's staging environment always active — the API-first equivalent of the existing Settings → Staging Environments toggle (cubedevinc/cubejs-enterprise#13535).All three are small, surgical edits to existing pages — no new pages or navigation changes needed.
Generated by Claude Code