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 a typed client for the oleander API. It covers lake queries, Spark job management, Spark cluster lookup, and run polling.

​
Installation

npm 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, in Node.js, set the OLEANDER_API_KEY environment variable. 
import { Oleander } from "@oleanderhq/sdk";

// Option 1: pass the key directly
const client = new Oleander({ apiKey: "your-api-key" });

// Option 2: reads OLEANDER_API_KEY from the environment
const client = new Oleander();

​
Quick start

import { Oleander } from "@oleanderhq/sdk";

const client = new Oleander();

// Query the lake and iterate over results
const result = await client.query(
  "SELECT * FROM oleander.default.flowers LIMIT 10",
);
for (const row of result.results?.rows ?? []) {
  const [sepalLength, sepalWidth] = row as [number, number];
  // process each row ...
}

// List available Spark job scripts
const { scripts } = await client.listSparkJobs();

// Submit a Spark job and wait for it to finish
const { runId, state } = await client.submitSparkJobAndWait({
  namespace: "my-namespace",
  name: "daily-etl",
  entrypoint: "etl_pipeline.py",
});

if (state !== "COMPLETE") {
  throw new Error(`Run ${runId} ended with state: ${state}`);
}

​
Working with clusters

Use cluster: "oleander" for oleander-managed Spark or pass the name of a registered cluster when submitting a job. 
const cluster = await client.getSparkCluster({ name: "emr-prod" });
console.log(cluster.type, cluster.properties);

​
Constructor options

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

​
Errors

The SDK throws structured HTTP errors for non-2xx responses. 
import { OleanderHttpError, RunNotFoundError } from "@oleanderhq/sdk";

try {
  await client.getRun("run-id");
} catch (error) {
  if (error instanceof RunNotFoundError) {
    console.log("Run is not visible yet:", error.runId);
  } else if (error instanceof OleanderHttpError) {
    console.log(error.status, error.path, error.apiError ?? error.apiDetails);
  } else {
    throw error;
  }
}