# Python cells
source: https://docs.chalk.ai/docs/notebook-python

## 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.

### Python example

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.

### Tables and DataFrames

Tabular results render as browsable tables. You can work with pandas, polars, pyarrow, and Chalk's
own DataFrame. 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.

### Query results

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:

```
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()
```

### Loading feature classes

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.

### Installing packages

The kernel ships with the chalk client and a data-science baseline that includes pandas, polars,
numpy, and Altair. It does not include every library you might reach for: matplotlib, plotly,
seaborn, scikit-learn, and xgboost are absent, and importing one of them raises
ModuleNotFoundError.

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.

### Querying a branch

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.