Skip to main content

Onehouse Hook

The OnehouseHook is the main interface for interacting with the Onehouse API. It provides methods for submitting SQL commands, checking their status, and waiting for their completion.

Connection Setup​

To use the Onehouse Hook, you need to set up an Airflow connection with the following parameters:

  • Connection Type: Generic
  • Host: https://api.onehouse.ai
  • Extra: JSON object containing:
    • project_uid: Your Onehouse project UID
    • user_id: Your Onehouse user ID
    • api_key: Your Onehouse API key
    • api_secret: Your Onehouse API secret
    • link_uid: Your Onehouse link UID
    • region: Your Onehouse region

Example connection setup in Airflow UI:

{
  "project_uid": "your-project-uid",
  "user_id": "your-user-id",
  "api_key": "your-api-key",
  "api_secret": "your-api-secret",
  "link_uid": "your-link-uid",
  "region": "your-region"
}

Methods​

submit_sql(sql: str) -> str​

Submits a SQL command to the Onehouse SQL API.

Parameters:

  • sql (str): The SQL command to execute

Returns:

  • str: The request ID for tracking the command's status

Raises:

  • AirflowException: If the SQL submission fails

get_status(request_id: str) -> dict​

Retrieves the status and response of a submitted SQL command.

Parameters:

  • request_id (str): The request ID returned by submit_sql()

Returns:

  • dict: The status response containing apiStatus and apiResponse

Raises:

  • AirflowException: If the status check fails

wait_for_status(request_id: str, poll_interval: int = 10, timeout: int = 300) -> dict​

Polls the status endpoint until a terminal state is reached or timeout occurs.

Parameters:

  • request_id (str): The request ID to poll status for
  • poll_interval (int): Poll frequency in seconds (default: 10s)
  • timeout (int): Max wait time in seconds (default: 300s / 5 min)

Returns:

  • dict: The final response JSON

Raises:

  • AirflowException: If the operation fails or times out

Example Usage​

from airflow_providers_onehouse.hooks.onehouse import OnehouseHook

# Create hook instance
hook = OnehouseHook(conn_id='onehouse_default')

# Submit SQL command
request_id = hook.submit_sql("CREATE CLUSTER my_cluster TYPE = 'SPARK' MAX_OCU = 2 MIN_OCU = 1")

# Wait for completion
result = hook.wait_for_status(request_id, timeout=1200)