Cube

Throw away the dev branch’s pending edits, resetting it to its parent (or to a specific commit hash). Use it to start over when the model will not compile and the way back is unclear. The edits are not recoverable, so only call it when the user asked to discard, or when the changes are yours from this same session and you are deliberately restarting. Data-model editing workflow (edit the Cube semantic model / schema YAML on a dev branch, never production): startDataModelEdit (enter dev mode → dev branchName) → readDataModelFile / writeDataModelFile / deleteDataModelFile (pass that branchName) → getDataModelChanges (review the diff) → runQuery with that same branchName (verify the edited model returns the right rows before deploying). Use listDataModelFiles / readDataModelFile to discover the current model source, getBranchDiff to see what ANY branch changed relative to the deploy branch, and getDeploymentEnv to check the deployment’s configuration. Call getBranchState whenever you need to know which branch you and the USER are each on. Before authoring a cube for data that is not modelled yet, use listDataSources to find the data sources configured on the deployment. Use runSourceQuery against one of them to inspect the underlying warehouse tables directly — it bypasses the semantic layer entirely, unlike runQuery. Your edits stay invisible — to the user, to the Cube UI and to anyone reviewing — until commitDataModelChanges commits the dev branch onto its parent; then offer switchUserBranch so the user is looking at that branch, commitToNewBranch to put the work on a branch of its own, discardDataModelChanges to start over, and mergeToDefaultBranch (only when the user asks to publish) to make it live.

discardDataModelChanges

Show what a branch changed to the data model: the complete changed-file list with per-file insertion/deletion counts, plus the unified diff. Works for ANY branch (feature branches included) and compares against the deploy branch by default, so this is the tool for "what did this branch change?". Prefer it over reading files one by one: when a branch edits existing cubes (adding a `pre_aggregations` block, say) the file LIST is identical on both branches, so listDataModelFiles reveals nothing. On a large change the patch may be trimmed or omitted — `diffComplete: false` plus `message` says so explicitly, while `files`, `insertions` and `deletions` still describe the FULL change, so never infer the size of a change from the length of the returned patch. ONE exception, and check it first: if `comparable` is `false` (with `reason: "no-common-history"` and `usedMergeBase: false`) the two branches share no ancestor, so nothing was compared — the empty `files` and zero counts mean UNKNOWN, not "no changes", and no narrower request will return anything. Diff against a branch the target was created from instead. Use getDataModelChanges instead only when you specifically want your own dev branch versus its immediate parent. Data-model editing workflow (edit the Cube semantic model / schema YAML on a dev branch, never production): startDataModelEdit (enter dev mode → dev branchName) → readDataModelFile / writeDataModelFile / deleteDataModelFile (pass that branchName) → getDataModelChanges (review the diff) → runQuery with that same branchName (verify the edited model returns the right rows before deploying). Use listDataModelFiles / readDataModelFile to discover the current model source, getBranchDiff to see what ANY branch changed relative to the deploy branch, and getDeploymentEnv to check the deployment’s configuration. Call getBranchState whenever you need to know which branch you and the USER are each on. Before authoring a cube for data that is not modelled yet, use listDataSources to find the data sources configured on the deployment. Use runSourceQuery against one of them to inspect the underlying warehouse tables directly — it bypasses the semantic layer entirely, unlike runQuery. Your edits stay invisible — to the user, to the Cube UI and to anyone reviewing — until commitDataModelChanges commits the dev branch onto its parent; then offer switchUserBranch so the user is looking at that branch, commitToNewBranch to put the work on a branch of its own, discardDataModelChanges to start over, and mergeToDefaultBranch (only when the user asks to publish) to make it live.

getBranchDiff

