Skip to content

README.md

Latest commit

 

History

History
115 lines (77 loc) · 5.51 KB

README.md

File metadata and controls

115 lines (77 loc) · 5.51 KB

hotdata-marimo

Marimo UI helpers for Hotdata: run SQL from a notebook, browse catalog metadata, and render results as tables.

Features

  • Workspace-aware setup — build a HotdataClient from environment variables, or use workspace_selector_from_env() to choose a workspace interactively when no workspace is pinned.
  • Connection health — show a compact status callout with API, workspace, and optional sandbox context.
  • Catalog browsing — browse Hotdata connections, schemas, tables, and columns from Marimo UI controls.
  • SQL editor widget — run SQL against Hotdata, cache the latest successful result, and render results in downstream reactive cells.
  • Native mo.sql engine — register HotdataMarimoEngine so Marimo SQL cells can execute through a live HotdataClient with engine=client.
  • Result display helpers — render query results, recent results, and run history as notebook-friendly UI.
  • Managed databases — create Hotdata-owned catalogs, declare tables, and load parquet files (replaces dataset uploads for writes).
  • Marimo UI aliases — importing hotdata_marimo attaches helpers such as mo.ui.hotdata_sql_editor and mo.ui.hotdata_table_browser for discoverability.

Install

uv pip install hotdata-marimo
# or: pip install hotdata-marimo

Requires Python 3.10+, Marimo, and hotdata-runtime (Hotdata SDK + runtime/session semantics — pulled in automatically when you pip install hotdata-marimo).

Environment

Variable Required Description
HOTDATA_API_KEY Yes API key for the Hotdata API
HOTDATA_API_URL No API base URL (default: https://api.hotdata.dev)
HOTDATA_WORKSPACE No Workspace id; if unset, the first active workspace is used
HOTDATA_SANDBOX No Sandbox session id, passed through to the SDK

Minimal notebook

import marimo as mo
import hotdata_marimo as hm

client = hm.from_env()
editor = hm.sql_editor(client, default_sql="SELECT 1 AS ok")
return editor.ui
return hm.query_result(editor.result)

Importing hotdata_marimo registers discoverability aliases on Marimo’s UI namespace, so you can also use mo.ui.hotdata_sql_editor, mo.ui.hotdata_table_browser, mo.ui.hotdata_query_result, and mo.ui.hotdata_connection_status.

Use hm.connection_status(client) (or mo.ui.hotdata_connection_status(client)) for a small API/workspace health callout.

Marimo SQL Cells

Register the Hotdata SQL engine once during setup, then pass a HotdataClient to Marimo SQL cells:

import hotdata_marimo as hm

hm.register_hotdata_sql_engine()
client = hm.from_env()
_df = mo.sql(
    """
    SELECT 1 AS example_value
    """,
    engine=client,
)

The engine also exposes Hotdata catalog metadata to Marimo's data-source UI. Hotdata connections are labeled Hotdata in the SQL connection picker.

Two-cell pattern

Keep the editor in one cell and consume editor.result in another. The editor caches the last successful run so downstream cells do not re-query the API on every refresh; click Run on Hotdata again after you change SQL. While a query is running, a Marimo status spinner is shown.

Marimo only shows what you return from a cell. Calling mo.vstack(...) or hm.query_result(...) without returning it produces no visible output.

See examples/demo.py for a full runnable notebook flow.

Examples

  • examples/demo.py — tabbed explorer with workspace selection, connection health, managed databases (create + parquet load), recent results (selectable table), run history, and a native mo.sql cell.

Run locally (single-user machine):

uv run marimo edit examples/demo.py --no-token

On a shared or networked host, omit --no-token and use the access token printed in the terminal URL. Without it, anyone who can reach the Marimo port can run queries against your Hotdata workspace.

Layout

This repo is intentionally thin: API client, env helpers, and result models live in hotdata-runtime; hotdata-marimo only adds Marimo widgets (sql_editor, table_browser, managed_database_writer, display for tables/status/history, workspace_selector). Import HotdataClient / QueryResult / from_env from hotdata_marimo or directly from hotdata_runtime.

Development

This package depends on hotdata-runtime (PyPI name hotdata-runtime). Development uses uv; keep a sibling checkout at ../hotdata-runtime so the lockfile resolves the runtime from disk (see [tool.uv.sources] in pyproject.toml).

uv sync --locked
uv run pytest
marimo edit examples/demo.py --no-token

To pin hotdata-runtime from Git instead of the sibling path, remove the [tool.uv.sources] block, set the dependency line as needed, and run uv lock again.

For a publishable uv.lock (CI that only clones this repo), remove [tool.uv.sources], point hotdata-runtime at PyPI or git+https://…, then uv lock.

The [project] name in hotdata-runtime pyproject.toml is hotdata-runtime and the import package is hotdata_runtime.

Use --no-token for local development so the editor does not redirect to /auth/login (session auth is easy to hit with a global Marimo config). For a public or shared machine, omit it and use the printed URL with an access token instead.