Skip to main content

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.

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 example QueryApi.md)
  • Request and response models: docs/<ModelName>.md

Support

Questions and issues: github.com/hotdata-dev/sdk-python.

Metadata

Release files for hotdata 0.13.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hotdata 0.13.0
File Size Uploaded Provenance Actions
hotdata-0.13.0.tar.gz 242.2 kB With provenance Details for hotdata-0.13.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hotdata 0.13.0
File Interpreter ABI Platform Actions
hotdata-0.13.0-py3-none-any.whl Python 3 none any Details for hotdata-0.13.0-py3-none-any.whl

Total release size: 574.6 kB

Release files / hotdata-0.13.0.tar.gz

Download URL hotdata-0.13.0.tar.gz
Size 242.2 kB
Tags Source
SHA-256 checksum
How to use checksums
41c18797e6ddcb949306a3b281e2a335fcccc93585ed2290ab1f62ba02016acc
BLAKE2b-256 checksum
How to use checksums
919c4913f248df2a4e251c27906eb3a049d8db9cac9a1a6b62f5d87e28732859
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 6, 2026.

Transparency log

Release files / hotdata-0.13.0-py3-none-any.whl

Download URL hotdata-0.13.0-py3-none-any.whl
Size 332.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
59962d639f397809d9f2992861fb12aaecad358a7bffd328ce4e239be246cb92
BLAKE2b-256 checksum
How to use checksums
05dc014410e56e4ece8947bb03f91f71ae19858f69687de159b15043c697dd99
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 6, 2026.

Transparency log

Security for hotdata 0.13.0

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.

Select from 2 files

Attestation for hotdata-0.13.0.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 6, 2026.

Transparency log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page