Metadata-Version: 2.4
Name: hotdata-jupyter
Version: 0.2.1
Summary: Jupyter integration for Hotdata runtime
License: MIT
Requires-Python: >=3.10
Requires-Dist: hotdata-runtime>=0.3.0
Requires-Dist: hotdata>=0.4.1
Requires-Dist: ipython>=8.18
Requires-Dist: ipywidgets>=8.1
Description-Content-Type: text/markdown

# hotdata-jupyter

[Jupyter](https://jupyter.org/) helpers for [Hotdata](https://hotdata.dev) — rich query display, workspace selection, managed databases, and a `%%hotdata` cell magic for running SQL directly in cells.

## Install

```bash
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

```python
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:

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

## Running SQL

```python
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:

```python
%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:

```python
hj.display_managed_databases_panel(client)
```

Create a database and load parquet files programmatically:

```python
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:

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

## Open the demo notebook

```bash
jupyter lab examples/demo.ipynb
```

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

## Development

```bash
uv sync --locked
uv run pytest
```
