Execution modes
There are three ways to run a command against the control plane. Prefer typed helpers — they build the SQL for you and validate inputs (resource name regex, enum values) before the request leaves your process. Drop down to execute() only when the SDK doesn't yet wrap the command you need, and to submit() / get_status() only when you need to detach the submission from the polling.
When to use each
| Mode | Use when | Trade-off |
|---|---|---|
Typed helpers (client.create_cluster(...)) | This is the default. You're calling a command the SDK already wraps. | None — they're a thin layer over execute() that adds validation. |
execute(sql) | You need a SQL command the SDK doesn't expose yet (e.g. GRANT, REVOKE, role management). | No input validation; you hand-write SQL. |
submit() + get_status() | You want to detach submission from polling — e.g. submit from a web request and poll from a background worker, or fan out many submissions and poll in parallel. | You handle the polling loop. |
1. Typed helpers (recommended)
Same blocking semantics as execute(), plus the SDK builds the SQL and validates resource names, enum values, and required-parameter combinations.
client.create_cluster("prod", type="Managed", max_ocu=10, min_ocu=1)
client.show_clusters()
client.delete_cluster("prod")
See Typed helpers for the full list of 52 methods across 13 resource families.
2. Blocking — execute()
Submit, poll, return the terminal status. Use this for raw SQL the typed helpers don't yet cover.
result = client.execute("GRANT SELECT ON TABLE analytics.events.page_views TO ROLE analyst")
Defaults (override per call or per client):
| Parameter | Default | Override on the client | Override per call |
|---|---|---|---|
timeout | 60.0 seconds | OnehouseResources(default_execute_timeout=...) | client.execute(sql, timeout=...) |
poll_interval | 1.0 second (grows to a cap of 10.0s via 1.5× backoff) | OnehouseResources(default_poll_interval=...) | client.execute(sql, poll_interval=...) |
The same timeout / poll_interval overrides work on every typed helper.
3. Non-blocking — submit() + get_status()
Submit now, poll later. Persist request_id if your poller is in a different process.
from onehouse_python_sdk.resources import ApiStatus
submitted = client.submit(
"CREATE CLUSTER `prod` TYPE = 'Managed' MAX_OCU = 10 MIN_OCU = 1"
)
# ... persist submitted.request_id, do other work ...
status = client.get_status(submitted.request_id)
while status.api_status == ApiStatus.PENDING:
time.sleep(5)
status = client.get_status(submitted.request_id)
get_status is also how you recover from OperationTimeoutError — see Error handling.