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.

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

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.15.1
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)

Table of built distributions (wheels) for hotdata 0.15.1
File Interpreter ABI Platform Actions
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 log

Release 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 log

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

Select from 2 files

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