Report which branch this session works on, which branch the USER is looking at in the Cube console, which branch is the deployment’s production branch, and whether the branch has edits that are not committed yet. Call it before editing (so work does not land somewhere the user will never look) and after committing (to see whether the user still has to be switched over). The two names differ far more often than they look like they should: a session connected to a dev branch edits a private working copy the user’s branch switcher never shows. Data-model editing workflow (edit the Cube semantic model / schema YAML on a dev branch, never production): startDataModelEdit (enter dev mode → dev branchName) → readDataModelFile / writeDataModelFile / deleteDataModelFile (pass that branchName) → getDataModelChanges (review the diff) → runQuery with that same branchName (verify the edited model returns the right rows before deploying). Use listDataModelFiles / readDataModelFile to discover the current model source, getBranchDiff to see what ANY branch changed relative to the deploy branch, and getDeploymentEnv to check the deployment’s configuration. Call getBranchState whenever you need to know which branch you and the USER are each on. Before authoring a cube for data that is not modelled yet, use listDataSources to find the data sources configured on the deployment. Use runSourceQuery against one of them to inspect the underlying warehouse tables directly — it bypasses the semantic layer entirely, unlike runQuery. Your edits stay invisible — to the user, to the Cube UI and to anyone reviewing — until commitDataModelChanges commits the dev branch onto its parent; then offer switchUserBranch so the user is looking at that branch, commitToNewBranch to put the work on a branch of its own, discardDataModelChanges to start over, and mergeToDefaultBranch (only when the user asks to publish) to make it live.

getBranchState

Show the diff of your dev branch against its parent — the pending data-model changes. Use this to review edits before committing. Data-model editing workflow (edit the Cube semantic model / schema YAML on a dev branch, never production): startDataModelEdit (enter dev mode → dev branchName) → readDataModelFile / writeDataModelFile / deleteDataModelFile (pass that branchName) → getDataModelChanges (review the diff) → runQuery with that same branchName (verify the edited model returns the right rows before deploying). Use listDataModelFiles / readDataModelFile to discover the current model source, getBranchDiff to see what ANY branch changed relative to the deploy branch, and getDeploymentEnv to check the deployment’s configuration. Call getBranchState whenever you need to know which branch you and the USER are each on. Before authoring a cube for data that is not modelled yet, use listDataSources to find the data sources configured on the deployment. Use runSourceQuery against one of them to inspect the underlying warehouse tables directly — it bypasses the semantic layer entirely, unlike runQuery. Your edits stay invisible — to the user, to the Cube UI and to anyone reviewing — until commitDataModelChanges commits the dev branch onto its parent; then offer switchUserBranch so the user is looking at that branch, commitToNewBranch to put the work on a branch of its own, discardDataModelChanges to start over, and mergeToDefaultBranch (only when the user asks to publish) to make it live.

getDataModelChanges

The git commit log of the data model, newest first: SHA, author name and email, commit date and subject. Answers "who changed this file?" and "what changed recently?". Pass filePath to limit it to one file, branchName to read a branch other than production. `hasMore: true` means older commits exist past `limit`. Only committed work appears; uncommitted dev-branch edits do not. Data-model editing workflow (edit the Cube semantic model / schema YAML on a dev branch, never production): startDataModelEdit (enter dev mode → dev branchName) → readDataModelFile / writeDataModelFile / deleteDataModelFile (pass that branchName) → getDataModelChanges (review the diff) → runQuery with that same branchName (verify the edited model returns the right rows before deploying). Use listDataModelFiles / readDataModelFile to discover the current model source, getBranchDiff to see what ANY branch changed relative to the deploy branch, and getDeploymentEnv to check the deployment’s configuration. Call getBranchState whenever you need to know which branch you and the USER are each on. Before authoring a cube for data that is not modelled yet, use listDataSources to find the data sources configured on the deployment. Use runSourceQuery against one of them to inspect the underlying warehouse tables directly — it bypasses the semantic layer entirely, unlike runQuery. Your edits stay invisible — to the user, to the Cube UI and to anyone reviewing — until commitDataModelChanges commits the dev branch onto its parent; then offer switchUserBranch so the user is looking at that branch, commitToNewBranch to put the work on a branch of its own, discardDataModelChanges to start over, and mergeToDefaultBranch (only when the user asks to publish) to make it live.

getDataModelHistory

