hotdata-jupyter

Jupyter helpers for Hotdata — rich query display, workspace selection, managed databases, and a %%hotdata cell magic for running SQL directly in cells.

Install

pip install hotdata-jupyter

Authentication

Set HOTDATA_API_KEY in your environment. Optionally set HOTDATA_WORKSPACE to pin a specific workspace (the first available workspace is used if unset).

Quickstart

import hotdata_jupyter as hj

client = hj.from_env()
result = client.execute_sql("SELECT 1 AS ok")
hj.display_query_result(result)

Workspace selection

When HOTDATA_WORKSPACE is set, the client connects to that workspace directly. If you have multiple workspaces, use the interactive picker — it renders a dropdown and updates ws.client when the selection changes:

ws = hj.workspace_selector_from_env()
display(ws.ui)
client = ws.client

Running SQL

result = client.execute_sql("SELECT * FROM orders LIMIT 10")
hj.display_query_result(result)

display_query_result renders the row count, column names, and a pandas DataFrame inline in the notebook.

Cell magic

Load the extension once per session, then use %%hotdata cells to write SQL without wrapping it in Python strings. The last active client is picked up automatically:

%load_ext hotdata_jupyter

%%hotdata
SELECT
  product,
  SUM(amount) AS total
FROM orders
GROUP BY product
ORDER BY total DESC

Managed databases

List the managed databases in your workspace:

hj.display_managed_databases_panel(client)

Create a database and load parquet files programmatically:

db = hj.create_managed_database(client, name="sales", tables=["orders"])

with open("orders.parquet", "rb") as f:
    loaded = hj.load_managed_table_from_bytes(client, "sales", "orders", f.read())

print(f"Loaded {loaded.row_count} rows into {loaded.full_name}")

Or use the interactive ipywidgets form:

writer = hj.managed_database_writer(client)
writer.display()

Open the demo notebook

jupyter lab examples/demo.ipynb

The demo covers workspace selection, connection listing, schema browsing, query history, and cell magics.

Development

uv sync --locked
uv run pytest