Getting Started

OnehouseResources wraps the Onehouse REST API for managing platform resources — clusters, lakes, flows, jobs, table services, and more. It posts SQL statements to https://api.onehouse.ai/v1/resource/ and polls /v1/status/{requestId} for the result.

Installation

pip install onehouse-python-sdk[resources]

Quickstart

from onehouse_python_sdk import OnehouseResources

client = OnehouseResources(
    account_uid="...", project_uid="...",
    api_key="...", api_secret="...",
    link_uid="...", region="us-west-2", user_uid="...",
)

# Typed helper — blocks until the operation reaches a terminal status.
result = client.create_cluster(
    "prod",
    type="Managed",
    max_ocu=10,
    min_ocu=1,
    options={"worker.type": "oh-general-4"},
)
print(result.api_status)        # ApiStatus.SUCCESS
print(result.api_response)      # parsed payload — shape depends on the command

Typed helpers are the recommended path — see Execution modes for when you'd reach for execute() or submit() instead.

What the API returns

Every blocking call (typed helper or execute()) returns a StatusResponse. Non-blocking submit() returns a SubmitResponse.

StatusResponse

Field	Type	Description
request_id	str	The server-assigned request ID. Stable across polls.
api_status	ApiStatus enum	One of SUCCESS, SUCCESS_PARTIAL, FAILED, INVALID, PENDING. Blocking calls only return on a terminal value (failures raise instead — see Error handling).
api_response	Any	The actual result payload. Shape depends on the command — see below.
raw	dict	The full unparsed JSON body from /v1/status/{requestId}.
.terminal	bool (property)	True if api_status is a terminal value.
.partial	bool (property)	True if api_status == SUCCESS_PARTIAL.

ApiStatus is an enum re-exported from onehouse_python_sdk.resources — its values mirror the wire format (API_OPERATION_STATUS_SUCCESS, etc.).

SubmitResponse

Returned by submit():

Field	Type	Description
request_id	str	Use this to poll get_status(request_id).
raw	dict	Full body from POST /v1/resource/.

Shape of api_response

The api_response field is whatever the command produces:

• Mutating commands (create_*, alter_*, delete_*, run_*) — typically a small dict echoing the resource that changed, or empty on success.
• describe_* commands — a dict with the full resource configuration.
• show_* commands — a list of dicts, one per resource.
• create_api_token — contains the token value. It is shown only once; persist it immediately.

Exact field names follow the Onehouse REST API contract. When in doubt, inspect result.raw to see the unparsed body.

# describe — full config of one resource
result = client.describe_cluster("prod")
print(result.api_response)
# → {"name": "prod", "type": "Managed", "max_ocu": 10, "min_ocu": 1, "state": "RUNNING", ...}

# show — a list
result = client.show_clusters()
for cluster in result.api_response:
    print(cluster["name"], cluster["state"])

# create_api_token — store immediately, it won't be shown again
result = client.create_api_token("ci_bot_token", service_principal="ci_bot")
token = result.api_response["secret"]

Next steps

• Credentials — how OnehouseResources resolves auth from constructor args, environment variables, INI files, and JSON files
• Execution modes — typed helpers (recommended), blocking execute(), non-blocking submit()
• Typed helpers — the 52 methods across 13 resource families
• Error handling — exception hierarchy, per-error handling, and resuming timed-out operations
• Client API — full method reference