hotdata
Official Python client for the Hotdata HTTP API: workspaces, connections, instant databases, SQL queries, results, uploads, indexes, jobs, embedding providers, and database context.
Requirements
Python 3.10+
Install
pip install hotdata
For an unreleased revision:
pip install "git+https://github.com/hotdata-dev/sdk-python.git"
From a local checkout (editable):
pip install -e .
Authentication
The API uses an API key sent as Authorization: Bearer <key>, plus an X-Workspace-Id header on requests scoped to a workspace.
import hotdata
configuration = hotdata.Configuration(
api_key="YOUR_API_KEY",
workspace_id="YOUR_WORKSPACE_ID",
)
Each of these can come from the environment instead, the same variables the
CLI uses: HOTDATA_API_KEY, HOTDATA_WORKSPACE and HOTDATA_API_URL fill in
api_key, workspace_id and host when the argument is not passed. An
explicit argument always wins.
host defaults to https://api.hotdata.dev. Override it (or set
HOTDATA_API_URL) if you target another environment.
Almost every call is workspace-scoped. If no workspace id is configured, the
SDK raises hotdata.MissingWorkspaceError before sending the request rather
than letting the server answer with an unexplained 404.
Usage
import hotdata
from hotdata.rest import ApiException
configuration = hotdata.Configuration(
api_key="YOUR_API_KEY",
workspace_id="YOUR_WORKSPACE_ID",
)
with hotdata.ApiClient(configuration) as api_client:
workspaces = hotdata.WorkspacesApi(api_client)
try:
response = workspaces.list_workspaces()
except ApiException as e:
print(f"API error: {e.status} {e.reason}\n{e.body}")
Each Api class groups endpoints by resource. Construct the client, then call the typed methods you need.
Loading tables
Loads are serialised per table on the server. hotdata.DatabasesApi and
hotdata.ConnectionsApi retry a load that hits a table another load still
holds (HTTP 409, error code RESOURCE_LOCKED), honouring the server's
Retry-After, for up to 60s by default:
from hotdata import DatabasesApi, LoadRetryPolicy, TableLockedError
databases = DatabasesApi(api_client, load_retry=LoadRetryPolicy(deadline_s=120))
try:
databases.load_database_table(db_id, "public", "events", request)
except TableLockedError as e:
print(f"gave up after {e.attempts} attempts: {e.reason}")
Other 409s (CONFLICT, IDEMPOTENCY_KEY_CONFLICT) are raised immediately.
Arrow results
Query results can be fetched as an Apache Arrow IPC stream instead of JSON, which is faster and far more memory-efficient for large result sets. Install the optional extra:
pip install 'hotdata[arrow]'
Use hotdata.arrow.ResultsApi (a drop-in subclass of ResultsApi that adds Arrow methods):
from hotdata import ApiClient, Configuration
from hotdata.arrow import ResultsApi
with ApiClient(Configuration(api_key="...", workspace_id="...")) as client:
results = ResultsApi(client)
# Results are scoped to a database via the required `X-Database-Id` header,
# so pass the id of the database the query ran in.
database_id = "your_database_id"
# Buffered: returns a pyarrow.Table.
table = results.get_result_arrow(result_id, database_id)
# Streaming: yields a pyarrow.RecordBatchStreamReader without
# materializing the full table in memory.
with results.stream_result_arrow(result_id, database_id) as reader:
for batch in reader:
...
Both methods accept offset and limit for pagination. They raise hotdata.arrow.ResultNotReadyError if the result is still pending or processing — poll results.get_result(result_id, database_id) until status == "ready" first.
Arrow from the query call
QueryApi.query_arrow runs a query and returns the rows as Arrow in one request, without fetching the stored result afterwards. The values the JSON response would carry come back on the result:
from hotdata import ApiClient, Configuration, QueryApi, QueryRequest
with ApiClient(Configuration(api_key="...", workspace_id="...")) as client:
out = QueryApi(client).query_arrow(
QueryRequest(sql="SELECT toStartOfHour(ts) AS h, count() FROM events GROUP BY h",
dialect="clickhouse"),
x_database_id="your_database_id",
)
out.table # pyarrow.Table, with the server's column types
out.rollup # RollupUsage.USED / NOT_MATCHED / NOT_READY / UNAVAILABLE, or None
out.query_run_id, out.result_id, out.total_row_count, out.execution_time_ms, out.warning
HTTP 429 is retried as in query. A result too large to send inline is read from the Results API instead (out.followed is True), up to max_auto_rows and max_auto_bytes (64 MiB of Arrow data by default; past a guard it raises ResultTooLargeError); pass auto_follow=False to get a ResultNotInlineError carrying the result_id and stream it yourself.
File uploads
hotdata.uploads.UploadsApi (also the default hotdata.UploadsApi) adds
upload_file, which uploads a local file directly to object storage and
finalizes it in one call. It opens an upload session, PUTs the bytes straight
to storage — a single PUT for a small file, concurrent part PUTs for a large
one — then finalizes. The bytes never round-trip through the API.
from hotdata import ApiClient, Configuration, UploadsApi
with ApiClient(Configuration(api_key="...", workspace_id="...")) as client:
uploads = UploadsApi(client)
finalized = uploads.upload_file(
"data.parquet",
content_type="application/parquet",
progress=lambda done, total: print(f"{done}/{total} bytes"),
)
# Pass finalized.upload_id to the managed-table load endpoint.
print(finalized.upload_id)
upload_file accepts a path, raw bytes, or a seekable binary file object
(size is inferred for all three; a file object is read from its current
position to the end). The SDK picks single vs. multipart from the size,
auto-scales the part size, and bounds part concurrency to a peak-memory budget
(override with part_size / max_concurrency / part_retry). A file larger than
8 MiB uploads via a streaming session — the SDK mints each part's URL just
before its PUT, so a presigned URL can't expire mid-transfer on a slow upload.
Storage PUTs go through a dedicated, header-isolated connection pool (auth and
workspace headers never reach object storage, which would otherwise reject the
upload) with a 30s connect timeout so a dead endpoint fails fast. Finalize is sent
with retries disabled so the exactly-once call is never accidentally replayed.
Every failure is a subclass of hotdata.uploads.UploadError (also importable as
from hotdata import UploadError), so a single except UploadError catches the
whole flow: SessionCreateError (opening the session — check .status for a
501 PRESIGN_UNSUPPORTED), StorageError (storage returned a non-2xx; .exhausted
is True if it outlived every retry round), StorageTransportError (the PUT
failed before any response), MissingETagError, MintPartError (minting a part
URL), FinalizeError, MalformedSessionError, SizeLimitError, and
UploadCancelledError. The phase errors that wrap a control-plane call chain the
underlying hotdata.exceptions.ApiException as __cause__ (and expose it as
.api_exception / .status). A local file read error surfaces as OSError.
The progress callback receives a cumulative (bytes_done, total) — for a
tqdm bar (whose update(n) wants a delta, and which isn't thread-safe under
multipart) use the ready-made adapter:
from hotdata import tqdm_progress
from tqdm import tqdm
with tqdm(total=size, unit="B", unit_scale=True) as bar:
uploads.upload_file("data.parquet", progress=tqdm_progress(bar))
Pass a threading.Event as cancel_event to abort an in-flight upload; tune the
control-plane calls with request_timeout (storage-PUT timeouts are automatic and
size-scaled).
API reference
Generated Markdown for every operation and model is in docs/:
- Resource APIs:
docs/*Api.md(for exampleQueryApi.md) - Request and response models:
docs/<ModelName>.md
Support
Questions and issues: github.com/hotdata-dev/sdk-python.
Metadata
Release files for hotdata 0.15.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| hotdata-0.15.1.tar.gz | 245.1 kB | With provenance | Details for hotdata-0.15.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hotdata-0.15.1-py3-none-any.whl | Python 3 | none | any | Details for hotdata-0.15.1-py3-none-any.whl |
Total release size: 593.6 kB
Release files / hotdata-0.15.1.tar.gz
| Download URL | hotdata-0.15.1.tar.gz |
|---|---|
| Size | 245.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ac1a57929ba37a10e5fd1c589b2c4c663bd4ebaf33eff56f319580ef82838742
|
|
BLAKE2b-256 checksum How to use checksums |
4d19228f3e26eae1c8ed4941fbd510c758eacad94a5fd6c6993ce10319ddc8a0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / hotdata-0.15.1-py3-none-any.whl
| Download URL | hotdata-0.15.1-py3-none-any.whl |
|---|---|
| Size | 348.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
de8ce1f9deb50259aa9817a851cd29a29c90963d31ab7e8804b9a0f29941cd3d
|
|
BLAKE2b-256 checksum How to use checksums |
7d8a2879eef8c20a9db317320f42ab85c9264197340db770b0f77789c76ec767
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logSecurity for hotdata 0.15.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for hotdata-0.15.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.