Skip to content

Commit c70262a

Browse files
eddietejedaeddietejeda
authored
docs: improve README for developer experience (#9)
* feat: add database= parameter to sql engine and editor for managed database scoping Pass database= to client.execute_sql() so queries are scoped to a managed database via the X-Database-Id header (hotdata-runtime>=0.2.1). - HotdataMarimoEngine: add default_database= constructor param, pass to execute() - SqlEditor: add database= constructor param, pass to both execute_sql calls - ManagedDatabaseWriter: use description= kwarg matching ManagedDatabase v0.2.0 API - Fix test_databases_marimo.py syntax error and update assertions * refactor: eliminate flag-based side-effect tracking, fix unregister, remove dead code - table_browser: extract _set_table_pick() replacing duplicate _init/_rebuild methods; _sync_table_catalog returns bool so ui drops _rebuilt_table_pick_this_run flag; standardize _active_connection_id to use 'or None' consistently - sql_engine: unregister now restores original engine_to_data_source_connection and resets sentinel so register/unregister/register round-trip works correctly - sql_editor: remove dead 'or ""' on _cached_sql (already guarded by None check above) - workspace_selector: cache HotdataClient, only reconstruct when workspace_id changes * fix: pass dropdown label key (not value) to mo.ui.dropdown value= init param When options is a dict {label: value}, Marimo validates value= against the dict keys (labels), not the values. _rebuild_database_pick was passing a database ID (dict value) which raised ValueError on startup. Now resolves the label key corresponding to the previously-selected ID instead. * docs: rewrite README with quickstart and usage examples --------- Co-authored-by: Eddie A Tejeda <669988+eddietejeda@users.noreply.github.com>
1 parent f15c942 commit c70262a

1 file changed

Lines changed: 48 additions & 77 deletions

File tree

‎README.md‎

Lines changed: 48 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -1,151 +1,122 @@
11
# hotdata-marimo
22

3-
Marimo widgets for [Hotdata](https://hotdata.dev): run SQL, browse catalogs, load managed databases, and display results in notebooks.
4-
5-
Requires Python 3.10+, [Marimo](https://marimo.io/), and [hotdata-runtime](https://github.com/hotdata-dev/hotdata-runtime) (installed automatically).
6-
7-
## Supported widgets
8-
9-
Importing `hotdata_marimo` registers `mo.ui.hotdata_*` aliases for discoverability.
10-
11-
| Widget | Function | Notes |
12-
|--------|----------|-------|
13-
| SQL editor | `hm.sql_editor(client)` | Returns `.ui` and `.result` |
14-
| Table browser | `hm.table_browser(client)` | Browse connections, schemas, tables, columns |
15-
| Managed databases panel | `hm.databases_panel(client)` | Create catalogs and load parquet files |
16-
| Managed database writer | `hm.managed_database_writer(client)` | Lower-level create/load UI |
17-
| Workspace selector | `hm.workspace_selector_from_env()` | Pick workspace when `HOTDATA_WORKSPACE` is unset |
18-
| Connection picker | `hm.connection_picker(client)` | Dropdown of workspace connections |
19-
| Connection status | `hm.connection_status(client)` | API / workspace health callout |
20-
| Connections panel | `hm.connections_panel(client)` | Status callout plus connection list |
21-
| Query result | `hm.query_result(result)` | Render a `QueryResult` as a table |
22-
| Recent results | `hm.recent_results(client)` | Browse past query results |
23-
| Run history | `hm.run_history(client)` | Recent query runs |
24-
25-
Each widget also has a `mo.ui.hotdata_*` alias (e.g. `mo.ui.hotdata_sql_editor`). Native Marimo SQL cells are supported via `hm.register_hotdata_sql_engine()` and `mo.sql(..., engine=client)`.
3+
[Marimo](https://marimo.io/) widgets for [Hotdata](https://hotdata.dev) — run SQL, browse your schema, and work with managed databases in reactive notebooks.
264

275
## Install
286

297
```bash
308
pip install hotdata-marimo
319
```
3210

33-
Set `HOTDATA_API_KEY`. Optionally set `HOTDATA_WORKSPACE`, `HOTDATA_API_URL`, or `HOTDATA_SANDBOX`.
34-
35-
## Connect
36-
37-
```python
38-
import hotdata_marimo as hm
39-
40-
client = hm.from_env()
41-
```
42-
43-
If `HOTDATA_WORKSPACE` is unset, pick a workspace interactively:
44-
45-
```python
46-
ws = hm.workspace_selector_from_env()
47-
client = ws.client
48-
```
11+
## Authentication
4912

50-
## SQL editor widget
13+
Set `HOTDATA_API_KEY` in your environment. Optionally set `HOTDATA_WORKSPACE` to pin a specific workspace (the first available workspace is used if unset).
5114

52-
Run SQL in one cell; show results in the next. Marimo only renders what you **`return`**.
15+
## Quickstart
5316

54-
**Cell 1 — editor**
17+
Because Marimo reruns cells reactively, construct a widget in one cell and read its `.ui` or `.result` in the next.
5518

5619
```python
57-
import marimo as mo
20+
# Cell 1
5821
import hotdata_marimo as hm
5922

6023
client = hm.from_env()
6124
editor = hm.sql_editor(client, default_sql="SELECT 1 AS ok")
6225
return editor.ui
6326
```
6427

65-
**Cell 2 — result**
66-
6728
```python
29+
# Cell 2
6830
return hm.query_result(editor.result)
6931
```
7032

71-
Click **Run on Hotdata** after changing SQL. The editor caches the last successful result so downstream cells do not re-query on every refresh.
33+
Click **Run on Hotdata** after editing SQL. The editor caches the last successful result so downstream cells don't re-query on every refresh.
7234

73-
## Native Marimo SQL cells
35+
## Workspace selection
36+
37+
If you have multiple workspaces or `HOTDATA_WORKSPACE` is unset, add an interactive picker. `ws.client` updates when the selection changes:
38+
39+
```python
40+
ws = hm.workspace_selector_from_env()
41+
client = ws.client
42+
return ws.ui
43+
```
7444

75-
Register the Hotdata engine once, then pass `engine=client` to `mo.sql`. Hotdata appears as **Hotdata** in the SQL connection picker.
45+
## Native Marimo SQL cells
7646

77-
**Setup cell**
47+
Register the Hotdata engine once and Hotdata will appear as a selectable engine in the SQL connection picker:
7848

7949
```python
50+
# Setup cell
8051
import marimo as mo
8152
import hotdata_marimo as hm
8253

8354
hm.register_hotdata_sql_engine()
8455
client = hm.from_env()
8556
```
8657

87-
**SQL cell**
88-
8958
```python
90-
_df = mo.sql(
91-
"""
92-
SELECT 1 AS example_value
93-
""",
94-
engine=client,
95-
)
59+
# Any SQL cell
60+
_df = mo.sql("SELECT * FROM orders LIMIT 10", engine=client)
9661
```
9762

9863
![Marimo SQL cell with Hotdata selected in the database connections picker](docs/images/mo-sql-hotdata-connection.png)
9964

100-
## Browse tables
65+
## Browse your schema
66+
67+
The table browser lets you pick a connection, search for a table, and inspect its columns — with a starter query ready to copy:
10168

10269
```python
10370
browser = hm.table_browser(client)
10471
return browser.ui
10572
```
10673

107-
Pick a connection, schema, and table to inspect columns. Use `browser.selected_table` in downstream cells.
74+
Use `browser.selected_table` in downstream cells to reference the chosen table.
10875

10976
## Managed databases
11077

111-
Create a Hotdata-owned catalog and load a parquet file from the notebook:
78+
View existing managed databases and load new parquet files from a single tabbed panel:
11279

11380
```python
114-
panel = hm.databases_panel(client)
115-
return panel
81+
writer = hm.managed_database_writer(client)
82+
return writer.tab_ui
11683
```
11784

118-
Or use the lower-level writer API:
85+
Or show just the read-only panel:
11986

12087
```python
121-
writer = hm.managed_database_writer(client)
122-
return writer.ui
88+
return hm.databases_panel(client)
12389
```
12490

125-
## Other helpers
126-
127-
See [Supported widgets](#supported-widgets) for the full list. Quick examples:
91+
## All widgets
92+
93+
| Widget | Code | What you get |
94+
|--------|------|-------------|
95+
| SQL editor | `hm.sql_editor(client)` | `.ui` to show the editor, `.result` to read rows |
96+
| Query result | `hm.query_result(result)` | Renders a `QueryResult` as a table |
97+
| Table browser | `hm.table_browser(client)` | Browse connections, tables, and column metadata |
98+
| Managed databases | `hm.databases_panel(client)` | Read-only list of managed databases |
99+
| Database writer | `hm.managed_database_writer(client)` | Create databases and load parquet files |
100+
| Workspace picker | `hm.workspace_selector_from_env()` | Dropdown to switch workspaces |
101+
| Connection picker | `hm.connection_picker(client)` | Dropdown of connections in the workspace |
102+
| Connection status | `hm.connection_status(client)` | Health callout for the API and workspace |
103+
| Connections panel | `hm.connections_panel(client)` | Status + list of connections |
104+
| Recent results | `hm.recent_results(client)` | Browse past query results |
105+
| Run history | `hm.run_history(client)` | Recent query runs |
128106

129-
```python
130-
return hm.connection_status(client)
131-
return hm.connections_panel(client)
132-
return hm.recent_results(client).ui
133-
return hm.run_history(client)
134-
```
107+
All widgets are also available as `mo.ui.hotdata_*` aliases (e.g. `mo.ui.hotdata_sql_editor`) for discovery via Marimo's autocomplete.
135108

136109
## Demo notebook
137110

138111
```bash
139112
uv run marimo edit examples/demo.py --no-token
140113
```
141114

142-
`examples/demo.py` combines workspace selection, catalog browsing, managed databases, query history, and a native `mo.sql` cell.
115+
The demo combines workspace selection, schema browsing, managed databases, query history, and a native SQL cell in a single tabbed interface.
143116

144117
## Development
145118

146119
```bash
147120
uv sync --locked
148121
uv run pytest
149122
```
150-
151-
See [hotdata-runtime](https://github.com/hotdata-dev/hotdata-runtime) for the underlying API client.

0 commit comments

Comments
 (0)