List the deployment’s environment variables, with every secret-looking value redacted to `[ENCRYPTED]`. Use it to confirm configuration is present and shaped as expected — for example an export bucket (`CUBEJS_DB_EXPORT_BUCKET`, `CUBEJS_DB_EXPORT_BUCKET_TYPE`) when an external pre-aggregation build fails on missing config. Read-only: this tool cannot change env vars. Data-model editing workflow (edit the Cube semantic model / schema YAML on a dev branch, never production): startDataModelEdit (enter dev mode → dev branchName) → readDataModelFile / writeDataModelFile / deleteDataModelFile (pass that branchName) → getDataModelChanges (review the diff) → runQuery with that same branchName (verify the edited model returns the right rows before deploying). Use listDataModelFiles / readDataModelFile to discover the current model source, getBranchDiff to see what ANY branch changed relative to the deploy branch, and getDeploymentEnv to check the deployment’s configuration. Call getBranchState whenever you need to know which branch you and the USER are each on. Before authoring a cube for data that is not modelled yet, use listDataSources to find the data sources configured on the deployment. Use runSourceQuery against one of them to inspect the underlying warehouse tables directly — it bypasses the semantic layer entirely, unlike runQuery. Your edits stay invisible — to the user, to the Cube UI and to anyone reviewing — until commitDataModelChanges commits the dev branch onto its parent; then offer switchUserBranch so the user is looking at that branch, commitToNewBranch to put the work on a branch of its own, discardDataModelChanges to start over, and mergeToDefaultBranch (only when the user asks to publish) to make it live.

getDeploymentEnv

List the data model’s pre-aggregations with their definitions and, for each, how many partitions exist, how many have actually been built, when the newest build landed, and the exact error if a build failed. This is how you verify pre-aggregations work: a query alone cannot prove a rollup was used, and external pre-aggregations fail in configuration-specific ways (a missing export bucket, denied bucket permissions) that only a build surfaces. Pre-aggregation verification workflow (confirm the rollups/caches a data model defines actually build): getPreAggregationStatus (list pre-aggs, their partitions and last build errors) → buildPreAggregation (trigger a build for one) → getPreAggregationStatus again (confirm it succeeded, or read the exact failure). Omit branchName to use the branch this session is on (the deployed production model unless the endpoint named one); pass the dev branchName from startDataModelEdit to verify pre-aggs added on a branch before deploying, or null to force the deployed model. Use getDeploymentEnv when a build fails on missing configuration such as an export bucket.

getPreAggregationStatus

List the Cube semantic model SOURCE files (the raw `.yml` / `.js` / `.py` schema files that define cubes and views) on a branch. Use this to discover which files to read/edit — it complements searchDataModel, which returns the compiled meta rather than the editable source. Data-model editing workflow (edit the Cube semantic model / schema YAML on a dev branch, never production): startDataModelEdit (enter dev mode → dev branchName) → readDataModelFile / writeDataModelFile / deleteDataModelFile (pass that branchName) → getDataModelChanges (review the diff) → runQuery with that same branchName (verify the edited model returns the right rows before deploying). Use listDataModelFiles / readDataModelFile to discover the current model source, getBranchDiff to see what ANY branch changed relative to the deploy branch, and getDeploymentEnv to check the deployment’s configuration. Call getBranchState whenever you need to know which branch you and the USER are each on. Before authoring a cube for data that is not modelled yet, use listDataSources to find the data sources configured on the deployment. Use runSourceQuery against one of them to inspect the underlying warehouse tables directly — it bypasses the semantic layer entirely, unlike runQuery. Your edits stay invisible — to the user, to the Cube UI and to anyone reviewing — until commitDataModelChanges commits the dev branch onto its parent; then offer switchUserBranch so the user is looking at that branch, commitToNewBranch to put the work on a branch of its own, discardDataModelChanges to start over, and mergeToDefaultBranch (only when the user asks to publish) to make it live.

listDataModelFiles

List the data sources configured on this deployment (name and database type) — the warehouses/databases Cube can query, as distinct from the Cube semantic model built on top of them. Use this before runSourceQuery to find a valid `dataSource` name.

listDataSources

Returns all Cube deployments and their agents that you can access. Use this to discover valid deploymentId values before passing them to any other tool: every tool takes an optional deploymentId and defaults to the deployment this session connected to, so pass one explicitly whenever the user asks about a different deployment. Passing an id not listed here is rejected. Every deployment supports the Auto agent (pass agentId: null to chat) — the default agent used when no specific agent is selected — in addition to any configured agents listed.

