hotdata-ibis 0.1.1__tar.gz

hotdata_ibis-0.1.1/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: hotdata-ibis
+Version: 0.1.1
+Summary: Ibis backend for Hotdata federated SQL API (depends on the hotdata SDK only; not hotdata-runtime)
+Author: Hotdata Ibis contributors
+License: Apache-2.0
+Project-URL: Documentation, https://www.hotdata.dev/docs/api-reference
+Project-URL: Ibis, https://ibis-project.org/
+Keywords: ibis,hotdata,sql,dataframe
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: ibis-framework<11,>=10.0
+Requires-Dist: hotdata>=0.2.0
+Requires-Dist: pyarrow>=15
+Requires-Dist: pyarrow-hotfix>=0.6
+Requires-Dist: pandas>=2
+Requires-Dist: sqlglot>=24
+
+# hotdata-ibis
+
+Experimental [Ibis](https://ibis-project.org/) backend for [Hotdata](https://www.hotdata.dev/docs/api-reference): compile expressions with Ibis, run federated SQL over the Hotdata API. REST calls use the official **[hotdata](https://github.com/hotdata-dev/sdk-python)** Python SDK. Repo examples use **httpx** (listed under the **dev** dependency group).
+
+**Requirements:** Python 3.10+, **ibis-framework** 10.x, **hotdata** ≥0.2.
+
+## Install
+
+```bash
+uv pip install hotdata-ibis
+# or: python -m pip install hotdata-ibis
+```
+
+## Features
+
+- **Ibis connection API** — connect with `ibis.hotdata.connect(...)` or `ibis.connect("hotdata://...")`.
+- **Hotdata catalog mapping** — expose Hotdata connections, schemas, and tables through Ibis catalogs, databases, and tables.
+- **SQL-backed expression execution** — compile Ibis expressions with the Postgres SQLGlot compiler and execute them through Hotdata query APIs.
+- **Typed table discovery** — load schema metadata from Hotdata information schema and map SQL types into Ibis types.
+- **Arrow and pandas results** — materialize expressions as pandas DataFrames, PyArrow tables, or local Arrow record batches.
+- **Raw SQL escape hatch** — use `con.sql(..., dialect="postgres")` when Hotdata-specific federated SQL is clearer than modeled Ibis expressions.
+- **Managed database writes** — create managed connections with `create_database`, load local pandas or PyArrow data through `create_table`, and clean up with `drop_table` / `drop_database`.
+
+## Connect
+
+Programmatic API:
+
+```python
+import ibis
+
+con = ibis.hotdata.connect(
+    api_url="https://api.hotdata.dev",
+    token="YOUR_API_TOKEN",
+    workspace_id="ws_…",
+    session_id=None,       # optional: X-Session-Id (sandbox)
+    verify_ssl=True,
+    timeout=120.0,
+    default_connection=None,  # Hotdata connection id → Ibis catalog
+    default_schema=None,      # remote schema → Ibis database
+    poll_interval_s=0.25,
+    poll_timeout_s=600.0,
+)
+```
+
+URL style (token may live in the query string or the URL “password” segment):
+
+```python
+con = ibis.connect(
+    "hotdata://api.hotdata.dev/?token=…&workspace_id=ws_…&verify_ssl=true"
+)
+```
+
+**Mapping:** Ibis **catalog** = Hotdata connection id; **database** = remote schema; **table** = table name. SQL references look like `connection.schema.table`. With a single connection and schema, defaults are inferred; otherwise set `default_connection` / `default_schema` or qualify `con.table(..., database=(conn_id, schema))`.
+
+**Execution:** SQL is compiled with Ibis’s **Postgres** SQLGlot compiler. The client submits queries asynchronously with `POST /v1/query`, polls `GET /v1/query-runs/{id}`, then downloads ready results as Arrow IPC from `GET /v1/results/{id}`. Tuning: `poll_interval_s`, `poll_timeout_s` on `connect()`.
+
+**Types:** Typed tables come from Hotdata’s information schema. `con.sql(...)` types are inferred from a small preview query and Arrow schema; see [Hotdata SQL](https://www.hotdata.dev/docs/sql) for server behavior.
+
+## Ibis Support Overview
+
+`hotdata-ibis` is a read-oriented SQL backend. It is useful for exploring Hotdata workspaces with Ibis expressions, running federated SQL, and materializing results locally, but it is not a full mutable database backend.
+
+Supported today:
+
+- **Connection setup:** `ibis.hotdata.connect(...)` and `ibis.connect("hotdata://...")` with token, workspace, optional sandbox session, TLS, timeout, and polling settings.
+- **Catalog discovery:** `list_catalogs`, `list_databases`, `list_tables`, `current_catalog`, and `current_database` map Hotdata connections and remote schemas into Ibis' catalog/database/table hierarchy.
+- **Table schemas:** `con.table(...)` uses Hotdata information schema column metadata and maps SQL types through Ibis' Postgres type parser.
+- **SQL-backed expressions:** Ibis expressions compile with the Postgres SQLGlot compiler and execute through Hotdata. Common `SELECT` workloads such as projection, filtering, joins, grouping, aggregation, ordering, limits, scalar expressions, and `con.sql(...)` work when the generated SQL is accepted by Hotdata.
+- **Result materialization:** `.execute()` returns pandas objects. `.to_pyarrow()` and `.to_pyarrow_batches()` use the Arrow IPC result data exposed by Hotdata without converting through JSON rows; batches are split locally after the result is downloaded.
+- **Raw SQL escape hatch:** `con.sql("SELECT ...", dialect="postgres")` is the most reliable way to use Hotdata-specific federated table names or SQL that Ibis does not model directly.
+- **Managed database lifecycle:** `create_database("sales", schema="public", tables=["orders"])` registers a managed connection (Ibis catalog). `create_table("orders", pandas_df, database=("sales", "public"))` uploads Parquet and loads it with replace mode. Query as `sales.public.orders` in SQL. `drop_table` clears a managed table; `drop_database` deletes the connection.
+- **Parquet uploads:** `create_table` accepts pandas DataFrames, PyArrow tables, or schema-only empty tables. Tables must live in a managed connection — declare them with `create_database(..., tables=[...])` first. Loads always use replace mode; pass `overwrite=True` to replace an existing synced table (the default `overwrite=False` raises if the table already exists).
+
+Not supported as full Ibis backend features:
+
+- **General DDL and mutations:** Arbitrary remote DDL, inserts, updates, deletes, and schema-altering operations on external connections are not implemented. Managed-database writes are limited to `create_database`, `create_table`, `drop_table`, and `drop_database` as described above.
+- **Temporary tables and in-memory registration:** `supports_temporary_tables` is false, and in-memory tables are not uploaded automatically for joins.
+- **Python UDFs:** `supports_python_udfs` is false.
+- **Transactions and sessions as database state:** Hotdata sandbox sessions can be passed as `session_id`, but the backend does not expose transaction APIs.
+- **Backend-native SQL dialect:** Compilation uses Ibis' Postgres dialect as the closest fit. Hotdata SQL and federation rules are authoritative, so not every Ibis expression that compiles is guaranteed to execute remotely.
+- **Complete Ibis compliance:** The backend is experimental and has focused test coverage for connection, discovery, schema mapping, execution, uploads, and Arrow results. It has not yet been validated against the full Ibis backend test suite.
+- **Hotdata platform APIs beyond SQL and managed databases:** embeddings, indexes, query history management, sandbox lifecycle management, and other Hotdata-specific APIs are outside the Ibis backend surface.
+
+## Development
+
+```bash
+uv sync   # installs dev group by default (pytest, ruff, httpx for examples)
+uv run pytest
+uv run ruff check src tests examples
+```
+
+Lockfile CI: `uv sync --locked && uv run pytest`.
+
+## TPC-H for the examples
+
+Examples assume something like **`tpch.tpch_sf1.customer`**. Provision TPC-H in your workspace (commonly a **DuckDB** connection, then DuckDB’s `tpch` extension and `CALL dbgen(sf = 1)` — see [DuckDB TPC-H](https://www.duckdb.org/docs/current/core_extensions/tpch.html) and [Hotdata Quick Start](https://www.hotdata.dev/docs/quick-start)). If your data lives under `main` instead, pass `--default-schema` / `--default-connection` or set `HOTDATA_DEFAULT_*` (see `examples/_helpers.py`).
+
+## Examples
+
+Needs `HOTDATA_API_KEY` and `HOTDATA_WORKSPACE`.
+
+```bash
+uv sync
+export HOTDATA_API_KEY=…
+export HOTDATA_WORKSPACE=…
+uv run python examples/01_catalog_introspection.py
+uv run python examples/02_execute_sql.py 'SELECT COUNT(*) AS n FROM tpch.tpch_sf1.customer'
+uv run python examples/03_connect_via_url.py
+uv run python examples/04_ibis_table_workflows.py
+```
+
+### Ibis tables → pandas DataFrames
+
+Calling **`.execute()`** on a table expression runs the compiled SQL on Hotdata and returns a **pandas** `DataFrame` (Ibis’s default for this backend).
+
+Hotdata’s SQL often uses a **federated prefix** (for example `tpch.tpch_sf1`) that may not match the Ibis **catalog** string (the connection id). A reliable pattern is to start from **`con.sql("SELECT * FROM tpch.tpch_sf1.mytable", dialect="postgres")`**, then chain filters and aggregates—see **`examples/04_ibis_table_workflows.py`**.
+
+When **`con.table("mytable")`** is enough (single connection/schema and names align with compiled SQL), the same operations apply:
+
+```python
+t = con.table("customer")  # or con.table("customer", database=(conn_id, "tpch_sf1"))
+
+df = (
+    t.filter(t.c_mktsegment == "AUTOMOBILE")
+    .select("c_custkey", "c_name")
+    .limit(100)
+    .execute()
+)
+
+by_seg = t.group_by(t.c_mktsegment).agg(n=t.count()).execute()
+
+o = con.table("orders")
+orders_with_names = (
+    t.join(o, t.c_custkey == o.o_custkey)
+    .select(t.c_name, o.o_totalprice)
+    .limit(50)
+    .execute()
+)
+
+total = t.c_acctbal.sum().execute()
+```
+
+Other useful paths: **`.to_pyarrow()`** / **`.to_pyarrow_batches()`** for Arrow; **`con.sql("SELECT …", dialect="postgres")`** then chain the returned table expression.
+
+## References
+
+- [Hotdata Python SDK](https://github.com/hotdata-dev/sdk-python)
+- [Hotdata API](https://www.hotdata.dev/docs/api-reference) · [Hotdata SQL](https://www.hotdata.dev/docs/sql)
+- [Ibis](https://ibis-project.org/) · [Ibis backend hierarchy](https://ibis-project.org/concepts/backend-table-hierarchy.qmd)

hotdata_ibis-0.1.1/README.md

@@ -0,0 +1,149 @@
+# hotdata-ibis
+
+Experimental [Ibis](https://ibis-project.org/) backend for [Hotdata](https://www.hotdata.dev/docs/api-reference): compile expressions with Ibis, run federated SQL over the Hotdata API. REST calls use the official **[hotdata](https://github.com/hotdata-dev/sdk-python)** Python SDK. Repo examples use **httpx** (listed under the **dev** dependency group).
+
+**Requirements:** Python 3.10+, **ibis-framework** 10.x, **hotdata** ≥0.2.
+
+## Install
+
+```bash
+uv pip install hotdata-ibis
+# or: python -m pip install hotdata-ibis
+```
+
+## Features
+
+- **Ibis connection API** — connect with `ibis.hotdata.connect(...)` or `ibis.connect("hotdata://...")`.
+- **Hotdata catalog mapping** — expose Hotdata connections, schemas, and tables through Ibis catalogs, databases, and tables.
+- **SQL-backed expression execution** — compile Ibis expressions with the Postgres SQLGlot compiler and execute them through Hotdata query APIs.
+- **Typed table discovery** — load schema metadata from Hotdata information schema and map SQL types into Ibis types.
+- **Arrow and pandas results** — materialize expressions as pandas DataFrames, PyArrow tables, or local Arrow record batches.
+- **Raw SQL escape hatch** — use `con.sql(..., dialect="postgres")` when Hotdata-specific federated SQL is clearer than modeled Ibis expressions.
+- **Managed database writes** — create managed connections with `create_database`, load local pandas or PyArrow data through `create_table`, and clean up with `drop_table` / `drop_database`.
+
+## Connect
+
+Programmatic API:
+
+```python
+import ibis
+
+con = ibis.hotdata.connect(
+    api_url="https://api.hotdata.dev",
+    token="YOUR_API_TOKEN",
+    workspace_id="ws_…",
+    session_id=None,       # optional: X-Session-Id (sandbox)
+    verify_ssl=True,
+    timeout=120.0,
+    default_connection=None,  # Hotdata connection id → Ibis catalog
+    default_schema=None,      # remote schema → Ibis database
+    poll_interval_s=0.25,
+    poll_timeout_s=600.0,
+)
+```
+
+URL style (token may live in the query string or the URL “password” segment):
+
+```python
+con = ibis.connect(
+    "hotdata://api.hotdata.dev/?token=…&workspace_id=ws_…&verify_ssl=true"
+)
+```
+
+**Mapping:** Ibis **catalog** = Hotdata connection id; **database** = remote schema; **table** = table name. SQL references look like `connection.schema.table`. With a single connection and schema, defaults are inferred; otherwise set `default_connection` / `default_schema` or qualify `con.table(..., database=(conn_id, schema))`.
+
+**Execution:** SQL is compiled with Ibis’s **Postgres** SQLGlot compiler. The client submits queries asynchronously with `POST /v1/query`, polls `GET /v1/query-runs/{id}`, then downloads ready results as Arrow IPC from `GET /v1/results/{id}`. Tuning: `poll_interval_s`, `poll_timeout_s` on `connect()`.
+
+**Types:** Typed tables come from Hotdata’s information schema. `con.sql(...)` types are inferred from a small preview query and Arrow schema; see [Hotdata SQL](https://www.hotdata.dev/docs/sql) for server behavior.
+
+## Ibis Support Overview
+
+`hotdata-ibis` is a read-oriented SQL backend. It is useful for exploring Hotdata workspaces with Ibis expressions, running federated SQL, and materializing results locally, but it is not a full mutable database backend.
+
+Supported today:
+
+- **Connection setup:** `ibis.hotdata.connect(...)` and `ibis.connect("hotdata://...")` with token, workspace, optional sandbox session, TLS, timeout, and polling settings.
+- **Catalog discovery:** `list_catalogs`, `list_databases`, `list_tables`, `current_catalog`, and `current_database` map Hotdata connections and remote schemas into Ibis' catalog/database/table hierarchy.
+- **Table schemas:** `con.table(...)` uses Hotdata information schema column metadata and maps SQL types through Ibis' Postgres type parser.
+- **SQL-backed expressions:** Ibis expressions compile with the Postgres SQLGlot compiler and execute through Hotdata. Common `SELECT` workloads such as projection, filtering, joins, grouping, aggregation, ordering, limits, scalar expressions, and `con.sql(...)` work when the generated SQL is accepted by Hotdata.
+- **Result materialization:** `.execute()` returns pandas objects. `.to_pyarrow()` and `.to_pyarrow_batches()` use the Arrow IPC result data exposed by Hotdata without converting through JSON rows; batches are split locally after the result is downloaded.
+- **Raw SQL escape hatch:** `con.sql("SELECT ...", dialect="postgres")` is the most reliable way to use Hotdata-specific federated table names or SQL that Ibis does not model directly.
+- **Managed database lifecycle:** `create_database("sales", schema="public", tables=["orders"])` registers a managed connection (Ibis catalog). `create_table("orders", pandas_df, database=("sales", "public"))` uploads Parquet and loads it with replace mode. Query as `sales.public.orders` in SQL. `drop_table` clears a managed table; `drop_database` deletes the connection.
+- **Parquet uploads:** `create_table` accepts pandas DataFrames, PyArrow tables, or schema-only empty tables. Tables must live in a managed connection — declare them with `create_database(..., tables=[...])` first. Loads always use replace mode; pass `overwrite=True` to replace an existing synced table (the default `overwrite=False` raises if the table already exists).
+
+Not supported as full Ibis backend features:
+
+- **General DDL and mutations:** Arbitrary remote DDL, inserts, updates, deletes, and schema-altering operations on external connections are not implemented. Managed-database writes are limited to `create_database`, `create_table`, `drop_table`, and `drop_database` as described above.
+- **Temporary tables and in-memory registration:** `supports_temporary_tables` is false, and in-memory tables are not uploaded automatically for joins.
+- **Python UDFs:** `supports_python_udfs` is false.
+- **Transactions and sessions as database state:** Hotdata sandbox sessions can be passed as `session_id`, but the backend does not expose transaction APIs.
+- **Backend-native SQL dialect:** Compilation uses Ibis' Postgres dialect as the closest fit. Hotdata SQL and federation rules are authoritative, so not every Ibis expression that compiles is guaranteed to execute remotely.
+- **Complete Ibis compliance:** The backend is experimental and has focused test coverage for connection, discovery, schema mapping, execution, uploads, and Arrow results. It has not yet been validated against the full Ibis backend test suite.
+- **Hotdata platform APIs beyond SQL and managed databases:** embeddings, indexes, query history management, sandbox lifecycle management, and other Hotdata-specific APIs are outside the Ibis backend surface.
+
+## Development
+
+```bash
+uv sync   # installs dev group by default (pytest, ruff, httpx for examples)
+uv run pytest
+uv run ruff check src tests examples
+```
+
+Lockfile CI: `uv sync --locked && uv run pytest`.
+
+## TPC-H for the examples
+
+Examples assume something like **`tpch.tpch_sf1.customer`**. Provision TPC-H in your workspace (commonly a **DuckDB** connection, then DuckDB’s `tpch` extension and `CALL dbgen(sf = 1)` — see [DuckDB TPC-H](https://www.duckdb.org/docs/current/core_extensions/tpch.html) and [Hotdata Quick Start](https://www.hotdata.dev/docs/quick-start)). If your data lives under `main` instead, pass `--default-schema` / `--default-connection` or set `HOTDATA_DEFAULT_*` (see `examples/_helpers.py`).
+
+## Examples
+
+Needs `HOTDATA_API_KEY` and `HOTDATA_WORKSPACE`.
+
+```bash
+uv sync
+export HOTDATA_API_KEY=…
+export HOTDATA_WORKSPACE=…
+uv run python examples/01_catalog_introspection.py
+uv run python examples/02_execute_sql.py 'SELECT COUNT(*) AS n FROM tpch.tpch_sf1.customer'
+uv run python examples/03_connect_via_url.py
+uv run python examples/04_ibis_table_workflows.py
+```
+
+### Ibis tables → pandas DataFrames
+
+Calling **`.execute()`** on a table expression runs the compiled SQL on Hotdata and returns a **pandas** `DataFrame` (Ibis’s default for this backend).
+
+Hotdata’s SQL often uses a **federated prefix** (for example `tpch.tpch_sf1`) that may not match the Ibis **catalog** string (the connection id). A reliable pattern is to start from **`con.sql("SELECT * FROM tpch.tpch_sf1.mytable", dialect="postgres")`**, then chain filters and aggregates—see **`examples/04_ibis_table_workflows.py`**.
+
+When **`con.table("mytable")`** is enough (single connection/schema and names align with compiled SQL), the same operations apply:
+
+```python
+t = con.table("customer")  # or con.table("customer", database=(conn_id, "tpch_sf1"))
+
+df = (
+    t.filter(t.c_mktsegment == "AUTOMOBILE")
+    .select("c_custkey", "c_name")
+    .limit(100)
+    .execute()
+)
+
+by_seg = t.group_by(t.c_mktsegment).agg(n=t.count()).execute()
+
+o = con.table("orders")
+orders_with_names = (
+    t.join(o, t.c_custkey == o.o_custkey)
+    .select(t.c_name, o.o_totalprice)
+    .limit(50)
+    .execute()
+)
+
+total = t.c_acctbal.sum().execute()
+```
+
+Other useful paths: **`.to_pyarrow()`** / **`.to_pyarrow_batches()`** for Arrow; **`con.sql("SELECT …", dialect="postgres")`** then chain the returned table expression.
+
+## References
+
+- [Hotdata Python SDK](https://github.com/hotdata-dev/sdk-python)
+- [Hotdata API](https://www.hotdata.dev/docs/api-reference) · [Hotdata SQL](https://www.hotdata.dev/docs/sql)
+- [Ibis](https://ibis-project.org/) · [Ibis backend hierarchy](https://ibis-project.org/concepts/backend-table-hierarchy.qmd)

hotdata_ibis-0.1.1/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hotdata-ibis"
+version = "0.1.1"
+description = "Ibis backend for Hotdata federated SQL API (depends on the hotdata SDK only; not hotdata-runtime)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Hotdata Ibis contributors" }]
+keywords = ["ibis", "hotdata", "sql", "dataframe"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+  "ibis-framework>=10.0,<11",
+  "hotdata>=0.2.0",
+  "pyarrow>=15",
+  "pyarrow-hotfix>=0.6",
+  "pandas>=2",
+  "sqlglot>=24",
+]
+
+[dependency-groups]
+dev = [
+  "httpx>=0.27",
+  "pytest>=8",
+  "pytest-httpserver>=1",
+  "ruff>=0.5",
+]
+
+[tool.uv]
+default-groups = ["dev"]
+
+[project.urls]
+Documentation = "https://www.hotdata.dev/docs/api-reference"
+"Ibis" = "https://ibis-project.org/"
+
+[project.entry-points."ibis.backends"]
+hotdata = "ibis_hotdata"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["E402"]
+"examples/**/*.py" = ["E402"]

hotdata_ibis-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hotdata_ibis-0.1.1/src/hotdata_ibis.egg-info/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: hotdata-ibis
+Version: 0.1.1
+Summary: Ibis backend for Hotdata federated SQL API (depends on the hotdata SDK only; not hotdata-runtime)
+Author: Hotdata Ibis contributors
+License: Apache-2.0
+Project-URL: Documentation, https://www.hotdata.dev/docs/api-reference
+Project-URL: Ibis, https://ibis-project.org/
+Keywords: ibis,hotdata,sql,dataframe
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: ibis-framework<11,>=10.0
+Requires-Dist: hotdata>=0.2.0
+Requires-Dist: pyarrow>=15
+Requires-Dist: pyarrow-hotfix>=0.6
+Requires-Dist: pandas>=2
+Requires-Dist: sqlglot>=24
+
+# hotdata-ibis
+
+Experimental [Ibis](https://ibis-project.org/) backend for [Hotdata](https://www.hotdata.dev/docs/api-reference): compile expressions with Ibis, run federated SQL over the Hotdata API. REST calls use the official **[hotdata](https://github.com/hotdata-dev/sdk-python)** Python SDK. Repo examples use **httpx** (listed under the **dev** dependency group).
+
+**Requirements:** Python 3.10+, **ibis-framework** 10.x, **hotdata** ≥0.2.
+
+## Install
+
+```bash
+uv pip install hotdata-ibis
+# or: python -m pip install hotdata-ibis
+```
+
+## Features
+
+- **Ibis connection API** — connect with `ibis.hotdata.connect(...)` or `ibis.connect("hotdata://...")`.
+- **Hotdata catalog mapping** — expose Hotdata connections, schemas, and tables through Ibis catalogs, databases, and tables.
+- **SQL-backed expression execution** — compile Ibis expressions with the Postgres SQLGlot compiler and execute them through Hotdata query APIs.
+- **Typed table discovery** — load schema metadata from Hotdata information schema and map SQL types into Ibis types.
+- **Arrow and pandas results** — materialize expressions as pandas DataFrames, PyArrow tables, or local Arrow record batches.
+- **Raw SQL escape hatch** — use `con.sql(..., dialect="postgres")` when Hotdata-specific federated SQL is clearer than modeled Ibis expressions.
+- **Managed database writes** — create managed connections with `create_database`, load local pandas or PyArrow data through `create_table`, and clean up with `drop_table` / `drop_database`.
+
+## Connect
+
+Programmatic API:
+
+```python
+import ibis
+
+con = ibis.hotdata.connect(
+    api_url="https://api.hotdata.dev",
+    token="YOUR_API_TOKEN",
+    workspace_id="ws_…",
+    session_id=None,       # optional: X-Session-Id (sandbox)
+    verify_ssl=True,
+    timeout=120.0,
+    default_connection=None,  # Hotdata connection id → Ibis catalog
+    default_schema=None,      # remote schema → Ibis database
+    poll_interval_s=0.25,
+    poll_timeout_s=600.0,
+)
+```
+
+URL style (token may live in the query string or the URL “password” segment):
+
+```python
+con = ibis.connect(
+    "hotdata://api.hotdata.dev/?token=…&workspace_id=ws_…&verify_ssl=true"
+)
+```
+
+**Mapping:** Ibis **catalog** = Hotdata connection id; **database** = remote schema; **table** = table name. SQL references look like `connection.schema.table`. With a single connection and schema, defaults are inferred; otherwise set `default_connection` / `default_schema` or qualify `con.table(..., database=(conn_id, schema))`.
+
+**Execution:** SQL is compiled with Ibis’s **Postgres** SQLGlot compiler. The client submits queries asynchronously with `POST /v1/query`, polls `GET /v1/query-runs/{id}`, then downloads ready results as Arrow IPC from `GET /v1/results/{id}`. Tuning: `poll_interval_s`, `poll_timeout_s` on `connect()`.
+
+**Types:** Typed tables come from Hotdata’s information schema. `con.sql(...)` types are inferred from a small preview query and Arrow schema; see [Hotdata SQL](https://www.hotdata.dev/docs/sql) for server behavior.
+
+## Ibis Support Overview
+
+`hotdata-ibis` is a read-oriented SQL backend. It is useful for exploring Hotdata workspaces with Ibis expressions, running federated SQL, and materializing results locally, but it is not a full mutable database backend.
+
+Supported today:
+
+- **Connection setup:** `ibis.hotdata.connect(...)` and `ibis.connect("hotdata://...")` with token, workspace, optional sandbox session, TLS, timeout, and polling settings.
+- **Catalog discovery:** `list_catalogs`, `list_databases`, `list_tables`, `current_catalog`, and `current_database` map Hotdata connections and remote schemas into Ibis' catalog/database/table hierarchy.
+- **Table schemas:** `con.table(...)` uses Hotdata information schema column metadata and maps SQL types through Ibis' Postgres type parser.
+- **SQL-backed expressions:** Ibis expressions compile with the Postgres SQLGlot compiler and execute through Hotdata. Common `SELECT` workloads such as projection, filtering, joins, grouping, aggregation, ordering, limits, scalar expressions, and `con.sql(...)` work when the generated SQL is accepted by Hotdata.
+- **Result materialization:** `.execute()` returns pandas objects. `.to_pyarrow()` and `.to_pyarrow_batches()` use the Arrow IPC result data exposed by Hotdata without converting through JSON rows; batches are split locally after the result is downloaded.
+- **Raw SQL escape hatch:** `con.sql("SELECT ...", dialect="postgres")` is the most reliable way to use Hotdata-specific federated table names or SQL that Ibis does not model directly.
+- **Managed database lifecycle:** `create_database("sales", schema="public", tables=["orders"])` registers a managed connection (Ibis catalog). `create_table("orders", pandas_df, database=("sales", "public"))` uploads Parquet and loads it with replace mode. Query as `sales.public.orders` in SQL. `drop_table` clears a managed table; `drop_database` deletes the connection.
+- **Parquet uploads:** `create_table` accepts pandas DataFrames, PyArrow tables, or schema-only empty tables. Tables must live in a managed connection — declare them with `create_database(..., tables=[...])` first. Loads always use replace mode; pass `overwrite=True` to replace an existing synced table (the default `overwrite=False` raises if the table already exists).
+
+Not supported as full Ibis backend features:
+
+- **General DDL and mutations:** Arbitrary remote DDL, inserts, updates, deletes, and schema-altering operations on external connections are not implemented. Managed-database writes are limited to `create_database`, `create_table`, `drop_table`, and `drop_database` as described above.
+- **Temporary tables and in-memory registration:** `supports_temporary_tables` is false, and in-memory tables are not uploaded automatically for joins.
+- **Python UDFs:** `supports_python_udfs` is false.
+- **Transactions and sessions as database state:** Hotdata sandbox sessions can be passed as `session_id`, but the backend does not expose transaction APIs.
+- **Backend-native SQL dialect:** Compilation uses Ibis' Postgres dialect as the closest fit. Hotdata SQL and federation rules are authoritative, so not every Ibis expression that compiles is guaranteed to execute remotely.
+- **Complete Ibis compliance:** The backend is experimental and has focused test coverage for connection, discovery, schema mapping, execution, uploads, and Arrow results. It has not yet been validated against the full Ibis backend test suite.
+- **Hotdata platform APIs beyond SQL and managed databases:** embeddings, indexes, query history management, sandbox lifecycle management, and other Hotdata-specific APIs are outside the Ibis backend surface.
+
+## Development
+
+```bash
+uv sync   # installs dev group by default (pytest, ruff, httpx for examples)
+uv run pytest
+uv run ruff check src tests examples
+```
+
+Lockfile CI: `uv sync --locked && uv run pytest`.
+
+## TPC-H for the examples
+
+Examples assume something like **`tpch.tpch_sf1.customer`**. Provision TPC-H in your workspace (commonly a **DuckDB** connection, then DuckDB’s `tpch` extension and `CALL dbgen(sf = 1)` — see [DuckDB TPC-H](https://www.duckdb.org/docs/current/core_extensions/tpch.html) and [Hotdata Quick Start](https://www.hotdata.dev/docs/quick-start)). If your data lives under `main` instead, pass `--default-schema` / `--default-connection` or set `HOTDATA_DEFAULT_*` (see `examples/_helpers.py`).
+
+## Examples
+
+Needs `HOTDATA_API_KEY` and `HOTDATA_WORKSPACE`.
+
+```bash
+uv sync
+export HOTDATA_API_KEY=…
+export HOTDATA_WORKSPACE=…
+uv run python examples/01_catalog_introspection.py
+uv run python examples/02_execute_sql.py 'SELECT COUNT(*) AS n FROM tpch.tpch_sf1.customer'
+uv run python examples/03_connect_via_url.py
+uv run python examples/04_ibis_table_workflows.py
+```
+
+### Ibis tables → pandas DataFrames
+
+Calling **`.execute()`** on a table expression runs the compiled SQL on Hotdata and returns a **pandas** `DataFrame` (Ibis’s default for this backend).
+
+Hotdata’s SQL often uses a **federated prefix** (for example `tpch.tpch_sf1`) that may not match the Ibis **catalog** string (the connection id). A reliable pattern is to start from **`con.sql("SELECT * FROM tpch.tpch_sf1.mytable", dialect="postgres")`**, then chain filters and aggregates—see **`examples/04_ibis_table_workflows.py`**.
+
+When **`con.table("mytable")`** is enough (single connection/schema and names align with compiled SQL), the same operations apply:
+
+```python
+t = con.table("customer")  # or con.table("customer", database=(conn_id, "tpch_sf1"))
+
+df = (
+    t.filter(t.c_mktsegment == "AUTOMOBILE")
+    .select("c_custkey", "c_name")
+    .limit(100)
+    .execute()
+)
+
+by_seg = t.group_by(t.c_mktsegment).agg(n=t.count()).execute()
+
+o = con.table("orders")
+orders_with_names = (
+    t.join(o, t.c_custkey == o.o_custkey)
+    .select(t.c_name, o.o_totalprice)
+    .limit(50)
+    .execute()
+)
+
+total = t.c_acctbal.sum().execute()
+```
+
+Other useful paths: **`.to_pyarrow()`** / **`.to_pyarrow_batches()`** for Arrow; **`con.sql("SELECT …", dialect="postgres")`** then chain the returned table expression.
+
+## References
+
+- [Hotdata Python SDK](https://github.com/hotdata-dev/sdk-python)
+- [Hotdata API](https://www.hotdata.dev/docs/api-reference) · [Hotdata SQL](https://www.hotdata.dev/docs/sql)
+- [Ibis](https://ibis-project.org/) · [Ibis backend hierarchy](https://ibis-project.org/concepts/backend-table-hierarchy.qmd)

hotdata_ibis-0.1.1/src/hotdata_ibis.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+README.md
+pyproject.toml
+src/hotdata_ibis.egg-info/PKG-INFO
+src/hotdata_ibis.egg-info/SOURCES.txt
+src/hotdata_ibis.egg-info/dependency_links.txt
+src/hotdata_ibis.egg-info/entry_points.txt
+src/hotdata_ibis.egg-info/requires.txt
+src/hotdata_ibis.egg-info/top_level.txt
+src/ibis_hotdata/__init__.py
+src/ibis_hotdata/backend.py
+src/ibis_hotdata/http.py
+src/ibis_hotdata/managed.py
+src/ibis_hotdata/types.py
+tests/test_architecture_guardrails.py
+tests/test_hotdata_backend.py
+tests/test_hotdata_http.py
+tests/test_hotdata_types.py
+tests/test_version.py

hotdata_ibis-0.1.1/src/hotdata_ibis.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hotdata_ibis-0.1.1/src/hotdata_ibis.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[ibis.backends]
+hotdata = ibis_hotdata

hotdata_ibis-0.1.1/src/hotdata_ibis.egg-info/requires.txt

@@ -0,0 +1,6 @@
+ibis-framework<11,>=10.0
+hotdata>=0.2.0
+pyarrow>=15
+pyarrow-hotfix>=0.6
+pandas>=2
+sqlglot>=24

hotdata_ibis-0.1.1/src/hotdata_ibis.egg-info/top_level.txt

@@ -0,0 +1 @@
+ibis_hotdata

hotdata_ibis-0.1.1/src/ibis_hotdata/__init__.py

@@ -0,0 +1,10 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("hotdata-ibis")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"
+
+from ibis_hotdata.backend import Backend
+
+__all__ = ["Backend", "__version__"]