Notebooks

Use Notebooks to create, edit, and run Git-backed analysis notebooks inside a Qarion space. Notebook workspaces can point at an analysis, project, or personal repository and can include both .ipynb files and supporting text files.

Workspace Setup

1. Open Authoring -> Notebooks.
2. Create or select a workspace.
3. Choose the default repository and branch for notebook files.
4. Set visibility to Space, Private, or Shared.
5. Optionally select authoring query connectors that the workspace can use.

Workspace visibility controls who can see the workspace. Query connector selection controls which governed data sources notebooks can reach while executing.

Files And Versions

Notebook files are stored in the selected repository branch. Saving a notebook or text file creates a Git commit and records a version entry in Qarion so teams can review the saved path, branch, commit message, and author.

The file tree supports notebook and text files. Use safe relative paths only; absolute paths and paths that escape the repository are rejected.

Executing Notebooks

Executable notebooks require an available kernel profile. Qarion can expose:

• A managed local IPython runtime for development.
• Dedicated notebook worker runtimes launched through the runtime gateway.
• External gateway profiles, when configured by an administrator.

When dedicated workers are enabled, start a worker from the notebook workspace, select a resource class, and then run cells through the active session. Cell execution streams status, output, and errors back to the notebook editor.

Resource Classes And Quotas

Dedicated workers use administrator-defined resource classes. A resource class sets the CPU, memory, GPU, workspace storage, and temporary storage limits shown when a user starts a worker. Qarion records the selected resource class snapshot on the worker so later investigations can see the limits used at startup.

Resource classes can be enabled, disabled, or marked as the default by administrators. At least one enabled class must be available before users can start dedicated workers.

Qarion reserves a worker quota before launching the runtime. If the user already has the maximum number of active workers, the start request is rejected before a new runtime is created. If startup fails after quota reservation, the worker is recorded as failed with sanitized error detail so administrators can diagnose capacity, package, image, or gateway problems.

Worker States

Notebook workers move through these states:

State	Meaning
starting	The worker is being created and prepared.
ready	The worker can execute notebook cells.
busy	A cell execution is currently running.
stopping	Qarion is stopping the worker.
stopped	The worker has stopped normally.
failed	Startup, health, dependency, or execution setup failed.

If a worker stays in starting or busy longer than expected, ask an administrator to check Notebook Workers.

Only one cell execution can use a worker at a time. If the database still shows the worker as busy, Qarion rejects a second execution request. When execution finishes normally, the worker returns to ready unless a separate lifecycle change, such as stop or failure, already happened.

Dependencies And Package Access

Notebook workers can prepare dependencies before execution. Package access follows the same governed package-fetch controls used by other authoring runtimes: private package repositories must be approved, public-index access may be disabled, and setup output is sanitized before it is stored.

Dependency setup runs before cell execution for the active worker session. If setup fails, the failure is recorded on the worker instead of exposing raw package credentials or unsanitized installer output in the notebook.

Use workspace query connectors for governed data access. Keep database credentials and package repository tokens in connector or platform settings, not inside notebook cells.

Data Access

Notebook workspaces can be linked to approved query connectors. Use those connectors for governed data reads and previews instead of copying database credentials into cells. Connector grants should be scoped to the workspace purpose and reviewed when a notebook moves from personal analysis to shared team work.

Troubleshooting

Python 3 is unavailable means the backend was started without notebook kernels or the dedicated runtime profile. In the Docker demo, start make demo-notebook-runtime-up.

Dedicated notebook runtime workers are disabled means the backend cannot reach or was not configured for the runtime gateway. Check NOTEBOOK_RUNTIME_ENABLED, NOTEBOOK_KERNELS_ENABLED, and the runtime gateway settings.

Dependency installation is slow usually means the worker is creating a fresh virtual environment. Administrators can preinstall common packages into the notebook worker image or configure a trusted dependency cache.

A worker limit is reached means the user already has the maximum active workers allowed by the runtime settings. Stop unused workers or ask an administrator to review worker limits and stale sessions.

The selected resource class is unavailable means the class was disabled or removed after the worker picker loaded. Refresh the workspace and select an enabled class.

A stop action reports an error means Qarion could not confirm a clean runtime shutdown. The worker is not marked stopped until the failed stop is resolved or the runtime cleanup task reconciles the state.