Notebooks

A notebook holds the cells and layout for an Explore. Its conversations stay with that Explore.

Cells and outputs

Each cell has an ID, Python source, configuration, and execution state. In the app, you can add Python, SQL, Markdown, and input cells. SQL and Markdown editors produce Python calls to cee.sql() and cee.md().

An earlier result may remain visible while you edit source or wait for a run. Use Run in the editor to submit the current source, then inspect the new result and any errors.

Saved source and stored outputs are separate from live Python variables. Reopened work may need execution again. See Environments, sessions and runs for runtime readiness and session lifetime.

Dependencies and execution order

Querio finds dependencies from the names cells define and use. Execution follows those dependencies, even when a dependent cell appears above its input. Moving a cell changes its position, not its references.

• Define each public variable in one cell. Defining it again in another cell causes a multiple-definition error; give downstream results new names.
• Names beginning with a single underscore are local to their cell. Use public names for values other cells need.
• Dependency cycles and wildcard imports such as from package import * are not allowed.
• Running a cell also runs affected dependent cells. Put reusable calculations upstream of presentation cells.
• Define a widget in one cell and read its .value in another. Changing its value can then rerun dependent calculations or queries.

If an upstream cell fails, its dependents may be cancelled. Fix the failed cell and check the results again. Reactive execution cannot tell you whether the query or business definition is right.

UI elements and filters

UI elements let readers filter data and change inputs without editing code. Add a control through Add input cell, ask the agent to create it, or use cee.ui in a Python cell. Place the control's cell in Layout to make it available on a board. See Build a board for the workflow.

Define a control in one cell and read its .value in another. This connects the calculation or query to the selection.

import code_execution_environment as cee

board_region = cee.ui.dropdown(
    ["All regions", "East", "West"], value="All regions", label="Region"
)
board_region

_region_totals = {"East": 24, "West": 32}
board_filtered_total = (
    sum(_region_totals.values())
    if board_region.value == "All regions"
    else _region_totals[board_region.value]
)
board_filtered_total

For database-backed filters, read the control's value in the downstream query cell. Treat an all-results option explicitly, and use appropriate value escaping rather than inserting arbitrary text into SQL. Each query follows the reader's datasource access. Live controls do not make saved public links interactive.

Use help(cee.ui.<widget>) in the active runtime for arguments and examples, including SQL filters. cee.ui.table(...) also provides an interactive table; its selection options are described by help(cee.ui.table).

Notebook helpers

In cell source, import notebook helpers with import code_execution_environment as cee.

See UI elements and filters for control values and a reactive example. Check SQL arguments in the active runtime with help(cee.sql).

Selecting a datasource does not grant query access. A query needs datasource permission and exactly one authorized credential. See Datasources and credentials for the access rules and Context files for workspace guidance.

Layout

Layout places selected notebook outputs on a board grid. It does not copy the cells or change their dependencies. Removing a cell from Layout leaves its source in the notebook for dependent cells to use. Follow Edit a notebook to arrange outputs in the app.

Code Mode placements use (cell_id, x, y, width, height) in grid units. The grid has 24 columns, 40px rows, and 10px gaps. x and y must be nonnegative integers; width and height must be positive integers; x + width must be at most 24. Placements cannot overlap.

Code visibility and layout placement do not control access. Editing source or layout requires Explore edit permission. A View session can inspect and run existing cells and use controls, but cannot edit the source notebook's cells. See Explores for access and separate work.

To refer to the current notebook in a question, use cell mentions and Tag in chat. To develop independent work from a board result, follow Explore from a board.

For a lost connection or restarted runtime, check Disconnect, timeout, and close before retrying.

Saving, status, and errors

Check which cells ran and whether the changes saved. Stored outputs and live Python values can differ from the current source. See Environments, sessions and runs for runtime recovery and saving behavior.

Advanced notebook authoring

querio code exec --json <<'PY'
from code_execution_environment import code_mode

async with code_mode.get_context() as ctx:
    price_id = ctx.create_cell("unit_price = 6", hide_code=False)
    total_id = ctx.create_cell(
        "order_total = unit_price * 7\norder_total", hide_code=False
    )
    ctx.run_cell(str(price_id))

assert ctx.result.succeeded, ctx.result.errors
assert ctx.globals["order_total"] == 42

async with code_mode.get_context() as ctx:
    _ = ctx.cells[str(price_id)].code
    ctx.edit_cell(str(price_id), "unit_price = 8")
    ctx.run_cell(str(price_id))

assert ctx.result.succeeded, ctx.result.errors
assert ctx.globals["order_total"] == 56
print(ctx.globals["order_total"])
PY