Environments, sessions and runs

When you open a notebook, Querio starts live compute separately from the work you saved. Use session state to tell whether you can work, and run status to tell whether execution finished. Neither tells you that a result is analytically correct or current.

Associations and ownership

A session, its notebook, and its environment belong to the same workspace. An environment hosts one active notebook kernel at a time. To work in two notebooks concurrently, use separate environments. Finish closing a session before reusing its environment.

Explicit CLI/API opens use the saved notebook ID as the session ID. Only one such session can be open for that notebook. Browser View creates a separate live session ID for each view instance, so several people can view the same Explore in independent runtimes. Keep returned IDs; do not construct them.

Opening an edit session requires Explore edit permission. A run session normally requires read permission, and custom query variables also require edit permission. Sharing an Explore does not grant control of another person's live session or query access. Session events and scratchpad execution check runtime identity, with separate authorization for managed platform work.

Session datasource selections and query variables configure execution; query variables are not Python globals. Close and deliberately reopen an explicit session to change its configuration. A notebook may have a bound agent session in the same environment. Closing the agent leaves the notebook usable; closing the notebook closes its bound agents.

Close only resources you created or were asked to close. Resource IDs are not access grants. Query access still requires datasource permission and exactly one authorized credential; see Users, roles and groups.

Readiness and session states

An environment reporting ready can host a notebook. It does not mean a notebook is open or any cell has run.

An explicit notebook open can return while startup is in progress. Wait for session readiness before using it; readiness is not an execution result.

Read id, notebookId, environmentId, workspaceId, mode, config, state, and error together. activeRunId identifies a tracked run when present; its absence does not establish that no interactive work is happening.

Inspection can restore compute

Inspecting an open saved session can start a replacement runtime after idle reclamation or a server restart. The session keeps its saved configuration, but fresh compute does not recover in-memory Python values. Run the cells you need again. An explicitly closed session stays closed on inspection.

The saved open/closed marker and reported live state can differ while idle compute is reclaimed. Treat inspection as a possible restoration, not merely a metadata read.

Edit and View modes

The session mode run controls what you can do in View. It is distinct from a recorded execution run.

View's authoring restriction does not make the filesystem or database read-only. Hybrid and Notebook are display presets, not execution modes. See Explores for View chat and continuation into editable work.

Opening a CLI/API session does not execute its cells. The browser manages its own initialization and may run the notebook when opening View.

Operations and outcomes

These commands show which action creates, inspects, or closes each resource. See the CLI reference for flags and result shapes, or Get started with CLI for the authoring path. The CLI is distributed through its official repository.

The current shared run inspection and cancellation API endpoints are marked deprecated; replacement endpoints are not yet defined. Existing CLI commands use the current surface. See the API reference before choosing an integration contract.

Run states and results

Run status is separate from session state: a session can be ready while a run is running. A returned run ID means the request was accepted, not that the work succeeded.

A response or live event can say cancelling while interruption is in progress. Read the recorded status for the final outcome. Cancellation does not guarantee that a remote warehouse query stopped.

Runs record kind (notebook or agent), sessionId, input, output, error, and creation, start, and completion times. Run output can differ from the notebook's current source, stored output, or a later result. Records remain after session and environment closure, subject to access; a live task index may disappear on restart. If a runtime vanishes without a completion report, do not assume success. No fixed history-retention period is promised here.

Concurrency and saving

Notebook execution and agent turns have busy checks. Another execution for the same active session can fail with Session execution already in progress. Browser editing can also be refused while an editor or automation holds the Explore. Wait for that work to finish; do not close someone else's session to clear a conflict.

In an editable session, a successful code exec waits for the notebook save. If saving fails, the code may already have run and changed cells. Keep the session open, inspect its cells and saved state, resolve the save failure, then retry saving or closing. Do not replay authoring code or submit a durable run just to flush a save.

Replacing a closed notebook's saved cells is a separate operation. It uses the last-read updatedAt timestamp and fails on a conflict. A title-only update can occur while a session is open. See CLI reference.

Disconnect, timeout, and close

The browser manages resources it opens. CLI/API callers close their own sessions, then their environments. Closing a terminal or losing a stream is not cleanup. Active work is protected from ordinary idle reclamation, but process failure and explicit close can still stop it.

notebook run --wait attempts cleanup in that order. Cleanup failures can appear on stderr even when the command exits successfully; confirm resource state separately.

Errors and recovery

For cells and stored outputs, see Notebooks. For resource creation and cleanup, use Get started with CLI.