Notebooks
Run Python, query Chalk features, and install packages in a notebook.
Use Python cells to transform data, run Chalk queries, and display results. Cells share one Python session, so variables you assign in one cell are available to later cells. You can also read the named results of SQL cells and values from Input cells.
This Python cell reads the orders DataFrame from the SQL example,
selects completed orders, and prints their total revenue. The two completed orders total $214.50.
Select Run to replay the sample result; this example does not connect to a Python kernel.
Tabular results render as browsable tables. You can work with pandas, pyarrow, and Chalk’s own
DataFrame. To use polars, install it first; see
Installing packages. Leave a value as the cell’s last expression to display it.
Assign it to a variable when later cells need to transform, join, or plot it without repeating
the computation.
Run online and offline queries with the same ChalkClient methods you use
outside a notebook.
Leave a query call as the cell’s last expression to display its response as a table of features and values, with tabs for query metadata and the saved execution plan.
The Plan tab shows the saved execution plan. This example loads a recorded plan into the same interactive viewer used in notebooks. Select an operator to inspect it, or use the zoom controls to explore the graph.
Offline queries return before their work finishes. offline_query hands back a
Dataset as soon as the revision is created, and realizing that dataset waits
for the computation to complete, reporting progress while it waits.
offline_query needs the runtime extra of the chalk client, which the kernel does not
include. The runtime extra is an optional set of packages for the chalk client, including
polars and duckdb, that offline queries use to compute and read their results. Install it in a
Python cell before running an offline query:
!uv pip install "chalkpy[runtime]"dataset = client.offline_query(
input={"user.id": list(range(1000))},
output=["user.fraud_score"],
recompute_features=True,
)
# Waits for the revision to finish, then returns the rows.
df = dataset.to_pandas()A notebook’s kernel is a hosted Python environment, separate from your laptop and from your project’s repository.
The kernel does not have your project’s package on its path, so from src.models import User
raises ModuleNotFoundError. Refer to features by their string names instead:
from chalk.client import ChalkClient
client = ChalkClient()
client.query(input={"user.id": 1}, output=["user.fraud_score"])Or call load_features to bind the deployed feature classes into the session, and then use them
the way you would in your project:
client.load_features()
client.query(input={User.id: 1}, output=[User.fraud_score])load_features reads the feature classes from whatever deployment the client points at, so a
client scoped to a branch loads that branch’s features. To scope a client to a branch, see
Querying a branch.
After load_features, you can define new features on the loaded classes and query them, online
or offline, in the same session. See
Building new features. A feature defined this
way exists only in the notebook’s session: the client sends it with each query it makes from the
notebook. To make it available to other notebooks, scripts, and deployments, add it to your
project and deploy it.
The kernel ships with the chalk client and a data-science baseline that includes pandas, numpy,
pyarrow, and Altair. It does not include every library you might reach for: polars, matplotlib,
plotly, seaborn, scikit-learn, and xgboost are absent, and importing one of them raises
ModuleNotFoundError. The chalk client is installed without its runtime extra, which
offline queries need.
Install what you need from a Python cell with !uv pip install. Both pip and uv
are on the kernel’s path. This cell replays a recorded SciPy installation when it comes into view;
versions, timings, and downloads depend on your environment.
To browse installed packages in the dashboard, select the settings icon in the notebook’s upper-right toolbar, then scroll to Installed packages in Notebook settings. Start the kernel if it is stopped; the list loads once it is ready. Use the filter to find a package and check its version. This example shows SciPy and its NumPy dependency after the installation above.
To list what a particular notebook’s kernel already has, run
chalk notebook dependencies against it.
The kernel stops after it has been idle for the time set in Idle timeout in Notebook settings. The default is 1 hour. You can choose from 15 minutes to 8 hours, or Indefinite to keep the kernel running.
When the kernel starts again, its Python session is empty. Variables, imports, the classes bound
by load_features, and features defined in the notebook are gone until the cells that create them
run again. A cell run from the CLI after a restart has the same empty session, so write cells that
create their own client and import what they use.
Run from chalk.features import _ again after a restart. Until you do, _ refers to the
kernel’s own variable for the last output, and feature expressions that use it fail.
The --branch flag on chalk notebook cell add and chalk notebook run scopes that CLI
invocation to a branch. It doesn’t change what branch a Python cell’s own code talks to. A cell
that constructs its own ChalkClient() runs in the notebook’s kernel, a separate process from
the CLI, so the CLI’s --branch flag never reaches it.
If a cell queries a branch-only feature through a ChalkClient() with no branch set, the query
doesn’t raise. The cell’s status still comes back SUCCESS, and the failure only shows up in the
result, as a message like Query output referenced undefined feature 'user.risk_score'. Pass
branch explicitly to the client constructed inside the cell to query that branch.
The kernel does not include the runtime extra of the chalk client, which offline_query
needs. Install it in a Python cell, then run the offline query again:
!uv pip install "chalkpy[runtime]"The client sends every feature defined in the session with each query. If one of those
definitions is invalid, for example an expression that adds a number to a string feature, every
query from the session fails with Internal server error, including queries that do not use that
feature. Restart the kernel, then run the cells again with the definition corrected.