listDeployments

List the workspace: folders, workbooks (each can hold a dashboard) and standalone reports (saved explorations), each with its `type`, `id`, `name` and the `folderId` it sits in (null = root). Every id another tool needs comes from here — never guess one: a FOLDER id is `folderId` on createReport / updateReport / moveWorkspaceItem, a WORKBOOK id is `workbookId` on readWorkbook / updateDashboard, a REPORT id is `reportId` on readReport / updateReport. Pass `search` to find an item by name in any folder; otherwise one folder level is listed. Pages hold up to 100 items — pass `nextCursor` back as `cursor` for the next one.

listWorkspaceItems

Fetch additional rows of a SQL query that a prior `chat` tool call already executed. The original query is re-run against the Cube semantic layer (the same SQL, no LIMIT/OFFSET injected) so it can be served from Cube's cache, and 100 rows starting at `offset` are returned. Use this ONLY when the user explicitly asks for more rows of a previous query. Identify the query via the `id` (uuid) of one of the SQL queries the prior chat response reported: take it from that response's `cubeSqlApiQueries[*].id`, which lists every query that turn ran. (`toolCalls[*].calls[*].id` carries the same uuid, but only for queries the answer cited explicitly, so it is often empty — prefer the former.) Page size is fixed at 100 — paginate by incrementing `offset` in steps of 100 (calls with different offsets may be issued in parallel) until the response reports `hasMore: false`. Do NOT call this tool to retry a failed query — re-issue the `chat` request instead.

loadQueryResults

Merge a branch into the deployment’s default (production) branch, making its changes live for everyone. This is a publish step with real consequences, so call it ONLY when the user has explicitly asked to publish or merge to production — never on your own initiative after committing. Commit first with commitDataModelChanges: this merges committed branches, not the development session. Prefer letting the user test the branch first (switchUserBranch). Data-model editing workflow (edit the Cube semantic model / schema YAML on a dev branch, never production): startDataModelEdit (enter dev mode → dev branchName) → readDataModelFile / writeDataModelFile / deleteDataModelFile (pass that branchName) → getDataModelChanges (review the diff) → runQuery with that same branchName (verify the edited model returns the right rows before deploying). Use listDataModelFiles / readDataModelFile to discover the current model source, getBranchDiff to see what ANY branch changed relative to the deploy branch, and getDeploymentEnv to check the deployment’s configuration. Call getBranchState whenever you need to know which branch you and the USER are each on. Before authoring a cube for data that is not modelled yet, use listDataSources to find the data sources configured on the deployment. Use runSourceQuery against one of them to inspect the underlying warehouse tables directly — it bypasses the semantic layer entirely, unlike runQuery. Your edits stay invisible — to the user, to the Cube UI and to anyone reviewing — until commitDataModelChanges commits the dev branch onto its parent; then offer switchUserBranch so the user is looking at that branch, commitToNewBranch to put the work on a branch of its own, discardDataModelChanges to start over, and mergeToDefaultBranch (only when the user asks to publish) to make it live.

mergeToDefaultBranch

Move a folder, workbook or standalone report into another folder, or to the workspace root with `folderId: null`. Take the item and the destination from listWorkspaceItems. A folder moves with everything inside it. To file an exploration as you save it, pass `folderId` on createReport instead.

moveWorkspaceItem

Publish the workbook’s current dashboard draft to make it live. Idempotent — publishing an unchanged draft is a no-op (reported via `warning`). Returns the live dashboard `url` (share this with the user) and its `dashboardPublicId`. Call it only when the user asks to publish, never as the last step of building or editing a dashboard. Dashboard-authoring workflow (use together): createWorkbook → createReport (one per chart/visualization) → updateDashboard, which leaves a draft for the user to review; publishDashboard only when the user asks to publish. readWorkbook reads the current state. To manage an EXISTING report (standalone or workbook-bound) rather than recreating it: readReport, updateReport (edit its title / SQL / visualization / placement in place, keeping its reportId), deleteReport.

publishDashboard

