> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cube.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Python analysis

> Attach a Python script to a workbook report or exploration to run forecasting, regression, cohort, and other analysis that SQL can't express.

> [!WARNING]
>
> Python analysis is currently in preview, and the user experience and the script
> contract may still change. Reach out to the [Cube support
> team](https://docs.cube.dev/admin/account-billing/support.md) to activate this feature for your account.

A workbook report or exploration can carry an attached **Python script** that
transforms its SQL result. Its chart then renders the script's **output** instead
of the raw SQL rows. This turns an analysis that would otherwise scroll away in a
chat transcript into a saved, re-runnable, shareable analysis.

[Python analysis in Cube](https://www.youtube-nocookie.com/embed/RVn11KueI7s)

Use it for work SQL can't express — forecasting, regression, cohort analysis,
statistical tests, clustering, and anomaly detection.

![A workbook report with the Python code panel open, showing a Prophet forecast script above a chart plotting actual monthly orders alongside the forecast and its confidence interval](https://static.cube.dev/docs/explore-analyze/workbooks/python-analysis/code-panel-forecast.png)

## Adding Python to a workbook report or exploration

### From Analytics Chat

Ask for the analysis in natural language — "forecast next quarter's revenue",
"find anomalies in signups" — and the agent runs Python for you, rendering the
result inline in the [chat thread](https://docs.cube.dev/docs/explore-analyze/analytics-chat.md). This
result is ephemeral by default.

Ask to **save it** — to a workbook, or as a standalone
[exploration](https://docs.cube.dev/docs/explore-analyze/explore.md#saving-explorations) — and Cube persists
both the code and the run result. Opening the saved copy renders that output without
re-running; saving re-executes the analysis.

> [!NOTE]
>
> The agent reaches for Python **only** when the answer genuinely needs a statistics
> or machine-learning library. Ordinary aggregations, top-N, ratios, running totals,
> period-over-period comparisons, and time series all stay in SQL, because a Python
> run costs a re-query plus a sandbox start. If you expected Python and got a plain
> SQL query, that is usually correct behavior.

### From the toolbar

Workbooks and [Explore](https://docs.cube.dev/docs/explore-analyze/explore.md) share the same flow.

Click **Python** in the toolbar to open the Python panel, then **Add script** to
attach one. Cube seeds a starter script and opens it on the **Script** tab.
Opening the panel does not attach anything by itself — only **Add script** does.

**Remove**, in the panel header, detaches the script, after which the analysis is
SQL-backed again.

Attaching Python clears any existing SQL result: a Python-backed analysis renders
its last Python run, and a freshly attached script has none until you press **Run**.

Attaching Python in Explore is only available on a **saved** exploration. On an
unsaved one the **Python** button is disabled with the tooltip *"Save the
exploration to add Python"* — **Run** executes server-persisted code, so the
analysis needs a saved exploration to live on.

## Writing the script

The script runs in a sandbox against a fixed contract:

* Input data arrives as `data.csv` in the working directory.
* Write results to `output.json` as a **flat JSON array of row objects**, for
  example `[{"month": "2026-01", "value": 1.5}, ...]`.

A top-level dict or object is rejected — flatten any nested structure into one
array of uniform rows.

## Python environment

Every run gets a fresh, isolated sandbox running **Python 3.11**. It is created for
the run and destroyed when the run finishes — nothing carries over between runs.

These packages are pre-installed, along with their dependencies:

| Package | Use |
| - | - |
| `pandas`, `numpy` | Dataframes and numerical computing |
| `scipy` | Statistical tests, optimization, interpolation |
| `scikit-learn` | Regression, classification, clustering, anomaly detection |
| `statsmodels` | ARIMA, exponential smoothing, econometric models |
| `prophet` | Time series forecasting with seasonality and holidays |
| `matplotlib`, `seaborn`, `plotly` | Plotting |

Figures are not a supported output. The chart is built from `output.json`, and
anything a script writes to disk is discarded with the sandbox — so the plotting
libraries are importable, but a saved figure has nowhere to go.

> [!NOTE]
>
> Installing your own packages is not supported yet. Because the sandbox is recreated
> for every run, anything a script installs is discarded when the run ends. Support for
> adding packages to the environment is coming.

## Running and refreshing

The panel's **Script** tab is editable in place, with line numbers. **Reset**
restores the starter template.

* **Edits do not run anything.** They save with the analysis, and the rendered result
  keeps showing the previous run.
* When the code or its input SQL has changed since the last run, the result is
  marked **Outdated**, with the tooltip *"The Python code or its input SQL changed
  after the last run. Run to refresh the saved result."*
* **Run** executes the stored script in the sandbox and persists the refreshed
  result.
* On a workbook report, the input SQL can use the workbook's SQL parameters
  (`:name` placeholders). **Run** fills each one with the value set on the report,
  or with the parameter's default if the report doesn't set one, and passes the
  filled SQL to the sandbox. Changing the value of a parameter that the input SQL
  uses counts as a change to the input SQL, so it marks the result **Outdated**.
  If a value can't be filled, for example because the parameter isn't declared in
  the workbook, the run fails with the same error the report shows and nothing is
  saved.
* The **Output** tab shows what the last run printed — the script's stdout and
  stderr, so `print()` is how you inspect intermediate values. Both are captured up
  to the cap in [Limits](#limits), so a chatty script gets truncated.
* The **input SQL panel is read-only** on a Python-backed analysis: that SQL is the
  sandbox's input, not what gets charted. It still offers the **Semantic SQL** and
  **Generated SQL** tabs, both derived from that input query.
* **A failed run keeps the previous chart.** The error surfaces alongside the last
  successful result, which stays rendered.

**Run is the only way the saved result changes.** Opening the workbook report or
exploration, reloading the page, or viewing a dashboard never re-runs anything on
its own.

## On dashboards

Python-backed workbook reports render their **saved output** on dashboards.
Nothing re-runs on dashboard load, so a dashboard full of Python reports costs
no compute to open — each widget shows whatever the last **Run** produced.

A python widget can be opened in [Explore](https://docs.cube.dev/docs/explore-analyze/explore.md) from a
dashboard and run from there.

## Who the analysis runs as

> [!WARNING]
>
> Python runs with the **security context of the person who pressed Run** — or of the
> chat user who saved the analysis. The result is then persisted with the workbook
> report or exploration, and **anyone who can view that item can see the result**.
>
> Row-level security is applied at **run time**, not at view time. A user with broad
> access can Run, and the stored output is then readable by people whose own access
> is narrower.

Take this into account when deciding who can run Python analyses or publish Python
reports, the same way you would for any other shared saved result.

## Limits

| Limit | Value |
| - | - |
| SQL query timeout | 120s |
| Python execution timeout | 120s |
| Maximum output rows persisted | 10,000 |
| Maximum output size | 2 MB |
| stdout/stderr captured | 16 KB |

Exceeding the output caps means the analysis still returns in chat but **cannot be
saved to a workbook report or exploration**. Aggregate or summarize inside the
script so the output stays within the caps — analysis results such as forecasts,
cohorts, and test statistics are small by nature.

## Learn more

* [Analytics Chat](https://docs.cube.dev/docs/explore-analyze/analytics-chat.md) — the standalone
  conversational analytics experience
* [Workbook Agent](https://docs.cube.dev/docs/explore-analyze/workbooks/workbook-agent.md) — the authoring
  assistant inside a workbook
* [Source SQL tabs](https://docs.cube.dev/docs/explore-analyze/workbooks/source-sql-tabs.md) — query
  connected data sources directly


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.