Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.oleander.dev/llms.txt

Use this file to discover all available pages before exploring further.

The oleanderhq-sdk package provides an async client for the oleander API. It covers lake queries, Spark job management, Spark cluster lookup, and run polling.

​
Installation

pip install oleanderhq-sdk

​
Authentication

Create an API key in your oleander settings, or run oleander configure if you use the CLI. You can pass the key directly or set the OLEANDER_API_KEY environment variable. 
from oleander_sdk import Oleander

# Option 1: pass the key directly
client = Oleander(api_key="your-api-key")

# Option 2: reads OLEANDER_API_KEY from the environment
client = Oleander()

​
Quick start

import asyncio
from oleander_sdk import Oleander, SubmitSparkJobAndWaitOptions

async def main():
    client = Oleander()

    result = await client.query(
        "SELECT * FROM oleander.default.flowers LIMIT 10"
    )
    for row in result.results.rows:
        sepal_length, sepal_width = row[0], row[1]
        # process each row ...

    jobs = await client.list_spark_jobs()
    print(jobs.scripts)

    run = await client.submit_spark_job_and_wait(
        SubmitSparkJobAndWaitOptions(
            namespace="my-namespace",
            name="daily-etl",
            entrypoint="etl_pipeline.py",
        )
    )

    if run.state != "COMPLETE":
        raise Exception(f"Run {run.run_id} ended with state: {run.state}")

asyncio.run(main())

​
Working with clusters

Use cluster="oleander" for oleander-managed Spark or pass the name of a registered cluster when submitting a job. 
cluster = await client.get_spark_cluster("emr-prod")
print(cluster.type, cluster.properties)

​
Constructor options

ParameterTypeDefaultDescription
api_keystrOLEANDER_API_KEY env varYour oleander API key
base_urlstrhttps://oleander.devAPI base URL. Override for local development.

​
Errors

The SDK raises structured HTTP errors for non-2xx responses. 
from oleander_sdk import OleanderHttpError, RunNotFoundError

try:
    await client.get_run("run-id")
except RunNotFoundError as error:
    print("Run is not visible yet:", error.run_id)
except OleanderHttpError as error:
    print(error.status, error.path, error.api_error or error.api_details)