Read the raw source of one Cube semantic model file (the editable YAML/JS defining a cube or view). Read this before writeDataModelFile so you edit on top of the current content rather than overwriting it. Data-model editing workflow (edit the Cube semantic model / schema YAML on a dev branch, never production): startDataModelEdit (enter dev mode → dev branchName) → readDataModelFile / writeDataModelFile / deleteDataModelFile (pass that branchName) → getDataModelChanges (review the diff) → runQuery with that same branchName (verify the edited model returns the right rows before deploying). Use listDataModelFiles / readDataModelFile to discover the current model source, getBranchDiff to see what ANY branch changed relative to the deploy branch, and getDeploymentEnv to check the deployment’s configuration. Call getBranchState whenever you need to know which branch you and the USER are each on. Before authoring a cube for data that is not modelled yet, use listDataSources to find the data sources configured on the deployment. Use runSourceQuery against one of them to inspect the underlying warehouse tables directly — it bypasses the semantic layer entirely, unlike runQuery. Your edits stay invisible — to the user, to the Cube UI and to anyone reviewing — until commitDataModelChanges commits the dev branch onto its parent; then offer switchUserBranch so the user is looking at that branch, commitToNewBranch to put the work on a branch of its own, discardDataModelChanges to start over, and mergeToDefaultBranch (only when the user asks to publish) to make it live.

readDataModelFile

Read one saved report by its numeric id: its `title`, `sqlQuery`, chart category + spec (in `meta`), placement (`workbookId` — null for a standalone exploration — and `folderId`), `publicId`, and a shareable `url`. Use it to inspect a report before updateReport, or to see what a dashboard CHART widget (config.reportId) points at. Reads a single report by id — works for both standalone and workbook-bound reports, unlike a report list which the server filters to workbook-less rows. Dashboard-authoring workflow (use together): createWorkbook → createReport (one per chart/visualization) → updateDashboard, which leaves a draft for the user to review; publishDashboard only when the user asks to publish. readWorkbook reads the current state. To manage an EXISTING report (standalone or workbook-bound) rather than recreating it: readReport, updateReport (edit its title / SQL / visualization / placement in place, keeping its reportId), deleteReport.

readReport

Read a workbook: its name and its current dashboard `dashboardDraft` and `dashboardPublished` configs. ALWAYS call this before updateDashboard so you can pass the current draft as `oldDashboardConfig` (concurrency guard) and edit on top of it rather than overwriting. Dashboard-authoring workflow (use together): createWorkbook → createReport (one per chart/visualization) → updateDashboard, which leaves a draft for the user to review; publishDashboard only when the user asks to publish. readWorkbook reads the current state. To manage an EXISTING report (standalone or workbook-bound) rather than recreating it: readReport, updateReport (edit its title / SQL / visualization / placement in place, keeping its reportId), deleteReport.

readWorkbook

Rename a workspace folder. Take its id from listWorkspaceItems.

renameFolder

