docs: fill gaps found by a cube-js/cube + cubejs-enterprise feature audit - #11387
docs: fill gaps found by a cube-js/cube + cubejs-enterprise feature audit#11387keydunov wants to merge 1 commit into
Conversation
- cli.mdx: document embed enable-dashboard/disable-dashboard commands - google-bigquery.mdx: document automatic cube_request_id query labels - environment-variables.mdx: document CUBESTORE_TOPK_STRATEGY - oracle.mdx: document Tesseract SQL planner + quarter granularity support - creator-mode.mdx: document Show Semantic SQL / Show Generated SQL toggles - api.yaml: add GitHub integration read endpoints and dashboard embed-access API (GET/PUT embed-access, allowEmbed on publish, embed-tenants list)
|
Claude finished @keydunov's task in 4m 32s —— View job Docs-only PR — no blockers. 2 medium, 5 low; 6 inline comments posted.Full review
What I verified against source
FindingsMedium
Low
Notes on scopeNothing here touches executable code, so the checklist's n/a marks on tests and linting are appropriate. The security-adjacent content is the Creator Mode SQL-visibility section — the reasoning that Generated SQL should default to off because it exposes physical schema names is sound and worth keeping explicit; just resolve the default-value contradiction. No prior review threads existed on this PR, so nothing to dedupe or resolve. |
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
| Every query job that Cube submits to BigQuery is automatically tagged with a | ||
| `cube_request_id` [job label][bq-docs-labels]. Use it to find a specific | ||
| Cube-issued query in BigQuery's job history, audit logs, or cost breakdowns by | ||
| `cube_request_id`. No configuration is required. |
There was a problem hiding this comment.
Accuracy: "Every query job … is automatically tagged" overstates what BigQueryDriver.buildQueryLabels() does (packages/cubejs-bigquery-driver/src/BigQueryDriver.ts:429-445):
- The label is only attached when the query carries a
requestId—buildQueryLabelsreturnsundefinedotherwise, andrunQueryJobthen submits the job with no added label. - The value is not the request id verbatim: the
-span-Nsuffix is stripped, the string is lowercased, every character outside[a-z0-9_-]is replaced with_, and it is truncated to 63 chars (BigQuery's label-value limit).
That second point matters in practice — a reader who copies a request id out of the logs and filters labels.cube_request_id = "<that id>" may get zero rows. Worth saying what the value actually is:
| Every query job that Cube submits to BigQuery is automatically tagged with a | |
| `cube_request_id` [job label][bq-docs-labels]. Use it to find a specific | |
| Cube-issued query in BigQuery's job history, audit logs, or cost breakdowns by | |
| `cube_request_id`. No configuration is required. | |
| Query jobs that Cube submits to BigQuery are tagged with a `cube_request_id` | |
| [job label][bq-docs-labels] whenever the query carries a request id. Use it to find | |
| Cube-issued queries in BigQuery's job history, audit logs, or cost breakdowns. No | |
| configuration is required. | |
| The label value is derived from the request id: the `-span-<n>` suffix is dropped, the | |
| value is lowercased, characters outside `a-z0-9_-` are replaced with `_`, and it is | |
| truncated to 63 characters to satisfy BigQuery's [label requirements][bq-docs-labels]. |
| The Oracle driver supports the [Tesseract SQL planner][ref-tesseract], including the | ||
| `quarter` [granularity][ref-granularities]. |
There was a problem hiding this comment.
Two problems with "including the quarter [granularity]":
-
quarteris already a default granularity for every data source.reference/data-modeling/dimensions.mdx:1018-1020listsyear, quarter, month, week, day, hour, minute, secondas available by default, so calling it out as a new Oracle capability reads as if Oracle previously lacked a standard granularity. WhatOracleQueryactually gained isquartersupport in interval expressions —addInterval/subtractIntervalfoldquarterintoADD_MONTHS(packages/cubejs-schema-compiler/src/adapter/OracleQuery.ts:103-190), which is what custom granularities with quarter-basedinterval/offsetneed. -
The link lands on a section that contradicts the sentence.
[ref-granularities]points at#granularities, whose<Warning>(dimensions.mdx:1035-1037) lists the data sources supporting custom granularities — Athena, Redshift, DuckDB, Databricks, BigQuery, ClickHouse, MSSQL, MySQL, Postgres, Snowflake — and Oracle is not in it. So a reader following the link concludes the opposite of what this page just told them.
Pick whichever matches reality and make both pages agree: if Oracle now supports custom granularities, add it to that <Warning> list in the same PR; if the change is narrower, say so, e.g.
| The Oracle driver supports the [Tesseract SQL planner][ref-tesseract], including the | |
| `quarter` [granularity][ref-granularities]. | |
| The Oracle driver supports the [Tesseract SQL planner][ref-tesseract], including | |
| quarter-based [`interval` and `offset` expressions][ref-granularities]. |
| - in: path | ||
| name: installationId | ||
| required: true | ||
| schema: | ||
| type: number | ||
| responses: | ||
| '200': | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '#/components/schemas/GitHubReposListResponse' | ||
| description: '' | ||
| summary: List repositories accessible to a GitHub App installation | ||
| tags: | ||
| - GitHub | ||
| /v1/github/repositories/{owner}/{repo}/branches: | ||
| get: | ||
| operationId: GitHubPublicController.branches | ||
| parameters: | ||
| - in: path | ||
| name: owner | ||
| required: true | ||
| schema: | ||
| type: string | ||
| - in: path | ||
| name: repo | ||
| required: true | ||
| schema: | ||
| type: string | ||
| - in: query | ||
| name: installationId | ||
| required: true | ||
| schema: | ||
| type: integer |
There was a problem hiding this comment.
installationId is documented with three different types. Same value, three declarations:
- path param here (line 2210-2213):
type: number - query param on the branches endpoint (line 2239-2242):
type: integer GitHubInstallationDto.installationId(line 4587-4588):type: string
The DTO is the value a client reads and then feeds straight back into these two endpoints, so a generated client would need a cast that the spec doesn't justify — and readers can't tell whether the id is really numeric. Only one of the three can be right; align all three (and if the API genuinely returns a stringified number, keep string on the DTO but say so, since number vs integer is also a distinction worth collapsing).
| Moving a folder into one of its own descendants, or exceeding the maximum folder depth, is | ||
| rejected with `400`. Returns `404` if the item does not exist or belongs to a different | ||
| deployment. | ||
| /v1/embed-tenants/: |
There was a problem hiding this comment.
This is the only path in the whole spec that ends in a trailing slash — every other collection path is bare (/v1/deployments, /v1/oauth-integrations, …), including this resource's own children (/v1/embed-tenants/{embedTenantName}). Mintlify renders the path literally, so the reference page will show GET /v1/embed-tenants/ next to DELETE /v1/embed-tenants/{name}, which reads like a typo.
If the route accepts both forms, drop the slash for consistency:
| /v1/embed-tenants/: | |
| /v1/embed-tenants: |
If the upstream Express route genuinely requires the slash, leave it and note that in the x-mint block so it doesn't get "fixed" later.
| allowEmbed: | ||
| oneOf: | ||
| - type: boolean | ||
| - type: 'null' |
There was a problem hiding this comment.
allowEmbed is added to PublishDashboardInput, but the publish operation (line 1780-1810) has no x-mint block, so the flag ships with zero explanation on the page a caller actually reads. Meanwhile PUT .../embed-access carefully documents that the same flag is "Allow signed embedding" and that setting it on a workbook with no published dashboard is a 400.
Two questions a reader can't answer from the spec as written: does omitting allowEmbed on re-publish preserve the previous value or reset it, and does publishing with allowEmbed: true need the same manage access the embed-access PUT requires? Worth one or two sentences in an x-mint block on publishDashboard cross-linking to the embed-access endpoint.
|
|
||
| | Possible Values | Default in Development | Default in Production | | ||
| | -------------------------------------- | ---------------------- | --------------------- | |
There was a problem hiding this comment.
Content checks out against rust/cubestore/cubestore/src/config/mod.rs:1306-1340 — the three canonical values, the default, and the "trades router memory for a ClickHouse-style merge" framing all match TopKAggregateStrategy and its doc comments. Two small things:
- The table's cell padding no longer lines up with the
|---|separator row (the header divider is shorter than the widened columns). Renders fine, but every other table in this 2000-line file is padded consistently — worth matching. env_topk_strategyis deliberately lenient: it also acceptsdefault/v1,vectorized_streaming/v2, andfull-merge/fullmerge, and an unrecognized value logs a warning and falls back tostreamingrather than failing startup. Listing only the canonical three is the right call for the table, but the fallback behavior is the kind of thing worth one clause in the prose — an operator who typos this var getsstreamingperformance and only a log line to tell them why.
| ## SQL visibility | ||
|
|
||
| By default, embed users in Creator Mode can view both the Semantic SQL and the Generated SQL for a query — in Analytics Chat, in a workbook's SQL panel, and in the Error/SQL switcher. Generated SQL is the query sent to your underlying data source, so it can expose physical table and schema names. | ||
|
|
||
| Control this from **Admin → Embed → Settings**: | ||
|
|
||
| - **Show Semantic SQL** — on by default. | ||
| - **Show Generated SQL** — off by default, since it exposes your data source's schema. | ||
|
|
||
| Turning a toggle off removes the corresponding tab and entry points (including the chat **Show SQL** button) from every Creator Mode embed for your account. A workbook's own SQL-based reports keep their SQL editor regardless of these settings, since that SQL is the report definition, not a derived schema view. These settings don't affect the authenticated Cube app, where both are always visible. |
There was a problem hiding this comment.
I can't verify this section from this repo — the toggles live in cubedevinc/cubejs-enterprise, so please double-check two claims that a reader will act on directly:
- The stated defaults. The opening paragraph says users "can view both the Semantic SQL and the Generated SQL", but the bullet immediately below says Show Generated SQL is off by default. As written the two sentences contradict each other for the Generated SQL case. If the default really is off, the intro should say Semantic SQL is visible by default and Generated SQL is opt-in.
- The UI path
Admin → Embed → Settings— worth confirming against the shipped nav labels.
Style-wise, docs-mintlify/CLAUDE.md asks for short paragraphs; the trailing paragraph packs four independent facts (tab removal, chat button, SQL-report exception, authenticated-app behavior) into one block. Splitting the SQL-report exception into its own line, or a <Note>, would make the security-relevant carve-out much harder to skim past.
2 participants
Check List
Description of Changes Made
Surgical edits to close documentation gaps identified by an automated audit of recently merged, customer-facing PRs in
cube-js/cubeandcubedevinc/cubejs-enterprisecross-checked against docs-mintlify.reference/cli.mdx— document theembed enable-dashboard/disable-dashboardCLI commands (feat(cube-cli): add embed enable-dashboard / disable-dashboard commands #11356).admin/connect-to-data/data-sources/google-bigquery.mdx— document the automaticcube_request_idBigQuery job label (feat(bigquery-driver): Label queries with requestId #11299).reference/configuration/environment-variables.mdx— documentCUBESTORE_TOPK_STRATEGY(feat(cubestore): top-k merge strategies via CUBESTORE_TOPK_STRATEGY #11152).admin/connect-to-data/data-sources/oracle.mdx— document Tesseract SQL planner support and thequartergranularity (feat(oracle-driver): Improvements & fixes #11174).embedding/iframe/creator-mode.mdx— document the account-wide Show Semantic SQL / Show Generated SQL Creator Mode toggles (cubedevinc/cubejs-enterprise#13014).api-reference/api.yaml— add the GitHub integration read endpoints (/v1/github/*) and the dashboard embed-access API (GET/PUT .../embed-access,allowEmbedon publish,GET /v1/embed-tenants/) (cubedevinc/cubejs-enterprise#13102, #13351).A few larger undocumented features surfaced by the same audit (CubeStore admin SQL commands, pre-aggregation matching for switch/calc-group dimensions, period-over-period comparison, Python analysis persistence on reports, and the broader public REST API surface for deployment lifecycle/data-model/device-auth) need new pages rather than surgical edits, so those were filed as Linear tickets instead of included here.
🤖 Generated with Claude Code
Generated by Claude Code