Run a Cube SQL query against the Cube SQL API (PostgreSQL dialect — see https://docs.cube.dev/reference/core-data-apis/sql-api) and return the result rows. Returns `schema` (columns), a page of `data` rows (`limit` rows, 100 by default), and `hasMore`/`totalRows` for pagination via `offset`. Read-only — it does not modify the model, workbooks, or reports. Use searchDataModel first to find the exact cubes/views and members to query — never guess member names, and call it with the same `branchName` so it reports the same model this query will run against. Pass `branchName` to run against a dev branch's un-deployed model instead of the deployed one; the branch the query actually ran on comes back as `branchName` (null = deployed model). ## CubeSQL Query Rules Always follow data_model_rules when generating CubeSQL queries: <data_model_rules> - When querying measures, always use MEASURE() function, e.g. MEASURE(revenue), do not nest MEASURE() in other functions. SUM(MEASURE(revenue)) IS INVALID and NOT ALLOWED, use MEASURE(revenue) instead. - A condition that narrows the WHOLE result ("only completed orders", "just the US") is a WHERE clause on the query, and every measure stays MEASURE(): SELECT DATE_TRUNC('month', created_at), MEASURE(revenue) FROM orders_view WHERE status = 'completed' GROUP BY 1. Keeping the member intact is what keeps its title and its number format; a hand-written aggregate has neither. - Use a filtered measure ONLY when a filtered and an unfiltered measure must sit side by side in one row (completed revenue next to total revenue). Then write AGG(CASE WHEN condition THEN view_measure END) where AGG matches the measure's aggregation type: COUNT, SUM, AVG, MIN, MAX, COUNT DISTINCT, APPROX_DISTINCT. Use the bare view measure reference inside CASE, not MEASURE(). Example: SUM(CASE WHEN status = 'completed' THEN revenue END) AS completed_revenue. Never use filtered measures with number-type measures. - A view can expose several time dimensions (an order's created_at and its line item's created_at, say). They bucket the same measure differently, so pick one, say which you used when you report the result, and keep it across every follow-up on that result unless the user asks for another — a follow-up is an edit of the statement you already ran, never a fresh derivation from the model. - When two of your own results disagree, diff the two SQL statements before explaining anything: the difference is almost always in them (a different time dimension, a different filter, a different view), not in the data model. Do not describe join or grain behaviour you have not read in the model. - Do not quote identifiers - When using DATE_TRUNC, you can't use different time grains in SELECT statement and window functions. Convention to call it <date_dimension_name>_<date_trunc_part>, e.g. date_dimension_month. - Avoid using ROUND function - Never use joins between cubes and views. Use selects from views that contain all necessary members instead. You can use joins between CTEs though. - You can't GROUP BY with aliases. You need to use indexes: ```sql SELECT DATE_TRUNC('month', date_dimension) AS date_dimension_month, category_dimension, MEASURE(metric_column) FROM semantic_view WHERE semantic_view.category_dimension = 'value' GROUP BY 1,2 ORDER BY 1,2 LIMIT 5000 ``` - Avoid using aliases, except for time dimensions and custom dimensions and measures: ```sql SELECT DATE_TRUNC('month', orders_view.date) AS date_month, MEASURE(orders_view.count), MEASURE(orders_view.revenue), MEASURE(orders_view.revenue) / NULLIF(MEASURE(orders_view.count), 0) AS avg_order_value FROM orders_view GROUP BY 1 ORDER BY 1 LIMIT 5000 ``` - Your semantic model is Cube. Cube allows to model complex metrics and dimensions. - Views in Cube are user facing. Cube SQL is Postgres SQL. - NEVER query raw cubes directly. You should only query views. If a user asks to query a cube that has no corresponding view, suggest building a view for it first and ask for confirmation before proceeding. Measures must be queried with MEASURE() function, e.g. MEASURE(revenue). - For example if there's revenue measure then to query revenue you should use 'SELECT MEASURE(revenue) FROM sales' or 'SELECT DATE_TRUNC('month', order_date), MEASURE(revenue) FROM sales GROUP BY 1'. - Dimensions can be queried as regular columns. You always need to GROUP BY by dimensions. When selecting only dimensions (no measures), always use SELECT DISTINCT to avoid duplicate rows. For example: 'SELECT DISTINCT category, region FROM sales_view LIMIT 5000'. - Never guess names of measures and dimensions. Read Cube data model before making queries. - When making queries, you need to always set LIMIT (use 5000 as default). - Avoid using CTEs unless absolutely necessary. - You can't join views in Cube. When you need data from different views, you can use CTEs. - When generating SQL query, you must keep it simple, no subqueries, no joins, no complex expressions. - For custom sorting, create a CASE dimension in SELECT (e.g. CASE WHEN ... THEN 1 ... END AS sort_order) and ORDER BY that column. Do not put CASE expressions directly in ORDER BY. - For string filtering, default to ILIKE for case-insensitive matching unless the user explicitly requests case-sensitive LIKE. For example: WHERE client_name ILIKE '%acme%' for default matching, or WHERE client_name LIKE '%Acme%' when case-sensitive matching is explicitly requested. Use NOT ILIKE by default for negated patterns unless NOT LIKE was explicitly requested. </data_model_rules>

runQuery

Execute a SQL query directly against a configured data source (warehouse/database), in the source's own dialect, and return the result rows — for inspecting raw source data that is not modelled in Cube yet, e.g. while building or verifying a new cube or view. Call listDataSources first to find a valid `dataSource` name. This does NOT modify Cube's model, workbooks, or reports, but on a deployment where SQL Runner DDL is enabled the underlying credential can run arbitrary statements against the data source itself, including ones that write or drop data — treat this the same as running SQL directly against the warehouse. To query the compiled Cube semantic model instead (which cannot alter source data), use runQuery.

runSourceQuery

Search the Cube semantic model by similarity — views and their measures & dimensions — to discover what is queryable. Returns compact records (name, title, description, type) you can then reference in a runQuery SQL statement. Call this before runQuery to find the exact view and member names, and pass the same `branchName` to both so the members you find are the ones the query will see: on a dev branch this reports THAT branch’s un-deployed model, including members that do not exist in production yet. The model searched is reported back as `branchName` (null = deployed model).

searchDataModel

Enter development mode and start a dev worker. Returns the `branchName` you MUST pass to writeDataModelFile / deleteDataModelFile / getDataModelChanges. Editing always happens on this dev branch — the deploy branch is never writable. Call this first, before any edit. To RESUME a specific edit later, pass the same feature-branch name you used before; omitting `branchName` starts a NEW edit session each call, so reuse the returned branchName for all follow-up tools rather than calling this again. Data-model editing workflow (edit the Cube semantic model / schema YAML on a dev branch, never production): startDataModelEdit (enter dev mode → dev branchName) → readDataModelFile / writeDataModelFile / deleteDataModelFile (pass that branchName) → getDataModelChanges (review the diff) → runQuery with that same branchName (verify the edited model returns the right rows before deploying). Use listDataModelFiles / readDataModelFile to discover the current model source, getBranchDiff to see what ANY branch changed relative to the deploy branch, and getDeploymentEnv to check the deployment’s configuration. Call getBranchState whenever you need to know which branch you and the USER are each on. Before authoring a cube for data that is not modelled yet, use listDataSources to find the data sources configured on the deployment. Use runSourceQuery against one of them to inspect the underlying warehouse tables directly — it bypasses the semantic layer entirely, unlike runQuery. Your edits stay invisible — to the user, to the Cube UI and to anyone reviewing — until commitDataModelChanges commits the dev branch onto its parent; then offer switchUserBranch so the user is looking at that branch, commitToNewBranch to put the work on a branch of its own, discardDataModelChanges to start over, and mergeToDefaultBranch (only when the user asks to publish) to make it live.

startDataModelEdit

Switch the USER over to a branch in the Cube console, so they can see and test what was committed to it — the same action as the branch switcher in the UI. This is what closes the loop after a commit: without it, the user is still looking at whatever branch they had selected and cannot find the work. It changes what they are looking at, so call it only when the user asks to be moved onto a branch, or agrees when you offer — never unprompted. Pass the shared branch a commit landed on, never a `dev-…` personal branch and never the default (production) branch. Data-model editing workflow (edit the Cube semantic model / schema YAML on a dev branch, never production): startDataModelEdit (enter dev mode → dev branchName) → readDataModelFile / writeDataModelFile / deleteDataModelFile (pass that branchName) → getDataModelChanges (review the diff) → runQuery with that same branchName (verify the edited model returns the right rows before deploying). Use listDataModelFiles / readDataModelFile to discover the current model source, getBranchDiff to see what ANY branch changed relative to the deploy branch, and getDeploymentEnv to check the deployment’s configuration. Call getBranchState whenever you need to know which branch you and the USER are each on. Before authoring a cube for data that is not modelled yet, use listDataSources to find the data sources configured on the deployment. Use runSourceQuery against one of them to inspect the underlying warehouse tables directly — it bypasses the semantic layer entirely, unlike runQuery. Your edits stay invisible — to the user, to the Cube UI and to anyone reviewing — until commitDataModelChanges commits the dev branch onto its parent; then offer switchUserBranch so the user is looking at that branch, commitToNewBranch to put the work on a branch of its own, discardDataModelChanges to start over, and mergeToDefaultBranch (only when the user asks to publish) to make it live.

switchUserBranch

Save the dashboard layout (the full `widgets` array) to the workbook DRAFT. This does not go live until publishDashboard. Send the COMPLETE widget set every time — this replaces the draft widgets (other top-level draft fields are preserved). CHART widgets must reference a real reportId from a createReport call made WITH this same workbookId; an id from another workbook or from a standalone (workbook-less) report is rejected and nothing is saved. Grid rules: 12 columns (x + w ≤ 12); CHART h≈11 (KPI-style ~w=3, h=3 with { hideTitle:true }), TEXT h is recomputed from its markdown server-side (pick any reasonable h; just size w), FILTER/TIME_GRAIN/FIELD/PARENT h=2 (w=3) on the top control row (y=0), a CONTAINER row/column stack takes a root-grid position sized to hold its children (its children carry LOCAL 1×1 positions by order — see the widget config field), DIVIDER h=1 and SPACER h=2 (both full-width w=12). Pass `oldDashboardConfig` (from readWorkbook) for a safe concurrent update. Returns a `url` to the updated dashboard you can share with the user. Dashboard-authoring workflow (use together): createWorkbook → createReport (one per chart/visualization) → updateDashboard, which leaves a draft for the user to review; publishDashboard only when the user asks to publish. readWorkbook reads the current state. To manage an EXISTING report (standalone or workbook-bound) rather than recreating it: readReport, updateReport (edit its title / SQL / visualization / placement in place, keeping its reportId), deleteReport.

updateDashboard

Edit an EXISTING report in place, KEEPING its reportId. Do NOT recreate a report to change it; that orphans the CHART widgets pointing at it. Send only the fields you want to change; omitted fields are left untouched. You can change: `title`; `sqlQuery`; the visualization (`chartCategory` + its matching spec — table/vega/kpi/html/map/sankey); and placement — set `workbookId` to a workbook id to bind it there, or `null` to detach it into a standalone exploration, and `folderId` to file a standalone report. Editing title/SQL/visualization keeps every referencing widget rendering. CHANGING `workbookId` DOES NOT: a dashboard CHART widget resolves its report from its OWN workbook's report list, so moving a report out of (or between) workbooks empties every tile on the old workbook's dashboard that referenced it — the same "deleted" empty state deleteReport warns about. Before changing `workbookId` on a report a dashboard uses, call readWorkbook and re-point or remove those widgets with updateDashboard first. Works for both standalone and workbook-bound reports. Returns the reportId and a `url`. Dashboard-authoring workflow (use together): createWorkbook → createReport (one per chart/visualization) → updateDashboard, which leaves a draft for the user to review; publishDashboard only when the user asks to publish. readWorkbook reads the current state. To manage an EXISTING report (standalone or workbook-bound) rather than recreating it: readReport, updateReport (edit its title / SQL / visualization / placement in place, keeping its reportId), deleteReport.

updateReport

Create or overwrite a Cube semantic model source file on your dev branch (whole-file replacement — send the COMPLETE content). After saving, the dev worker recompiles the model and this returns `valid` plus any `validationError`. If it does not compile, fix the content and call this again — the file stays saved so you can iterate. Requires the dev branchName from startDataModelEdit. Data-model editing workflow (edit the Cube semantic model / schema YAML on a dev branch, never production): startDataModelEdit (enter dev mode → dev branchName) → readDataModelFile / writeDataModelFile / deleteDataModelFile (pass that branchName) → getDataModelChanges (review the diff) → runQuery with that same branchName (verify the edited model returns the right rows before deploying). Use listDataModelFiles / readDataModelFile to discover the current model source, getBranchDiff to see what ANY branch changed relative to the deploy branch, and getDeploymentEnv to check the deployment’s configuration. Call getBranchState whenever you need to know which branch you and the USER are each on. Before authoring a cube for data that is not modelled yet, use listDataSources to find the data sources configured on the deployment. Use runSourceQuery against one of them to inspect the underlying warehouse tables directly — it bypasses the semantic layer entirely, unlike runQuery. Your edits stay invisible — to the user, to the Cube UI and to anyone reviewing — until commitDataModelChanges commits the dev branch onto its parent; then offer switchUserBranch so the user is looking at that branch, commitToNewBranch to put the work on a branch of its own, discardDataModelChanges to start over, and mergeToDefaultBranch (only when the user asks to publish) to make it live.

writeDataModelFile