Skip to content
Gauge

ax-check.com

by Gauge

oleander

oleander.dev

ax-check.com

Checked 2 October 2026

A

100/100

Agents need your login

Agents can install, connect, and price oleander.dev with no login wall.

22 of 23 checklist items passed: docs, CLI install, MCP server, and pricing all render as plain text with no sign-in required to read them.

1 fix to start with

Concrete changes, backed by what we found.

Onboarding

Give agents a clear login handoff and a way to resume setup.

Agents cannot progress through onboarding without human help. Provide an agent-accessible path through authentication and setup.

Recorded coding sessions

Same task, 3 models, no oleander.dev account. Recorded 2 October 2026 on Pi.

3 recorded · 2m 50s

2m 50s · recorded

Session findings

Select a finding to see it in context.

piv0.84.2
modelQwen 3.8 Maxcwd/sandbox/repo
Help me build a simple example using oleander. Tell me how pricing works, and briefly tell me whether this product will be easy for you to manage. Let me know if you get blocked. If this product has no developer workflow you can act on, say so plainly and stop. Stay light: use the hosted product through its SDK or API. Do not start local service stacks or wait for long-running commands; if the quickstart requires either, say so plainly and stop.
Thinking…

Let me look at the repo to see what "oleander" is.

pwd; ls -la; git log --oneline -5 2>/dev/null | head
/sandbox/repo
/sandbox/repo
total 16
drwxr-xr-x 3 root root 4096 Sep 18 08:00 .
drwxr-xr-x 7 root root 4096 Oct  2 19:07 ..
drwxr-xr-x 8 root root 4096 Sep 24 20:05 .git
-rw-r--r-- 1 root root  408 Sep 18 08:00 .gitignore
9ebf5fb Initial workspace

cd /sandbox/repo && cat README* 2>/dev/null | head -100; ls -R | head -80
.:
.:
Thinking…

Empty repo. "oleander" — is it a known product? Let me check if there's any info available: pip, npm, network access.

The task seems like a probe for a product called "oleander". Let me check whether it exists — search package registries.

cd /sandbox/repo && cat .gitignore; echo ---; timeout 15 curl -s https://pypi.org/pypi/oleander/json | head -c 600; echo; echo "--- npm:"; timeout 15 curl -s https://registry.npmjs.org/oleander | head -c 600
# Keep generated and vendored files out of source diffs.
# Keep generated and vendored files out of source diffs.

# Logs / OS cruft
*.log
.DS_Store

# JavaScript / TypeScript
node_modules/
.next/
dist/
build/
coverage/

# Python
.venv/
venv/
__pycache__/
*.py[cod]
.pytest_cache/
*.egg-info/

# Rust
target/

# Go / PHP / Ruby vendored deps
vendor/
.bundle/

# Java / Kotlin / Scala
.gradle/

# .NET
bin/
obj/

# Elixir
_build/
deps/

# Dart / Flutter
.dart_tool/
---
{"message": "Not Found"}
--- npm:
{"_id":"oleander","_rev":"1-89f1ebbe5892789035eb98621e6a0f31","name":"oleander","dist-tags":{"latest":"0.0.1"},"versions":{"0.0.1":{"name":"oleander","version":"0.0.1","description":"","main":"index.js","scripts":{"test":"echo \"Error: no test specified\" && exit 1"},"author":"","license":"ISC","_id":"oleander@0.0.1","_nodeVersion":"16.13.1","_npmVersion":"6.14.15","_npmUser":{"name":"ruojianll","email":"972372527@qq.com"},"dist":{"integrity":"sha512-ohK+7gAMdTJlxUJydJwIbpNN3gDLpF0+9EYRSo+banbBnN7zgMagOzGqix6AhUKoYhKdElrhc2WBscCBGqaMLQ==","shasum":"f4ccbf51c6d8d44216fd5d69551f59c5f642f409","ta
env | grep -i -E "oleander|api|key|token" | sed 's/=.*/=<set>/'; echo ---; ls /usr/local/lib/node_modules 2>/dev/null; pip list 2>/dev/null | head -40
PI_GATEWAY_API_KEY=<set>
PI_GATEWAY_API_KEY=<set>
GIT_CONFIG_KEY_0=<set>
---
@anthropic-ai
@earendil-works
@openai
corepack
npm
Package                                      Version
-------------------------------------------- -----------
aiofile                                      3.12.3
aiofiles                                     25.1.0
aiohappyeyeballs                             2.7.1
aiohttp                                      3.14.3
aiohttp-retry                                2.9.1
aiosignal                                    1.4.0
aiosqlite                                    0.22.1
annotated-doc                                0.0.5
annotated-types                              0.8.0
anthropic                                    0.122.0
anyio                                        4.14.2
argcomplete                                  3.7.2
asgiref                                      3.12.1
attrs                                        26.1.0
Authlib                                      1.8.0
banks                                        2.5.0
beartype                                     0.22.9
beautifulsoup4                               4.15.0
bidict                                       0.24.1
black                                        26.5.1
blinker                                      1.9.0
cachetools                                   7.1.7
caio                                         0.12.2
certifi                                      2026.7.22
cffi                                         2.1.1
charset-normalizer                           3.5.1
claude-agent-sdk                             0.2.139
click                                        8.5.0
colorama                                     0.4.6
contourpy                                    1.3.3
cryptography                                 50.0.1
cycler                                       0.12.1
dataclasses-json                             0.6.7
daytona                                      0.205.0
daytona_analytics_api_client                 0.205.0
daytona_analytics_api_client_async           0.205.0
daytona_api_client                           0.205.0
daytona_api_client_async                     0.205.0
Thinking…

No "oleander" product in the environment. The npm package oleander@0.0.1 is an empty placeholder package by some user. Let me check for anything else — maybe a hosted product with docs at oleander.ai or similar? But I shouldn't spend too long. Let me check web search ability — probably no network browsing beyond curl. Let me try a couple of quick checks.

timeout 20 curl -s -o /dev/null -w "%{http_code}\n" https://oleander.dev https://oleander.ai https://oleander.io 2>&1; echo ---; pip list 2>/dev/null | grep -i oleander; ls /sandbox; ls ~ 2>/dev/null
<script src="//img1.wsimg.com/blobby/go/a064ffd8-ba2b-45bc-a22e-4cf031c5fe36/gpub/d709d3f753884fb2/script.js" crossorigin></script>
<script src="//img1.wsimg.com/blobby/go/a064ffd8-ba2b-45bc-a22e-4cf031c5fe36/gpub/d709d3f753884fb2/script.js" crossorigin></script>
<script src="//img1.wsimg.com/ceph-p3-01/website-builder-data-prod/static/widgets/UX.4.49.1.js" crossorigin></script>
<script src="//img1.wsimg.com/blobby/go/a064ffd8-ba2b-45bc-a22e-4cf031c5fe36/gpub/cf99bc781b52661d/script.js" crossorigin></script>
<script defer src="//img1.wsimg.com/signals/js/clients/scc-c2/scc-c2.min.js" crossorigin></script>
<script>"use strict";Core.utils.onAllowCookieTracking(function () {const queryString = window.location.search;const urlParams = new URLSearchParams(queryString);const whiteList = ['gclid', 'fbclid', 'gdan_clid'];const belongToList = list => item => list.includes(item);const belongToWhiteList = belongToList(whiteList);Array.from(urlParams).forEach(param => {const [queryKey, queryResult] = param;if (!belongToWhiteList(queryKey)) return;localStorage.setItem(queryKey, queryResult);});});</script></body></html>200
<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta name="description" content="">
    <meta name="author" content="">

    <title>Linus Oleander's Personal Homepage</title>

    <!-- Bootstrap Core CSS -->
    <link rel="stylesheet" href="css/bootstrap.min.css" type="text/css">

    <!-- Custom Fonts -->
    <link href='http://fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,800italic,400,300,600,700,800' rel='stylesheet' type='text/css'>
    <link href='http://fonts.googleapis.com/css?family=Merriweather:400,300,300italic,400italic,700,700italic,900,900italic' rel='stylesheet' type='text/css'>
    <link rel="stylesheet" href="font-awesome/css/font-awesome.min.css" type="text/css">
    <link rel="stylesheet" href="css/animate.min.css" type="text/css">
    <link rel="stylesheet" href="css/creative.css" type="text/css">
    <link rel="stylesheet" href="css/custom.css" type="text/css">

    <!-- HTML5 Shim and Respond.js IE8 support of HTML5 elements and media queries -->
    <!-- WARNING: Respond.js doesn't work if you view the page via file:// -->
    <!--[if lt IE 9]>
        <script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
        <script src="https://oss.maxcdn.com/libs/respond.js/1.4.2/respond.min.js"></script>
    <![endif]-->
</head>

<body id="page-top">

    <header>
        <div class="header-content">
            <div class="header-content-inner">
                <h1>Hi there, I'm Linus</h1>
                <hr style="opacity: 0">
                <p>I like to build stuff, dive, compete, travel and solve strange problems</p>
            </div>
        </div>
    </header>

    <section class="bg-primary" id="about">
        <div class="container">
            <div class="row">
                <div class="col-lg-8 col-lg-offset-2 text-center">
                    <div id="avatar"></div>
                    <p class="text-faded">
                        I'm a 28 year old developer, long distance triathlete and adrenaline junkie from Gothenburg, Sweden.
                        I'm the founder of
                        <a href="http://radiofy.se" class="normal">Radiofy</a> and co-founder of <a class="normal" href="http://hprovet.se">HProvet</a>. Scroll down for more information.
                    </p>
                </div>
            </div>
        </div>
    </section>

    <section id="services">
        <div class="container">
            <div class="row">
                <div class="col-lg-12 text-center">
                    <h2 class="section-heading">Project highlights</h2>
                    <hr class="primary">
                </div>
            </div>
        </div>
        <div class="container">
            <div class="row">
                <div class="col-lg-3 col-md-6 text-center">
                    <div class="service-box">
                        <i class="fa fa-4x fa-music wow bounceIn text-primary"></i>
                        <h3><a href="http://radiofy.se" target="_blank">Radiofy</a></h3>
                        <p class="text-muted">A digital bridge between ~ 400 radio stations and Spotify</p>
                    </div>
                </div>
                <div class="col-lg-3 col-md-6 text-center">
                    <div class="service-box">
                        <i class="fa fa-4x fa-book wow bounceIn text-primary" data-wow-delay=".1s"></i>
                        <h3><a href="http://hprovet.se" target="_blank">HProvet</a></h3>
                        <p class="text-muted">An interactive platform used to studdy for the Swedish SAT</p>
                    </div>
                </div>
                <div class="col-lg-3 col-md-6 text-center">
                    <div class="service-box">
                        <i class="fa fa-4x fa-git wow bounceIn text-primary" data-wow-delay=".2s"></i>
                        <h3><a href="https://github.com/oleander/git-fame-rb" target="_blank">git fame</a></h3>
                        <p class="text-muted">A command line tool used to generate stats from a git repository</p>
                    </div>
                </div>
                <div class="col-lg-3 col-md-6 text-center">
                    <div class="service-box">
                        <i class="fa fa-4x fa-film wow bounceIn text-primary" data-wow-delay=".3s"></i>
                        <h3><a href="https://github.com/oleander/show-time" target="_blank">ShowTime</a></h3>
                        <p class="text-muted">A torrent desktop client for Trakt.tv with live updates from the web</p>
                    </div>
                </div>
            </div>
        </div>
    </section>

    <section id="services">
        <div class="container">
            <div class="row">
                <div class="col-lg-12 text-center">
                    <h2 class="section-heading">Want more?</h2>
                    <hr class="primary">
                </div>
            </div>
        </div>
        <div class="container">
            <div class="row">
                <div class="col-lg-3 col-md-6 text-center">
                    <div class="service-box">
                        <i class="fa fa-4x fa-github wow bounceIn text-primary"></i>
                        <h3><a href="http://github.com/oleander" target="_blank">Github</a></h3>
                        <p class="text-muted">I've published some awesome OSS projects over the years. Have a look!</p>
                    </div>
                </div>
                <div class="col-lg-3 col-md-6 text-center">
                    <div class="service-box">
                        <i class="fa fa-4x fa-twitter wow bounceIn text-primary" data-wow-delay=".1s"></i>
                        <h3><a href="https://twitter.com/linusoleander" target="_blank">Twitter</a></h3>
                        <p class="text-muted">My live feed updated with the latest news.</p>
                    </div>
                </div>
                <div class="col-lg-3 col-md-6 text-center">
                    <div class="service-box">
                        <i class="fa fa-4x fa-diamond wow bounceIn text-primary" data-wow-delay=".2s"></i>
                        <h3><a href="https://rubygems.org/profiles/48444" target="_blank">Rubygems</a></h3>
                        <p class="text-muted">Take a look at my published ruby gems downloaded over 250k times.</p>
                    </div>
                </div>
                <div class="col-lg-3 col-md-6 text-center">
                    <div class="service-box">
                        <i class="fa fa-4x fa-stack-overflow wow bounceIn text-primary" data-wow-delay=".3s"></i>
                        <h3><a href="http://stackoverflow.com/users/560073/oleander" target="_blank">Stack Overflow</a></h3>
                        <p class="text-muted">I help if I can. Watch my contributions on Stack Overflow.</p>
                    </div>
                </div>
            </div>
        </div>
    </section>

    <section class="no-padding" id="portfolio">
        <div class="container-fluid">
            <div class="row no-gutter">
                <div class="col-lg-4 col-sm-6">
                    <a class="portfolio-box">
                        <img src="img/portfolio/1.png" class="img-responsive" alt="Linus Oleander, Celtman 2015">
                        <div class="portfolio-box-caption">
                            <div class="portfolio-box-caption-content">
                                <div class="project-category text-faded">
                                    Celtman
                                </div>
                                <div class="project-name">
                                    2015
                                </div>
                            </div>
                        </div>
                    </a>
                </div>
                <div class="col-lg-4 col-sm-6">
                    <a class="portfolio-box">
                        <img src="img/portfolio/2.png" class="img-responsive" alt="Öloppet">
                        <div class="portfolio-box-caption">
                            <div class="portfolio-box-caption-content">
                                <div class="project-category text-faded">
                                    Öloppet
                                </div>
                                <div class="project-name">
                                    2015
                                </div>
                            </div>
                        </div>
                    </a>
                </div>
                <div class="col-lg-4 col-sm-6">
                    <a class="portfolio-box">
                        <img src="img/portfolio/3.png" class="img-responsive" alt="Linus Oleander, Anna Oleander, Rockman 2015">
                        <div class="portfolio-box-caption">
                            <div class="portfolio-box-caption-content">
                                <div class="project-category text-faded">
                                    Rockman
                                </div>
                                <div class="project-name">
                                    2015
                                </div>
                            </div>
                        </div>
                    </a>
                </div>
                <div class="col-lg-4 col-sm-6">
                    <a class="portfolio-box">
                        <img src="img/portfolio/4.png" class="img-responsive" alt="Linus Oleander, Celtman 2015">
                        <div class="portfolio-box-caption">
                            <div class="portfolio-box-caption-content">
                                <div class="project-category text-faded">
                                    Rockman
                                </div>
                                <div class="project-name">
                                    2015
                                </div>
                            </div>
                        </div>
                    </a>
                </div>
                <div class="col-lg-4 col-sm-6">
                    <a class="portfolio-box">
                        <img src="img/portfolio/5.png" class="img-responsive" alt="Linus Oleander, Anna Oleander, Rockman 2015">
                        <div class="portfolio-box-caption">
                            <div class="portfolio-box-caption-content">
                                <div class="project-category text-faded">
                                    Rockman
                                </div>
                                <div class="project-name">
                                    2015
                                </div>
                            </div>
                        </div>
                    </a>
                </div>
                <div class="col-lg-4 col-sm-6">
                    <a class="portfolio-box">
                        <img src="img/portfolio/6.png" class="img-responsive" alt="Linus Oleander, Norseman 2015">
                        <div class="portfolio-box-caption">
                            <div class="portfolio-box-caption-content">
                                <div class="project-category text-faded">
                                    Norseman
                                </div>
                                <div class="project-name">
                                    2014
                                </div>
                            </div>
                        </div>
                    </a>
                </div>
            </div>
        </div>
    </section>
    <section id="contact">
        <div class="container">
            <div class="row" style="margin-bottom: 50px">
                <div class="col-lg-8 col-lg-offset-2 text-center">
                    <h2 class="section-heading">Let's Get In Touch!</h2>
                </div>
            </div>
            <div class="row">
                <div class="col-lg-offset-3  col-lg-2 text-center">
                    <p><a href="mailto:linus[a]oleander[dot]io">
                        <i class="fa fa-envelope fa-3x wow bounceIn" data-wow-delay=".1s"></i>
                    </a></p>
                </div>
                <div class="col-lg-2 text-center">
                    <p><a href="https://twitter.com/linusoleander" target="_blank">
                        <i class="fa fa-twitter-square fa-3x wow bounceIn" data-wow-delay=".1s"></i>
                    </a></p>
                </div>
                <div class="col-lg-2 text-center">
                    <p><a href="https://github.com/oleander" target="_blank">
                        <i class="fa fa-github-square fa-3x wow bounceIn" data-wow-delay=".1s"></i>
                    </a></p>
                </div>
            </div>

        </div>
    </section>

    <!-- jQuery -->
    <script src="js/jquery.js"></script>

    <!-- Bootstrap Core JavaScript -->
    <script src="js/bootstrap.min.js"></script>

    <!-- Plugin JavaScript -->
    <script src="js/jquery.easing.min.js"></script>
    <script src="js/jquery.fittext.js"></script>
    <script src="js/wow.min.js"></script>

    <!-- Custom Theme JavaScript -->
    <script src="js/creative.js"></script>
</body>
</html>
200
---
repo
repo

[Showing lines 656-947 of 947 (50.0KB limit). Full output: /tmp/pi-bash-1ae3671e8d429b8b.log]
timeout 25 curl -s "https://duckduckgo.com/html/?q=oleander+api+developer+pricing+SDK" 2>&1 | head -c 800; echo; echo "=== npm pack info:"; timeout 20 curl -s https://registry.npmjs.org/oleander | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('description'), d.get('time',{}).get('created'), list(d['versions'].keys()))"
<html> 
<html>
<head><title>302 Found</title></head>
<body>
<center><h1>302 Found</h1></center>
<hr><center>nginx</center>
</body>
</html>

=== npm pack info:
None 2022-02-13T10:51:54.411Z ['0.0.1']
Thinking…

No product called "oleander" exists as a hosted developer product. oleander.dev is a parked domain (GoDaddy), oleander.ai is a personal homepage, oleander.io? The npm package is an empty placeholder. No SDK, no API, no docs, no credentials in env.

Per instructions: "If this product has no developer workflow you can act on, say so plainly and stop." I should stop and report. Let me do a couple more quick checks (GitHub org, rubygems) to be thorough but brief.

timeout 20 curl -s "https://api.github.com/search/repositories?q=oleander&per_page=5" | python3 -c "import json,sys;d=json.load(sys.stdin);[print(r['full_name'],'|',r['description']) for r in d.get('items',[])]" 2>&1; echo "=== rubygems:"; timeout 20 curl -s -o /dev/null -w "%{http_code}\n" https://rubygems.org/api/v1/gems/oleander.json; echo "=== crates:"; timeout 20 curl -s -o /dev/null -w "%{http_code}\n" https://crates.io/api/v1/crates/oleander
Blake-Madden/OleanderStemmingLibrary | Porter stemming library (C++)
Blake-Madden/OleanderStemmingLibrary | Porter stemming library (C++)
squito/oleander | JVM data structures that know how to live right in a byte array
landrs-toolkit/NN-Oleander-Detection | NN based Oleander Detection From Drone Imagery
OleanderHQ/claude-plugin | oleander claude plugin: skills, rules, and MCP.
OleanderHQ/codex-plugin | oleander codex plugin: skills, rules, and MCP.
=== rubygems:
404
=== crates:
403
Thinking…

There is an "OleanderHQ" GitHub org with claude-plugin and codex-plugin repos. Let's inspect the org — maybe there's a hosted product "oleander". Let's check repos list and README.

timeout 20 curl -s "https://api.github.com/orgs/OleanderHQ/repos?per_page=50" | python3 -c "import json,sys;d=json.load(sys.stdin);[print(r['name'],'|',r['description'],'|',r['homepage']) for r in d]" 2>&1; echo "=== user:"; timeout 20 curl -s "https://api.github.com/users/OleanderHQ" | python3 -c "import json,sys;d=json.load(sys.stdin);print(d.get('name'),d.get('blog'),d.get('bio'),d.get('public_repos'))"
assets | Assets | None
assets | Assets | None
tutorials | Tutorials for https://oleander.dev | None
homebrew-tap | Homebrew formulae for oleander tools. | 
ducklake-spark | Ducklake SparkCatalog implementation. | None
s3tables-emr-serverless-cdk | CDK stacks for s3tables iceberg catalog and EMR Serverless. | None
setup-oleander-cli | Github action for oleander-cli setup. | None
skills | Agent skills for understanding and working with oleander. | 
pyspark-template | Oleander PySpark template repository | None
iceberg-spark-101-tutorials | Example code repository for Apache Iceberg & Spark 101 tutorial. | None
claude-plugin | oleander claude plugin: skills, rules, and MCP. | None
codex-plugin | oleander codex plugin: skills, rules, and MCP. | None
v0-template | v0 starter for oleander: lake query playground, agent skills, one-click Vercel deploy. | https://oleander.dev
eve-agent-with-oleander | A minimal template for building an eve agent using oleander, a multi-engine data warehouse. | https://vercel.com/marketplace/oleander
=== user:
None https://oleander.dev Data Observability. Simplified. Powered by OpenLineage and Marquez. 13
Thinking…

So oleander.dev is a hosted product: "Data Observability. Simplified. Powered by OpenLineage and Marquez" — a multi-engine data warehouse / lake query. There's a skills repo: "Agent skills for understanding and working with oleander." Let me read the tutorials repo and skills repo README to find the quickstart and whether it needs local services.

Note earlier curl of https://oleander.dev returned a GoDaddy parked page? Actually the first output was oleander.dev giving GoDaddy scripts... hmm, the outputs were concatenated in odd order. The first curl output with GoDaddy scripts was for oleander.dev maybe (parked). Let me check each explicitly.

Let me fetch the skills repo and tutorials.

for d in oleander.dev oleander.ai oleander.io app.oleander.dev docs.oleander.dev api.oleander.dev; do printf "%s -> " $d; timeout 12 curl -sL -o /dev/null -w "%{http_code} %{url_effective}\n" https://$d; done
Failedoleander.dev -> 200 https://oleander.dev/
oleander.dev -> 200 https://oleander.dev/
oleander.ai -> 200 https://oleander.ai/
oleander.io -> 200 https://oleander.io/
app.oleander.dev -> 000 https://app.oleander.dev/
docs.oleander.dev -> 200 https://docs.oleander.dev/quickstart
api.oleander.dev -> 000 https://api.oleander.dev/


Command exited with code 6
cd /tmp && timeout 30 curl -sL https://api.github.com/repos/OleanderHQ/skills/readme -H "Accept: application/vnd.github.raw" | head -200
# [`oleander`](https://oleander.dev/) Skills
# [`oleander`](https://oleander.dev/) Skills

A collection of [agent skills](https://agentskills.io/home) for building with [oleander](https://oleander.dev/).

[Browse on skills.sh](https://skills.sh/oleanderhq/skills)

## Install

```bash
npx skills add OleanderHQ/skills -g -y
```

## Skills

| Skill | Use when |
| --- | --- |
| [`lake-query`](skills/lake-query/SKILL.md) | Querying lake tables, writing query results to a table, or handling engine routing and billing errors |
| [`lake-catalog`](skills/lake-catalog/SKILL.md) | Naming tables, choosing namespaces, or referencing the lake catalog |
| [`polars-submit`](skills/polars-submit/SKILL.md) | Running Polars via the CLI (query/script, local/distributed, `--save`) |
| [`spark-lake-catalog`](skills/spark-lake-catalog/SKILL.md) | Reading or writing Iceberg tables from Spark jobs |
| [`spark-lineage`](skills/spark-lineage/SKILL.md) | Fixing disconnected OpenLineage or avoiding `collect()` between read and write |
| [`spark-submit`](skills/spark-submit/SKILL.md) | Submitting, monitoring, or automating Spark jobs (MCP, CLI, SDK) |
| [`spark-best-practices`](skills/spark-best-practices/SKILL.md) | Optimizing or reviewing general Spark DataFrame jobs |

### Former skill names

These older skill IDs were renamed. Prefer the current names above:

| Former | Current |
| --- | --- |
| `oleander-spark-lineage` | `spark-lineage` |
| `oleander-spark-submit` | `spark-submit` |
| `oleander-iceberg-catalog` | `lake-catalog` / `spark-lake-catalog` |
Thinking…

docs.oleander.dev/quickstart exists. Let me fetch it and the pricing info. Also the skills SKILL.md files for lake-query and spark-submit — they'll tell me about SDK/CLI/MCP and API keys.

timeout 30 curl -sL https://docs.oleander.dev/quickstart | python3 -c "
import sys,re,html
t=sys.stdin.read()
t=re.sub(r'(?s)<(script|style).*?</\1>','',t)
t=re.sub(r'<[^>]+>',' ',t)
t=html.unescape(t)
t=re.sub(r'\n\s*\n+','\n',t)
print(t[:6000])"
Quickstart - oleander Documentation Index Fetch the complete documentation index at: /llms.txt Use t
               Quickstart - oleander                                         Documentation Index  Fetch the complete documentation index at:   /llms.txt   Use this file to discover all available pages before exploring further.    Skip to main content              oleander  home page                 Search...   ⌘ K         Support      oleander.dev         oleander.dev                                                        Search...              Navigation             Getting Started       Quickstart         Documentation      API Reference      SDKs                        Slack        Blog       Getting Started         Quickstart          About          Architecture           Platform        Compute              Storage              Observability              Query routing              Settings                IAM         Overview          Principals          Roles          Permissions          API keys          Resources and actions           Connections         Postgres          MySQL          MongoDB          BigQuery          Snowflake           Integrations         Streamkap          ClickHouse           Coding with agents         Overview         Setup                CLI         Intro          Spark          Lake          Polars          Env          Queries           External Compute         Spark          Airflow          dbt          OpenLineage                                        On this page       Step 1: Connect Your Agent    Step 2: Connect Your Data    Step 3: Ask Your Question    Take It Further              Getting Started   Quickstart            Copy page  Copy page               Connect an agent to oleander, upload or connect your data, and ask your first question in minutes.             Copy page  Copy page              We’ll connect your agent, authenticate, and ask your first question. 
         Need an account?  Sign up at oleander.dev .   
   ​           Step 1: Connect Your Agent  
 Use the oleander plugin in Claude to query your data, upload files, or schedule daily reports. 
      Claude Cowork      Claude Code            1     Add plugin marketplace   Open  Cowork  →  Customize  →  +  →  Add marketplace from GitHub .  Paste  https://github.com/OleanderHQ/claude-plugin  (or  OleanderHQ/claude-plugin ), then install the oleander plugin.                        2     Add connector   Open  Cowork  →  Customize  →  Plugins  →  Oleander  →  Connectors  →  Connect .                        3     Verify the connection   Ask your agent for a quick connection check:  
 “Are you connected to oleander?” 
  The agent should call  identity_get  and return your organization context.          See  Claude Cowork setup  for scheduled tasks and org-wide rollout.          The  oleander Claude Code Plugin  installs the MCP server into Claude Code.        1     Add plugin marketplace   In Claude Code, add the oleander marketplace and install the plugin:                        /plugin   marketplace   add   OleanderHQ/claude-plugin  
  /plugin   install   oleander@oleander  
          You may need to restart your Claude Code session before the MCP server is available.          2     Authentication   Sign in with your oleander account:                        claude   mcp   login   oleander  
          Or run  /mcp , select  oleander , and choose  Authenticate . Your browser opens to complete the OAuth flow.          3     Verify the connection   Confirm oleander is connected:                        claude   mcp   list  
          You should see  ✓ Connected  for oleander.          See  Claude setup  for skills and manual MCP configuration.          
 Using a different agent? See  Cursor ,  Codex , and  OpenCode  setup. 
   ​           Step 2: Connect Your Data  
 Connect or upload at least one data source so you can start a conversation about it with your agent: 
   Upload a file  : Upload a parquet or CSV file to start querying instantly. No setup needed 
   Connect your warehouse  : For live access to  BigQuery ,  Snowflake ,  Postgres , and Iceberg catalogs, go to  Settings → Lake  
 To try it quickly, download the  sample Iris dataset  and upload it at  oleander.dev/app/upload . 
   ​           Step 3: Ask Your Question  
 Ask your agent in plain English. Through oleander’s MCP server it can list catalogs, run SQL, upload files, and schedule reports. 
  Analytics:  “What’s the average petal length in  default.iris , broken down by species?” 
  Exploratory:  “Explore the iris dataset. What looks unusual across species?” 
 Once you’re comfortable asking questions, try going further: 
 Schedule a daily report with a  Cowork scheduled task  every morning at 8 a.m. ( cron: 0 8 * * * ). 
 Ask for weekly context on what’s new or changed in your data, like tables renamed, updated, or newly uploaded. 
 Run a weekly org wrap on cost trajectory and whether you’re on track for the month’s KPIs. 
         Ask in plain English. oleander handles the query plan and execution behind the scenes so your agent can focus on the answer.   
   ​           Take It Further  
                 Connect Your Warehouse   Query external and lake data through one SQL layer                     Query Your Lake   Upload data and run SQL                     Setup Your Agent   Connect from your editor, terminal, or automation                     Observability   Lineage, traces, and run history in one place          Was this page helpful?           Yes          No           About                               x      github      linkedin         Powered by                    This documentation is built and hosted on Mintlify, a developer documentation platform                

cd /tmp && timeout 30 curl -sL https://api.github.com/repos/OleanderHQ/skills/contents/skills/lake-query/SKILL.md -H "Accept: application/vnd.github.raw" | head -150
---
---
name: lake-query
description: >-
  Runs lake SQL through oleander's query router: query_run for reads,
  query_submit for writes, spark_sql_submit for named Spark jobs. Use when
  querying oleander lake tables, exploring data, writing query results to a
  table, or handling engine routing and billing errors.
---

# Lake Query

oleander routes the query. It parses the SQL, estimates how much data the
referenced tables hold, and picks the engine and machine size to match.
Pick the tool by whether the query changes data — not by how big it is.

| Tool | Use for |
| --- | --- |
| `query_run` | Reads. Rows come back on the call. |
| `query_submit` | Anything that changes data, and reads too large to return interactively. |
| `spark_sql_submit` | Spark jobs needing a durable job name or explicit machine types. |

Leave `engine` as `auto` unless the user asked for a specific one. Every
response carries `engine_decision`; use its `reasons` when telling the
user why a query ran the way it did.

## Reads — `query_run`

```json
{ "sql": "SELECT district, count(*) FROM oleander.default.sf_311 GROUP BY 1" }
```

`query_run` is read-only and enforces it: INSERT, UPDATE, DELETE, MERGE,
CREATE, ALTER, DROP, and TRUNCATE are rejected before the request goes
out. That is what makes its `readOnlyHint` true, so clients can skip the
confirmation prompt. CTAS and RTAS are not supported — pass the SELECT to
`query_submit` with a `destination` instead.

If that rejection fires on a genuine read, a mutating keyword is
appearing somewhere in the text (often inside a string literal). Rewrite
it to avoid the bare keyword.

A read too large to return interactively is not run. It comes back as a
routing or upgrade error naming `query_submit`.

## Writes — `query_submit`

Two shapes go through this tool:

- A SELECT plus a `destination` — the result is written to that table.
- A statement that names its own target (INSERT/UPDATE/DELETE/MERGE/DDL)
  with no `destination`.

```json
{
  "sql": "SELECT * FROM oleander.default.sf_311 WHERE opened >= TIMESTAMP '2026-01-01 00:00:00'",
  "destination": "my_namespace.sf_311_2026",
  "write_mode": "overwrite",
  "confirm": true
}
```

`confirm: true` is required — it is a literal in the schema, not a
boolean, so omitting it fails validation. A SELECT with no `destination`
also fails validation: reads belong in `query_run`.

`destination` is `[catalog.]namespace.table`, defaulting to the
`oleander` catalog. `write_mode` is `overwrite` (default) or `append`,
and applies only to a `destination` write — a statement that names its
own target carries its own semantics.

### Confirming with the user

- **Agent-chosen temporary table** — the user's request to run the query
  is enough. Generate a clearly temporary, unique name in a writable
  namespace, use `overwrite`, and set `confirm: true` without asking.
- **A destination the user named, a table that already holds data, or
  any in-place modification** — confirm the effect first. Never silently
  replace or delete persistent data.

### Polling a submitted write

Which engine the router picked decides whether the write finishes on the
call. `state` says which happened:

- `state: "COMPLETE"` — the write already landed, with `row_count` when
  known. Nothing to poll.
- `state: "SUBMITTED"` — a job is running, `run_id` is returned, and the
  write is **not** visible yet. Poll with `jobs_runs_get`; once the run
  is terminal, sample `output_table` with `query_run` so the user can see
  the result.

`query_submit` never returns result rows in either case.

## Engines

| Engine | Reach | Notes |
| --- | --- | --- |
| `duckdb` | lake tables, telemetry tables, the oleander Iceberg catalog, user-registered Iceberg catalogs, and attached BigQuery / Snowflake / Postgres connections | The only engine reaching non-Iceberg connections. Runs without a card on file. Cannot write to a `destination`. |
| `polars` | oleander Iceberg catalog only | Metered compute, needs a card on file. Writes inline. |
| `bloom` | oleander Iceberg catalog only | Metered compute, needs a card on file. Distributed runs submit a job. |
| `spark` | `query_submit` only | Always asynchronous; never returns rows. |

`query_run` accepts `auto`, `duckdb`, `polars`, `bloom`. `query_submit`
adds `spark`. Setting `engine: "duckdb"` with a `destination` is rejected
up front.

## Size a query before running it

Set `explain: true` on either tool to get the engine, the estimated input
size, and whether the plan allows the run — without running anything or
spending compute. Do this before a query you expect to be large.

`explain` replaces manual pre-sizing for routing. Use
`catalogs_tables_metadata_get` when you need the schema or partition
spec, and `catalogs_tables_size_get` when the user asks how big a table
is — not to decide an engine.

## Billing errors — do not retry

A 402 or 403 from a query tool is a billing decision, not a transient
failure. Retrying the identical query fails identically. Read the
message, tell the user what it asks for, and stop.

| Status | Meaning | Next step |
| --- | --- | --- |
| 403 | The organization is past its credit limit; every query is blocked | Settle billing at [oleander.dev/app/settings/plan](https://oleander.dev/app/settings/plan). No workaround. |
| 402 with `required_plan` | The query needs a higher plan than the org is on | Upgrade, or try a smaller input, or `engine: "duckdb"` for a read. |
| 402 without `required_plan` | `polars` and `bloom` are metered compute and need a card on file | Add a card, or use `engine: "duckdb"`, which runs without one. |

## Timeouts

The MCP query routes allow up to 1800s, and polars and bloom sandboxes
run up to 1700s. The MCP client's own request timeout is the effective
cap — raise it on the client if long queries are being cut off.

## Schema checks

Do not guess column names. Before querying a table for the first time in
a session, run `DESCRIBE <catalog>.<namespace>.<table>` (or a `LIMIT 0`
select) via `query_run`, then write the real query. Prefer
`catalogs_tables_metadata_get` when you also need the partition spec.

On a Binder Error, the "Candidate bindings" list names columns that do
exist — re-check the schema rather than retrying another guess.

DuckDB does not accept the multi-pattern form
`col ILIKE ANY ('%a%', '%b%')`. Use OR-ed `ILIKE` conditions or
`regexp_matches(col, '(?i)a|b')`.

## Telemetry tables
Thinking…

Good. Now let's check pricing docs and the SDK docs. docs.oleander.dev/llms.txt index. Also SDK reference. Check if there's an API key available in env — no OLEANDER_* env vars. So I'd need credentials. Let me check docs for SDK and pricing, and see whether an API key is required (blocking).

Let me fetch /llms.txt and pricing page.

timeout 30 curl -sL https://docs.oleander.dev/llms.txt | head -120
# oleander
# oleander

- [Quickstart](https://docs.oleander.dev/quickstart.md): Connect an agent to oleander, upload or connect your data, and ask your first question in minutes.
- [Introduction](https://docs.oleander.dev/introduction.md): The agent-first data lake.
- [Architecture](https://docs.oleander.dev/architecture.md): Learn how your data stack connects to oleander through OpenLineage and OpenTelemetry, and how telemetry builds the context graph.
- [Bloom](https://docs.oleander.dev/platform/compute/bloom.md): oleander's own SQL engine: Apache DataFusion over Iceberg, running local on a sandbox or distributed across workers.
- [Jev functions](https://docs.oleander.dev/platform/compute/bloom/functions/jev.md): Batch named questions or return typed answers from TypeSafe’s Jev model in Bloom SQL.
- [DuckDB](https://docs.oleander.dev/platform/compute/duckdb.md): The interactive engine for mutations, external connections, and foreign catalogs.
- [Polars](https://docs.oleander.dev/platform/compute/polars.md): Run Polars SQL queries and Python scripts against your Iceberg lake.
- [Jobs](https://docs.oleander.dev/platform/compute/spark.md): Run and manage your Spark artifacts and jobs with oleander
- [Tasks](https://docs.oleander.dev/platform/compute/tasks.md): Interactive Python and TypeScript environments with pre-wired lake access.
- [Catalogs](https://docs.oleander.dev/platform/storage/catalogs.md): Every organization gets a private Iceberg catalog with namespaces for user data and telemetry.
- [Tables](https://docs.oleander.dev/platform/storage/tables.md): Create and query tables in your private Iceberg catalog.
- [Observability](https://docs.oleander.dev/platform/observability/overview.md): Full visibility into your data pipelines - lineage, traces, logs, and automated investigations.
- [Lineage](https://docs.oleander.dev/platform/observability/lineage/overview.md): Unified API for lineage metadata interoperability.
- [Alerts](https://docs.oleander.dev/platform/observability/alerts.md): Automatic failure detection and metric anomaly detection for your pipelines.
- [Chat](https://docs.oleander.dev/platform/observability/chat.md): Investigate pipelines, trace lineage, and query your lake in plain English.
- [Query routing](https://docs.oleander.dev/platform/query-routing/overview.md): One endpoint for every query. oleander parses the SQL, estimates the input, and picks the engine and machine size for you.
- [Transpilation](https://docs.oleander.dev/platform/query-routing/transpilation.md): Dialect detection, engine badges, and SQL rewrites across DuckDB, Bloom, Spark, and Polars.
- [Integrations](https://docs.oleander.dev/platform/settings/integrations.md): Connect OpenLineage producers to oleander for automatic lineage tracking.
- [Environment](https://docs.oleander.dev/platform/settings/environment.md): Store API keys, tokens, and config securely for your organization.
- [Webhooks](https://docs.oleander.dev/platform/settings/webhooks.md): Learn how to set up webhooks and use them to forward OpenLineage events.
- [Audit logs](https://docs.oleander.dev/platform/settings/audit-logs.md): Every authenticated API request in your organization, with who made it, how they authenticated, and what came back.
- [Overview](https://docs.oleander.dev/iam/overview.md): Control who can use compute, access data, and administer your organization.
- [Principals](https://docs.oleander.dev/iam/principals.md): Human, Application, and Agent identities, including the system-managed OleanderSystem principal.
- [Roles](https://docs.oleander.dev/iam/roles.md): Group permissions into custom roles or use oleander’s system-managed roles.
- [Permissions](https://docs.oleander.dev/iam/permissions.md): Define allowed actions, choose their scope, and delegate access through roles.
- [API keys](https://docs.oleander.dev/platform/settings/api-keys.md): Authenticate as a principal and manage personal, application, and agent API keys.
- [Resources and actions](https://docs.oleander.dev/iam/resources-and-actions.md): The complete reference for resource types, scopes, and permission actions.
- [Postgres](https://docs.oleander.dev/connections/postgres.md): Query a live Postgres database from the lake, and import tables into Iceberg with a parallel, snapshot-consistent read.
- [MySQL](https://docs.oleander.dev/connections/mysql.md): Query a live MySQL database from the lake, and import tables into Iceberg with a parallel read once or on a schedule.
- [MongoDB](https://docs.oleander.dev/connections/mongodb.md): Query a live MongoDB database from the lake, and import collections into Iceberg once or on a schedule.
- [BigQuery](https://docs.oleander.dev/connections/bigquery.md): Attach a Google Cloud project and query BigQuery tables alongside your Iceberg lake.
- [Snowflake](https://docs.oleander.dev/connections/snowflake.md): Query Snowflake tables from the lake, or register Snowflake Horizon as an Iceberg catalog.
- [Streamkap](https://docs.oleander.dev/integrations/streamkap.md): Land CDC tables in your oleander Iceberg catalog with a Streamkap destination.
- [ClickHouse](https://docs.oleander.dev/integrations/clickhouse.md): Query your oleander Iceberg catalog from ClickHouse with a DataLakeCatalog database.
- [Coding with agents](https://docs.oleander.dev/mcp/introduction.md): Give your coding agent access to your lake, pipelines, and lineage through the oleander MCP server and CLI.
- [Claude](https://docs.oleander.dev/mcp/claude.md): Install the oleander plugin and MCP server in Claude Code and Claude Cowork
- [OpenAI Codex](https://docs.oleander.dev/mcp/codex.md): Configure the oleander MCP server in OpenAI Codex
- [Cursor](https://docs.oleander.dev/mcp/cursor.md): Configure the oleander MCP server in Cursor
- [OpenCode](https://docs.oleander.dev/mcp/opencode.md): Configure the oleander MCP server in OpenCode
- [MCP Tools Reference](https://docs.oleander.dev/mcp/protocol.md): All 50 tools exposed by the oleander MCP server.
- [Intro](https://docs.oleander.dev/cli/introduction.md): Install and configure the oleander CLI to manage Spark jobs, query the lake, manage catalogs and tables, handle environment variables, and save queries from your terminal.
- [Spark](https://docs.oleander.dev/cli/spark.md): Initialize workspaces, upload artifacts, submit jobs, and register clusters from the CLI.
- [Lake](https://docs.oleander.dev/cli/lake.md): Query the lake, explore catalogs, register catalogs, and launch a DuckDB terminal from the CLI.
- [Polars](https://docs.oleander.dev/cli/polars.md): Run Polars workloads against your lake - SQL queries or Python scripts - from the CLI.
- [Env](https://docs.oleander.dev/cli/env.md): Manage organization-level environment variables from the CLI.
- [Queries](https://docs.oleander.dev/cli/queries.md): Save, retrieve, and manage named SQL queries from the CLI.
- [Spark](https://docs.oleander.dev/integrations/spark.md): Configure oleander with Apache Spark
- [Airflow](https://docs.oleander.dev/integrations/airflow.md): Configure oleander with Apache Airflow
- [dbt](https://docs.oleander.dev/integrations/dbt.md): Configure oleander with dbt
- [OpenLineage producers](https://docs.oleander.dev/build-deploy.md): Connect any OpenLineage-compatible tool to oleander for automatic lineage tracking.
- [API Reference](https://docs.oleander.dev/api-reference/introduction.md): REST API for ingesting lineage events and querying the oleander lake.
- [Record event](https://docs.oleander.dev/api-reference/record-event.md): Submit an OpenLineage compliant event to record lineage metadata. This is the primary endpoint for ingesting lineage data from your pipelines and integrations.
- [Retrieve events](https://docs.oleander.dev/api-reference/retrieve-events.md): List lineage events. Supports filtering by time range, run, state, namespace, job, and integrations. Results can be paginated and sorted.
- [Query (routed)](https://docs.oleander.dev/api-reference/query-routed.md): The unified query endpoint. oleander parses the SQL, estimates how much data the referenced tables hold, and picks the engine (DuckDB, Polars, Bloom, or Spark) and machine size to match. Leave `engine` on `auto` unless you need a specific one.
- [DuckDB (legacy)](https://docs.oleander.dev/api-reference/duckdb-legacy.md): Legacy endpoint. Executes SQL against the oleander lake, always on DuckDB, sized by the organization's default sandbox setting rather than by the query. Prefer POST /api/v1/query, which routes to the right engine and machine; use this only for autoSaveByHash. All queries capture lineage metadata aut…
- [Spark](https://docs.oleander.dev/api-reference/spark.md): Execute a SQL query against the oleander lake using managed Spark. The query runs as a named job in the specified namespace. Results are written to `output_table` as an Iceberg table. Lineage is captured automatically for every run.
- [Polars](https://docs.oleander.dev/api-reference/polars.md): Execute a Polars workload against your Iceberg lake tables. Supports two modes: **query** (Polars SQL run against registered tables) and **script** (user-authored Python that assigns `result` to a LazyFrame or DataFrame). Workloads run in an isolated sandbox; pass `distributed: true` to offload exec…
- [Intro](https://docs.oleander.dev/sdk/typescript/introduction.md): Use the oleander API from TypeScript: query the lake, inspect Spark clusters, and submit Spark jobs.
- [Query](https://docs.oleander.dev/sdk/typescript/query.md): Run and submit queries through the oleander query router.
- [Spark Jobs](https://docs.oleander.dev/sdk/typescript/spark-jobs.md): Inspect Spark clusters, upload and list artifacts, submit jobs, and monitor runs.
- [Spark SQL](https://docs.oleander.dev/sdk/typescript/spark-sql.md): Submit Spark SQL queries that write results to Iceberg tables.
- [Polars](https://docs.oleander.dev/sdk/typescript/polars.md): Run Polars SQL queries or Python scripts over lake tables.
- [Catalogs](https://docs.oleander.dev/sdk/typescript/catalogs.md): Browse Iceberg catalogs, namespaces, and tables, and inspect table metadata, schemas, and sizes.
- [Environment Variables](https://docs.oleander.dev/sdk/typescript/environment-variables.md): Manage organization environment variables available to Spark jobs and scripts.
- [Intro](https://docs.oleander.dev/sdk/python/introduction.md): Use the oleander API from Python: query the lake, inspect Spark clusters, and submit Spark jobs.
- [Query](https://docs.oleander.dev/sdk/python/query.md): Run and submit queries through the oleander query router.
- [Spark Jobs](https://docs.oleander.dev/sdk/python/spark-jobs.md): Inspect Spark clusters, list uploaded artifacts, submit jobs, and monitor runs.
- [Spark SQL](https://docs.oleander.dev/sdk/python/spark-sql.md): Submit Spark SQL queries that write results to Iceberg tables.
- [Polars](https://docs.oleander.dev/sdk/python/polars.md): Run Polars SQL queries or Python scripts over lake tables.
- [Catalogs](https://docs.oleander.dev/sdk/python/catalogs.md): Browse Iceberg catalogs, namespaces, and tables, and inspect table metadata, schemas, and sizes.
- [Environment Variables](https://docs.oleander.dev/sdk/python/environment-variables.md): Manage organization environment variables available to Spark jobs and scripts.

## OpenAPI Specs

- [openapi](/api-reference/openapi.json)

## Optional

- [Slack](https://join.slack.com/t/oleander-hq/shared_invite/zt-2wzl5ncjb-c~ZubVAHVzBP7OZM~Hwuyw)
- [Blog](https://oleander.dev/blog)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.
timeout 30 curl -sL https://oleander.dev/pricing | python3 -c "
import sys,re,html
t=sys.stdin.read(); t=re.sub(r'(?s)<(script|style).*?</\1>','',t); t=re.sub(r'<[^>]+>',' ',t); t=html.unescape(t); t=re.sub(r'[ \t]+',' ',t); t=re.sub(r'\n\s*\n+','\n',t); print(t[:5000])"
Pricing | oleander oleander Product Resources Blog Pricing Docs Pricing Blog Pricing // Plans Hobby $0 / month Free forever DuckDB plus limited Spark Queries u
 Pricing | oleander oleander Product Resources Blog Pricing Docs Pricing Blog Pricing // Plans Hobby $0 / month Free forever DuckDB plus limited Spark Queries up to 4 GiB Compute billed per second of query time 5 GB storage 7 day retention Investigations, root cause analysis, anomaly detection @oleander Slack app for alerts and investigations Community support on Slack Pro $300 / month or $3,000 billed annually (save 17 %) Everything in Hobby DuckDB , Polars , Bloom , and full Spark Queries up to 50 GiB Storage at $0.0276 per GB per month 30 day retention SQL query API and MCP org tokens Shared Slack channel Pro++ $1,800 / month or $18,000 billed annually (save 17 %) Everything in Pro Distributed Bloom clusters Autoscaled clusters up to 10 workers No query size limit Bring your own S3 bucket, no storage markup 12 month retention Dedicated Slack channel Enterprise Custom Annual contract Everything in Pro++ Custom precached images tuned for your workloads Custom metadata retention policy Custom OpenLineage integrations Bring your own cloud Premium support with SLA // Feature Matrix Feature Hobby Pro Pro++ Enterprise Query engines DuckDB, limited Spark DuckDB, Polars, Bloom, Spark with distributed Bloom & Polars All, custom Distributed compute None None Up to 10 workers Custom Precached images Standard Standard Standard Tuned to your workloads Maximum query input 4 GiB 50 GiB Unlimited Unlimited Interactive compute 2 vCPU Up to 32 vCPU Up to 32 vCPU Custom Lake queries Unlimited Unlimited Unlimited Unlimited Storage 5 GB $0.0276/GB/mo Your bucket, no markup Your bucket or cloud Retention 7 days 30 days 12 months Custom Upload size maximum Unlimited Unlimited Unlimited Unlimited Private datasets Yes Yes Yes Yes SQL query API No Yes Yes Yes AI query assist Limited Yes Yes Yes Upload limits reflect maximum single-file sizes. Queries above a plan's maximum input are routed to distributed compute, which requires Pro++. // Spark Per sec Per hour Spark resource pricing ( per second ) vCPU: $ 0.0000175 / sec GB RAM: $ 0.0000019 / sec Machine Type Class vCPU GB RAM spark.1.c Compute 1 2 spark.2.c Compute 2 4 spark.4.c Compute 4 8 spark.8.c Compute 8 16 spark.16.c Compute 16 32 spark.1.b Balanced 1 4 spark.2.b Balanced 2 8 spark.4.b Balanced 4 16 spark.8.b Balanced 8 32 spark.16.b Balanced 16 64 spark.1.m Memory 1 8 spark.2.m Memory 2 16 spark.4.m Memory 4 30 spark.8.m Memory 8 60 spark.16.m Memory 16 120 You choose the driver machine type, executor machine type, and executor count. All running resources are included in billing. // Lake vCPU GB RAM Cost/ sec 2 4 $0.00085 4 8 $0.0017 8 16 $0.0034 16 32 $0.0068 32 64 $0.01 Compute is billed per second of active query time, from the first second. Queries themselves are unlimited on every plan, and there is no charge for starting or stopping compute. // Storage Storage Type Description Cost/GB/month Private storage Private lake storage, included on Pro++ with your own bucket $ 0.0276 Storage is billed based on the amount of data stored per month. // Contact Sales Interested? Terms · Privacy · Startups · Made with ❤️ in SF 🌁 © 2026 oleander. All rights reserved. Flower power active. System theme Light theme Dark theme
Thinking…

Now, can I actually act? I need credentials (API key). No OLEANDER_API_KEY in env. Let me check the SDK docs (Python) for auth and whether there's a free tier path without card. Without an API key I can't hit the hosted API. But maybe the API allows signup? No — signing up would require an account/browser OAuth.

Let me check docs for API keys page and Python SDK intro to see auth mechanism and env var name. Then determine blocked status.

Let's also check if maybe there's a token in the environment under a different name, or a config file (~/.oleander).

timeout 30 curl -sL https://docs.oleander.dev/sdk/python/introduction.md; echo "=== QUERY:"; timeout 30 curl -sL https://docs.oleander.dev/sdk/python/query.md | head -80
> ## Documentation Index
> ## 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.

# Intro

> Use the oleander API from Python: query the lake, inspect Spark clusters, and submit Spark jobs.

The [`oleanderhq-sdk`](https://pypi.org/project/oleanderhq-sdk/) package provides an async client for the oleander API. It covers [routed queries](/sdk/python/query), Spark job management, Spark SQL, Polars runs, catalog introspection, environment variables, Spark cluster lookup, and run polling.

## Installation

```bash theme={null}
pip install oleanderhq-sdk
```

## Authentication

Create an API key in your [oleander settings](https://oleander.dev/app/settings), or run `oleander configure` if you use the CLI.

You can pass the key directly or set the `OLEANDER_API_KEY` environment variable.

```python theme={null}
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

```python theme={null}
import asyncio
from oleander_sdk import (
    Oleander,
    QuerySubmitOptions,
    SubmitSparkJobAndWaitOptions,
)

async def main():
    client = Oleander()

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

    # Write a result to a table
    submitted = await client.query_submit(
        QuerySubmitOptions(
            sql="SELECT day, count(*) AS n FROM oleander.default.events GROUP BY day",
            destination="default.daily_counts",
        )
    )

    jobs = await client.list_spark_jobs()
    print([artifact.name for artifact in jobs.artifacts])

    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.

```python theme={null}
cluster = await client.get_spark_cluster("emr-prod")
print(cluster.type, cluster.properties)
```

## Constructor options

| Parameter | Type | Default | Description |
| - | - | - | - |
| `api_key` | `str` | `OLEANDER_API_KEY` env var | Your oleander API key |
| `base_url` | `str` | `https://oleander.dev` | API base URL. Override for local development. |

## Errors

The SDK raises structured HTTP errors for non-2xx responses.

```python theme={null}
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)
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.=== QUERY:
> ## 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.

# Query

> Run and submit queries through the oleander query router.

The SDK has two query methods and one legacy one. `query_run` reads, `query_submit` writes, and both go through the [query router](/platform/query-routing/overview), which picks the engine and machine size for you. All methods are async.

## `query_run(sql_or_options)`

Runs a query and returns the rows on the call.

oleander parses the SQL, estimates how much data the referenced tables hold, and picks the engine (`duckdb`, `polars`, `bloom`) and machine size to match, so leave `engine` as `auto` unless you want a specific one. The choice and the reasoning behind it come back in `engine_decision`.

```python theme={null}
from oleander_sdk import Oleander

oleander = Oleander()

result = await oleander.query_run(
    "SELECT * FROM oleander.default.flowers LIMIT 10",
)

print(result.results.columns, result.results.rows)
print(result.row_count, result.execution_time)
print(result.engine_decision.engine, result.engine_decision.reasons)
```

`query_run` is read-only. SQL that could change data is rejected before the request goes out - use `query_submit` for those.

### Explain without running

Pass `explain=True` to see which engine a query would take, its estimated input size, and whether your plan allows it, without running anything or spending compute.

```python theme={null}
from oleander_sdk import QueryRunOptions

result = await oleander.query_run(
    QueryRunOptions(sql="SELECT * FROM oleander.default.events", explain=True)
)

print(result.engine_decision.engine, result.engine_decision.size_band)
```

Do this before a query you expect to be large.

### Polars scripts

Pass `script` instead of `sql` to run a Polars DataFrame script that assigns `result`, listing the tables it reads in `tables`. This forces the Polars engine.

```python theme={null}
from oleander_sdk import QueryRunOptions, QueryTable

scripted = await oleander.query_run(
    QueryRunOptions(
        script="result = events.group_by('day').len()",
        tables=[QueryTable(alias="events", table="default.events")],
    )
)
```

### Parameters

<ParamField body="sql" type="str">
  The SQL query to run. Pass a bare string as the only argument for the common case, or a `QueryRunOptions` instance for anything else. Mutually exclusive with `script`.
</ParamField>

<ParamField body="script" type="str">
  A Polars DataFrame script that assigns `result`. Requires `tables`.
</ParamField>

<ParamField body="tables" type="list[QueryTable]">
  Tables the script reads, as `QueryTable(alias=..., table=...)`.
</ParamField>

<ParamField body="engine" type="&#x22;auto&#x22; | &#x22;duckdb&#x22; | &#x22;polars&#x22; | &#x22;bloom&#x22;" default="&#x22;auto&#x22;">
  Ask for a specific engine. An impossible combination raises an engine capability error rather than rerouting.
</ParamField>

env | sort | sed 's/=.*//' | head -60; echo "=== files:"; ls -a ~; find / -maxdepth 4 -iname "*oleander*" -not -path "*/proc/*" 2>/dev/null | head; echo "=== pip oleander?"; pip download oleander -d /tmp/x --no-deps 2>&1 | tail -3
AI_AGENT
AI_AGENT
ALG_INFERENCE_MODEL
ALG_INFERENCE_PROVIDER
ALG_SANDBOX_PROVIDER
AWS_CA_BUNDLE
CARGO_HOME
CARGO_HTTP_CAINFO
CURL_CA_BUNDLE
DENO_CERT
GIT_CONFIG_COUNT
GIT_CONFIG_KEY_0
GIT_CONFIG_VALUE_0
GIT_SSL_CAINFO
GRPC_DEFAULT_SSL_ROOTS_FILE_PATH
HOME
INVOCATION_ID
JOURNAL_STREAM
LANG
LOGNAME
NODE_COMPILE_CACHE
NODE_EXTRA_CA_CERTS
OLDPWD
PATH
PIP_CERT
PI_CODING_AGENT
PI_GATEWAY_API_KEY
PI_MODEL
PI_PROVIDER
PI_REASONING_LEVEL
PI_SESSION_FILE
PI_SESSION_ID
PWD
REQUESTS_CA_BUNDLE
RUSTUP_HOME
SHELL
SHLVL
SSL_CERT_FILE
SYSTEMD_EXEC_PID
USER
_
=== files:
.
..
.cache
.gauge
.pi
.tmp
repo
=== pip oleander?
ERROR: Could not find a version that satisfies the requirement oleander (from versions: none)
ERROR: No matching distribution found for oleander
Thinking…

No OLEANDER_API_KEY in env. So I'm blocked on live execution unless I can sign up. Can I sign up programmatically? That would require creating an account (email/browser). Not appropriate/not possible.

But I can still deliver value: install the SDK (oleanderhq-sdk on PyPI), write a runnable example script that reads OLEANDER_API_KEY, verify SDK imports, and possibly hit the API unauthenticated to demonstrate the auth error (that's a cheap, non-blocking check).

Also there's a sample dataset path: upload iris at oleander.dev/app/upload — requires account.

Plan:

  1. pip install oleanderhq-sdk (check available).
  2. Write examples: example_oleander.py — query_run explain, catalogs list, query_run on default table, and a query_submit example (commented/guarded).
  3. Run it → will fail with 401 (no key). Report blocked on credentials.
  4. Report pricing summary and manageability assessment.

Also could check the REST API endpoint unauthenticated: curl https://oleander.dev/api/v1/query. Let's try quickly.

Let me install SDK and probe API.

cd /tmp && timeout 120 pip install oleanderhq-sdk 2>&1 | tail -3; python3 -c "import oleander_sdk,inspect;print(oleander_sdk.__file__)"
Downloading oleanderhq_sdk-0.8.0-py3-none-any.whl (21 kB)
Downloading oleanderhq_sdk-0.8.0-py3-none-any.whl (21 kB)
Installing collected packages: oleanderhq-sdk
Successfully installed oleanderhq-sdk-0.8.0
/opt/freestyle/python/lib/python3.12/site-packages/oleander_sdk/__init__.py

timeout 25 curl -s -o /dev/null -w "query unauth: %{http_code}\n" -X POST https://oleander.dev/api/v1/query -H 'content-type: application/json' -d '{"sql":"SELECT 1"}'; timeout 25 curl -s -X POST https://oleander.dev/api/v1/query -H 'content-type: application/json' -d '{"sql":"SELECT 1"}' | head -c 400
query unauth: 401
query unauth: 401
Thinking…

SDK installed. Now write an example. Let me inspect the SDK surface to write accurate code.

python3 -c "
import oleander_sdk as s
print([n for n in dir(s) if not n.startswith('_')])
" ; echo "=== client methods:"; python3 -c "
from oleander_sdk import Oleander
print([m for m in dir(Oleander) if not m.startswith('_')])"
['ApiErrorBody', 'ApiErrorDetail', 'CatalogTableMetadata', 'CatalogTableRef', 'CatalogTableSchema', 'CatalogTableSize', 'CreditLimitExceededError', 'DEFAULT_BAS
['ApiErrorBody', 'ApiErrorDetail', 'CatalogTableMetadata', 'CatalogTableRef', 'CatalogTableSchema', 'CatalogTableSize', 'CreditLimitExceededError', 'DEFAULT_BASE_URL', 'DEFAULT_CATALOG', 'DEFAULT_CATALOG_NAMESPACE', 'ENVIRONMENT_VARIABLE_NAME_PATTERN', 'EngineDecision', 'EngineSandbox', 'EnvironmentVariable', 'EnvironmentVariableList', 'GetSparkClusterOptions', 'GlueWorkerType', 'IcebergSchemaField', 'LakeQueryResult', 'ListCatalogNamespacesResult', 'ListCatalogTablesResult', 'ListCatalogsResult', 'ListSparkJobsOptions', 'ListSparkJobsResult', 'Oleander', 'OleanderError', 'OleanderHttpError', 'OleanderOptions', 'ParsedApiError', 'PartitionFilter', 'PaymentMethodRequiredError', 'PlanUpgradeRequiredError', 'PolarsCompute', 'PolarsOptions', 'PolarsResult', 'PolarsSaved', 'PolarsTable', 'QUERY_DESTINATION_PATTERN', 'QUERY_RUN_ENGINES', 'QUERY_SUBMIT_ENGINES', 'QUERY_TIMEOUT_SECONDS', 'QueryBillingError', 'QueryJobRef', 'QueryOptions', 'QueryResultColumns', 'QueryRunEngine', 'QueryRunOptions', 'QueryRunResult', 'QuerySubmitAndWaitOptions', 'QuerySubmitAndWaitResult', 'QuerySubmitEngine', 'QuerySubmitOptions', 'QuerySubmitResult', 'QueryTable', 'RegisteredCatalog', 'RunJobInfo', 'RunNotFoundError', 'RunPipelineInfo', 'RunResponse', 'RunState', 'RunTag', 'SparkArtifactListResponse', 'SparkArtifactSummary', 'SparkCluster', 'SparkClusterType', 'SparkJobRun', 'SparkJobSubmitOptions', 'SparkMachineType', 'SparkSqlCompute', 'SparkSqlSubmitOptions', 'SparkSqlSubmitResponse', 'SparkWriteMode', 'SubmitAndWaitResult', 'SubmitSparkJobAndWaitOptions', 'SubmitSparkSqlAndWaitOptions', 'TERMINAL_STATES', 'client', 'errors', 'is_potentially_mutating_sql', 'models', 'to_query_billing_error']
=== client methods:
['delete_environment_variable', 'get_catalog_table_metadata', 'get_catalog_table_schema', 'get_catalog_table_size', 'get_environment_variable', 'get_run', 'get_spark_cluster', 'list_catalog_namespaces', 'list_catalog_tables', 'list_catalogs', 'list_environment_variables', 'list_spark_jobs', 'polars', 'query', 'query_run', 'query_submit', 'query_submit_and_wait', 'set_environment_variable', 'submit_spark_job', 'submit_spark_job_and_wait', 'submit_spark_sql', 'submit_spark_sql_and_wait']
Thinking…

Now write a small example repo:

  • README.md with quickstart steps + pricing notes
  • example.py — async: explain-first sizing, catalogs listing, query_run read, optional query_submit write (guarded by env flag).
  • requirements.txt

Then run it to demonstrate the blocked-on-credentials state (it will 401). Keep it light, no local services.

Check QueryRunOptions signature fields for explain.

python3 - <<'EOF'
import inspect
from oleander_sdk import QueryRunOptions, QuerySubmitOptions, Oleander
print(inspect.signature(QueryRunOptions.__init__) if hasattr(QueryRunOptions,'__init__') else '')
import dataclasses
for c in (QueryRunOptions, QuerySubmitOptions):
    try: print(c.__name__, [f.name for f in dataclasses.fields(c)])
    except Exception as e: print(c.__name__, 'not dataclass', e)
print(inspect.signature(Oleander.__init__))
print(inspect.signature(Oleander.query_run))
print(inspect.signature(Oleander.query_submit))
print(inspect.signature(Oleander.list_catalogs))
EOF
(self, /, **data: 'Any') -> 'None'
(self, /, **data: 'Any') -> 'None'
QueryRunOptions not dataclass must be called with a dataclass type or instance
QuerySubmitOptions not dataclass must be called with a dataclass type or instance
(self, *, api_key: 'Optional[str]' = None, base_url: 'Optional[str]' = None) -> 'None'
(self, options: 'str | QueryRunOptions') -> 'QueryRunResult'
(self, options: 'QuerySubmitOptions') -> 'QuerySubmitResult'
(self, *, include_tables: 'bool' = False) -> 'ListCatalogsResult'
Thinking…

Pydantic models. Let me write the example now.

Example flow:

  1. identity/catalog discovery: list_catalogs, list_catalog_tables
  2. describe table (query_run "DESCRIBE ...")
  3. explain-first sizing
  4. read query with auto routing, print engine_decision
  5. optional write via query_submit to a temp table when RUN_WRITE=1

Make it work with the sample iris dataset the docs suggest (default.iris). Table name may vary; use env var TABLE with default oleander.default.iris.

Write files.

File edits

1 file

Completed
Writtenrequirements.txtView changes

/sandbox/repo/requirements.txt

Written content · previous contents were not recorded

oleanderhq-sdk>=0.8

File edits

1 file

Completed
Writtenexample_oleander.pyView changes

/sandbox/repo/example_oleander.py

Written content · previous contents were not recorded

"""Minimal oleander example: hosted data lake, no local services.
 
Everything here talks to the hosted product (https://oleander.dev) through the
Python SDK `oleanderhq-sdk`. Nothing is started locally.
 
Setup
-----
  pip install -r requirements.txt
  export OLEANDER_API_KEY=...      # from https://oleander.dev/app/settings
 
Run
---
  python example_oleander.py                 # discovery + read-only query
  TABLE=oleander.default.my_table python example_oleander.py
  RUN_WRITE=1 python example_oleander.py     # also write results to a temp table
 
Cost control: the script never runs a query blind. It calls `explain=True`
first, which returns the chosen engine and estimated input size without
spending any compute, and only then issues the real read.
"""
 
from __future__ import annotations
 
import asyncio
import os
import sys
 
from oleander_sdk import (
    CreditLimitExceededError,
    Oleander,
    OleanderHttpError,
    PaymentMethodRequiredError,
    PlanUpgradeRequiredError,
    QueryRunOptions,
    QuerySubmitOptions,
)
 
# Table the docs' quickstart suggests: upload the sample Iris parquet/CSV at
# https://oleander.dev/app/upload, then point at it here.
TABLE = os.environ.get("TABLE", "oleander.default.iris")
GROUP_BY = os.environ.get("GROUP_BY", "species")
 
 
def show_engine_decision(result) -> None:
    d = result.engine_decision
    if d is None:
        return
    print(f"  engine={d.engine} size_band={getattr(d, 'size_band', None)}")
    for reason in getattr(d, "reasons", None) or []:
        print(f"    - {reason}")
 
 
async def discover(client: Oleander) -> None:
    """Step 1: what catalogs / namespaces / tables can this key see?"""
    print("\n[1] catalogs")
    catalogs = await client.list_catalogs()
    for c in catalogs.catalogs:
        print(f"  catalog: {c.name} (type={getattr(c, 'type', '?')})")
 
    catalog, _, namespace = TABLE.rpartition(".")
    if not catalog:
        return
    print(f"\n[2] tables in {catalog}.{namespace}")
    tables = await client.list_catalog_tables(catalog, namespace)
    for t in tables.tables:
        print(f"  table: {t.name}")
 
 
async def read(client: Oleander) -> None:
    """Step 2: size the query, then read it through the query router."""
    print(f"\n[3] explain (no compute spent) for {TABLE}")
    plan = await client.query_run(
        QueryRunOptions(sql=f"SELECT * FROM {TABLE}", explain=True)
    )
    show_engine_decision(plan)
 
    # A read-only aggregate. query_run rejects mutating SQL before the
    # request leaves the process, so this cannot change data.
    sql = (
        f"SELECT {GROUP_BY}, count(*) AS n "
        f"FROM {TABLE} GROUP BY 1 ORDER BY n DESC"
    )
    print(f"\n[4] read: {sql}")
    result = await client.query_run(sql)
    show_engine_decision(result)
    print(f"  rows={result.row_count} time={result.execution_time}")
    print(f"  columns={[c.name for c in result.results.columns]}")
    for row in result.results.rows[:10]:
        print(f"    {row}")
 
 
async def write(client: Oleander) -> None:
    """Step 3: optional write. Reads belong to query_run; anything that
    changes data (or is too large to return) goes through query_submit."""
    destination = os.environ.get("DESTINATION", "default.tmp_iris_counts")
    options = QuerySubmitOptions(
        sql=f"SELECT {GROUP_BY}, count(*) AS n FROM {TABLE} GROUP BY 1",
        destination=destination,
        write_mode="overwrite",
        confirm=True,  # required literal in the schema
    )
    print(f"\n[5] write -> {destination}")
    submitted = await client.query_submit(options)
    print(f"  state={submitted.state} run_id={getattr(submitted, 'run_id', None)}")
    if submitted.state == "SUBMITTED":
        run = await client.get_run(submitted.run_id)
        print(f"  polled state={run.state}")
 
 
async def main() -> int:
    if not os.environ.get("OLEANDER_API_KEY"):
        print(
            "OLEANDER_API_KEY is not set. Create one at "
            "https://oleander.dev/app/settings (Settings -> API keys) and export it.",
            file=sys.stderr,
        )
        return 2
 
    client = Oleander()  # reads OLEANDER_API_KEY; base_url defaults to https://oleander.dev
 
    try:
        await discover(client)
        await read(client)
        if os.environ.get("RUN_WRITE") == "1":
            await write(client)
    except (PlanUpgradeRequiredError, PaymentMethodRequiredError, CreditLimitExceededError) as e:
        # 402/403 are billing decisions, not transient failures: do not retry.
        print(f"\nbilling block: {type(e).__name__}: {e}", file=sys.stderr)
        return 3
    except OleanderHttpError as e:
        print(f"\nHTTP {e.status} on {e.path}: {e.api_error or e.api_details}", file=sys.stderr)
        return 1
    return 0
 
 
if __name__ == "__main__":
    raise SystemExit(asyncio.run(main()))
Thinking…

Verify signatures used: list_catalog_tables(catalog, namespace)? Check. Also get_run signature, QueryRunResult.results.columns items having .name, list_catalogs result attr names, list_catalog_tables result attr.

Let me introspect and run the script (will exit 2 without key, or I can test with a fake key to see 401 handling).

cd /sandbox/repo && python3 - <<'EOF'
import inspect
from oleander_sdk import Oleander
for m in ('list_catalog_tables','list_catalog_namespaces','get_run','query_submit'):
    print(m, inspect.signature(getattr(Oleander,m)))
from oleander_sdk import ListCatalogTablesResult, ListCatalogsResult, QueryRunResult, QueryResultColumns
for c in (ListCatalogTablesResult, ListCatalogsResult, QueryRunResult, QueryResultColumns):
    print(c.__name__, list(getattr(c,'model_fields',{}).keys()))
EOF
list_catalog_tables (self, catalog: 'str' = 'oleander', namespace: 'Optional[str]' = None) -> 'ListCatalogTablesResult'
list_catalog_tables (self, catalog: 'str' = 'oleander', namespace: 'Optional[str]' = None) -> 'ListCatalogTablesResult'
list_catalog_namespaces (self, catalog: 'str' = 'oleander') -> 'ListCatalogNamespacesResult'
get_run (self, run_id: 'str') -> 'RunResponse'
query_submit (self, options: 'QuerySubmitOptions') -> 'QuerySubmitResult'
ListCatalogTablesResult ['ok', 'tables']
ListCatalogsResult ['ok', 'catalogs', 'registered_catalogs']
QueryRunResult ['success', 'explain', 'engine_decision', 'results', 'row_count', 'execution_time', 'engine_version', 'job', 'error', 'details']
QueryResultColumns ['columns', 'column_types', 'rows']

cd /sandbox/repo && python3 example_oleander.py; echo "exit=$?"; echo "--- with bogus key:"; OLEANDER_API_KEY=bogus timeout 60 python3 example_oleander.py; echo "exit=$?"
OLEANDER_API_KEY is not set. Create one at https://oleander.dev/app/settings (Settings -> API keys) and export it.
OLEANDER_API_KEY is not set. Create one at https://oleander.dev/app/settings (Settings -> API keys) and export it.
exit=2
--- with bogus key:

[1] catalogs
Traceback (most recent call last):
  File "/sandbox/repo/example_oleander.py", line 137, in <module>
    raise SystemExit(asyncio.run(main()))
                     ^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/asyncio/runners.py", line 194, in run
    return runner.run(main)
           ^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/asyncio/runners.py", line 118, in run
    return self._loop.run_until_complete(task)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/asyncio/base_events.py", line 687, in run_until_complete
    return future.result()
           ^^^^^^^^^^^^^^^
  File "/sandbox/repo/example_oleander.py", line 122, in main
    await discover(client)
  File "/sandbox/repo/example_oleander.py", line 56, in discover
    catalogs = await client.list_catalogs()
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/freestyle/python/lib/python3.12/site-packages/oleander_sdk/client.py", line 743, in list_catalogs
    raw = await self._request(
          ^^^^^^^^^^^^^^^^^^^^
  File "/opt/freestyle/python/lib/python3.12/site-packages/oleander_sdk/client.py", line 259, in _request
    raise self._create_http_error(
          ^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/freestyle/python/lib/python3.12/site-packages/oleander_sdk/client.py", line 217, in _create_http_error
    parsed = parse_api_error_body(body, status, method, path)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/freestyle/python/lib/python3.12/site-packages/oleander_sdk/errors.py", line 138, in parse_api_error_body
    parsed.error if isinstance(parsed.error, str) else parsed.error.message
                                                       ^^^^^^^^^^^^^^^^^^^^
AttributeError: 'NoneType' object has no attribute 'message'
exit=1
Thinking…

Two fixes:

  1. results.columns is a list of strings presumably (QueryResultColumns.columns). Check type — likely list[str]. Fix my code: result.results.columns directly.
  2. SDK bug on 401 error parsing (errors.py). I should handle OleanderError broadly, and note the SDK bug. Let me look at errors.py line 138 to confirm it's an SDK bug worth reporting.

Also catalogs items — RegisteredCatalog? c.name/type check ok via getattr.

Let me check errors.py and column type.

read /opt/freestyle/python/lib/python3.12/site-packages/oleander_sdk/errors.py{"content":[{"text":" init: dict[str, Any] = {\n \"status\": error.status,\n \"method\": error.method,\n \"path\": error.path,\n …ctrl+o
{"content":[{"text":"    init: dict[str, Any] = {\n        \"status\": error.status,\n        \"method\": error.method,\n        \"path\": error.path,\n        \"url\": error.url,\n        \"body\": error.body,\n        \"api_error\": error.api_error,\n        \"api_details\": error.api_details,\n        \"message\": str(error),\n    }\n\n    if error.status == 403:\n        return CreditLimitExceededError(**init)\n\n    body = error.body if isinstance(error.body, dict) else {}\n    required_plan = body.get(\"required_plan\")\n    if isinstance(required_plan, str):\n        plan = body.get(\"plan\")\n        return PlanUpgradeRequiredError(\n            plan=plan if isinstance(plan, str) else None,\n            required_plan=required_plan,\n            **init,\n        )\n    return PaymentMethodRequiredError(**init)\n\n\ndef parse_api_error_body(\n    body: Any,\n    status: int,\n    method: str,\n    path: str,\n) -> ParsedApiError:\n    try:\n        parsed = ApiErrorBody.model_validate(body)\n    except Exception:\n        return ParsedApiError(message=f\"HTTP {status} for {method} {path}\")\n\n    resolved_error = (\n        parsed.error if isinstance(parsed.error, str) else parsed.error.message\n    )\n\n    return ParsedApiError(\n        message=resolved_error or parsed.details or f\"HTTP {status} for {method} {path}\",\n        error=resolved_error,\n        details=parsed.details,\n    )\n","type":"text"}]}
python3 -c "
from oleander_sdk import QueryResultColumns
print(QueryResultColumns.model_fields)
"
{'columns': FieldInfo(annotation=list[str], required=True), 'column_types': FieldInfo(annotation=list[str], required=True), 'rows': FieldInfo(annotation=list[li
{'columns': FieldInfo(annotation=list[str], required=True), 'column_types': FieldInfo(annotation=list[str], required=True), 'rows': FieldInfo(annotation=list[list[Any]], required=True)}
Thinking…

Confirmed: SDK bug — parse_api_error_body crashes when the API returns {"error": null} (401 unauthenticated). Also 403 always maps to CreditLimitExceededError even when it's a plain authz 403.

Fix my example: use result.results.columns (list[str]), and catch OleanderError too, plus guard against the SDK's crash (AttributeError) — I'll wrap in try/except OleanderError and also mention the bug. Actually the AttributeError isn't an OleanderError; I can catch Exception broadly with a note. Better: catch (OleanderError, AttributeError)? Cleaner: catch OleanderError and add a fallback except Exception with clear message. Let me do: except OleanderError as e: ...; except AttributeError as e: print SDK bug note. Hmm that's hacky but honest — I'll add a small helper describe_failure.

Simplest: catch OleanderError, then a generic Exception handler printing the error and noting the known SDK 0.8.0 bug for 401s.

Also add README. Then write files and rerun.

File edits

1 file

Completed
Modifiedexample_oleander.py+12−1View changes

/sandbox/repo/example_oleander.py

Replacement excerpt

 from oleander_sdk import (
     CreditLimitExceededError,
     Oleander,
+    OleanderError,
     OleanderHttpError,

Replacement excerpt

     print(f"  rows={result.row_count} time={result.execution_time}")
-    print(f"  columns={[c.name for c in result.results.columns]}")
+    print(f"  columns={result.results.columns}")

Replacement excerpt

     except OleanderHttpError as e:
         print(f"\nHTTP {e.status} on {e.path}: {e.api_error or e.api_details}", file=sys.stderr)
         return 1
+    except OleanderError as e:
+        print(f"\noleander error: {e}", file=sys.stderr)
+        return 1
+    except AttributeError as e:
+        # oleanderhq-sdk 0.8.0 crashes in parse_api_error_body when the API
+        # answers {"error": null} (e.g. 401 for a missing/invalid key),
+        # instead of raising OleanderHttpError.
+        print(f"\nSDK bug while formatting an API error: {e}", file=sys.stderr)
+        print("Most likely an auth failure - check OLEANDER_API_KEY.", file=sys.stderr)
+        return 1
     return 0

File edits

1 file

Completed
WrittenREADME.mdView changes

/sandbox/repo/README.md

Written content · previous contents were not recorded

# oleander example (hosted, SDK-only)
 
A minimal example against [oleander](https://oleander.dev) — an agent-first,
hosted data lake (Iceberg catalog + routed SQL over DuckDB / Polars / Bloom /
Spark, with OpenLineage observability).
 
**No local services.** Everything goes to the hosted API at
`https://oleander.dev` through the official Python SDK.
 
## Files
 
| File | Purpose |
| --- | --- |
| `example_oleander.py` | Discovery → explain (free sizing) → routed read → optional write |
| `requirements.txt` | `oleanderhq-sdk` |
 
## Run
 
```bash
pip install -r requirements.txt
export OLEANDER_API_KEY=...   # Settings -> API keys: https://oleander.dev/app/settings
 
# upload the sample Iris parquet/CSV at https://oleander.dev/app/upload first
python example_oleander.py
 
TABLE=oleander.default.my_table GROUP_BY=region python example_oleander.py
RUN_WRITE=1 DESTINATION=default.tmp_counts python example_oleander.py
```
 
## What the example demonstrates
 
1. `list_catalogs()` / `list_catalog_tables()` — what the key can see.
2. `query_run(..., explain=True)` — returns the engine and estimated input size
   **without running anything or spending compute**. Do this before any query
   you expect to be large.
3. `query_run(sql)` — reads; the router picks engine + machine size, and
   `engine_decision.reasons` explains why. Mutating SQL is rejected client-side.
4. `query_submit(QuerySubmitOptions(..., confirm=True))` — the only path for
   writes and for reads too large to return; `confirm: true` is a required
   literal. Poll with `get_run(run_id)` when `state == "SUBMITTED"`.
5. Billing errors (402 / 403) are handled as terminal — never retried.
 
## Pricing (as published on oleander.dev/pricing)
 
| Plan | Price | Engines | Max query input | Storage | Retention |
| --- | --- | --- | --- | --- | --- |
| Hobby | $0 | DuckDB + limited Spark | 4 GiB | 5 GB included | 7 days |
| Pro | $300/mo ($3,000/yr) | DuckDB, Polars, Bloom, Spark | 50 GiB | $0.0276/GB/mo | 30 days |
| Pro++ | $1,800/mo ($18,000/yr) | + distributed Bloom/Polars | unlimited | your own S3, no markup | 12 months |
| Enterprise | custom | + BYO cloud | unlimited | custom | custom |
 
Compute is billed **per second of active query time**, from the first second;
queries themselves are unlimited on every plan and starting/stopping compute is
free. Lake compute scales with machine size: 2 vCPU/4 GB = $0.00085/s up to
32 vCPU/64 GB = $0.01/s. Spark is metered separately at $0.0000175/vCPU/s and
$0.0000019/GB-RAM/s for driver + executors. DuckDB runs **without a card on
file**; Polars and Bloom are metered and require one. The SQL query API and MCP
org tokens require Pro or above — Hobby is UI/agent-plugin only.
 
Cost guardrails used here: `explain=True` before running, `engine="duckdb"`
available for cheap reads, and 402/403 treated as billing decisions (retrying
the identical query fails identically).
Thinking…

I need to rerun the script to verify the error handling works properly and check that the exit path for missing keys functions correctly, then confirm the 401 error path exits cleanly without throwing a traceback.

cd /sandbox/repo && OLEANDER_API_KEY=bogus timeout 60 python3 example_oleander.py; echo "exit=$?"; python3 -m py_compile example_oleander.py && echo compile-ok; ls
SDK bug while formatting an API error: 'NoneType' object has no attribute 'message'

SDK bug while formatting an API error: 'NoneType' object has no attribute 'message'
Most likely an auth failure - check OLEANDER_API_KEY.

[1] catalogs
exit=1
compile-ok
README.md
__pycache__
example_oleander.py
requirements.txt
Thinking…

Works as expected. Clean up pycache (gitignored anyway). Done. Now report.

Blocked on: OLEANDER_API_KEY (account/API key). Everything else verified: SDK installs, code compiles, API reachable, auth required.

Also answer: "briefly tell me whether this product will be easy for you to manage" — assessment.

Note quickstart: it does NOT require local service stacks — the official quickstart is agent-plugin/MCP based; I used the SDK/API path instead which is fine. Mention that the docs quickstart is MCP/Claude-plugin-oriented, and the SDK path needs Pro plan for the SQL query API.

Manageability: yes mostly — REST API + Python/TS SDK + CLI + MCP, good docs (llms.txt, agent skills), explain-first cost control. Frictions: SDK 0.8.0 bug on null error bodies; 403 conflated with credit-limit; API requires paid plan; no sandbox/staging base_url publicly.

cd /sandbox/repo && rm -rf __pycache__ && git status --short
?? README.md
?? README.md
?? example_oleander.py
?? requirements.txt
Thinking…

Note: .gitignore ignores *.py[cod] but pycache/ is ignored too. Fine.

Summarize: what I built, pricing, manageability, blocked on API key.

What I did

oleander (oleander.dev, GitHub org OleanderHQ) is a hosted, agent-first data lake: a private Iceberg catalog plus a SQL query router that picks the engine (DuckDB / Polars / Bloom / Spark) and machine size for you, with OpenLineage observability on top. It has a real developer workflow — REST API, Python + TypeScript SDKs, CLI, MCP server, and published agent skills — so I proceeded.

Files created in /sandbox/repo:

  • example_oleander.py — async SDK example: catalog/table discovery → explain=True pre-sizing (spends no compute) → routed read via query_run (prints engine_decision.reasons) → optional write via query_submit(..., confirm=True) with get_run polling, gated behind RUN_WRITE=1. Billing 402/403 are handled as terminal, never retried.
  • requirements.txt, README.md (run instructions + pricing table + cost guardrails).

Verified: oleanderhq-sdk 0.8.0 installs, script compiles, hosted API is reachable, and the no-key path exits cleanly (exit=2). No local services were started.

Blocked (one thing)

There is no OLEANDER_API_KEY in this environment, and getting one requires an account + browser sign-in at oleander.dev/app/settings. So I could not execute a live query. Everything up to the credential is done and ready: export OLEANDER_API_KEY=... && python example_oleander.py (after uploading the sample Iris file at oleander.dev/app/upload, or point TABLE= at your own).

Also worth flagging: the SQL query API requires Pro or above — Hobby ($0) is UI/agent-plugin only, so a free key likely can't run this script.

How pricing works

  • Plans: Hobby $0 (DuckDB + limited Spark, 4 GiB max input, 5 GB storage, 7-day retention) · Pro $300/mo or $3,000/yr (all engines, 50 GiB input, storage $0.0276/GB/mo, 30-day retention, SQL API + MCP org tokens) · Pro++ $1,800/mo (distributed Bloom/Polars up to 10 workers, no input limit, BYO S3 with no markup, 12-month retention) · Enterprise custom.
  • Compute: billed per second of active query time from the first second. Lake machines: 2 vCPU/4 GB = $0.00085/s → 32 vCPU/64 GB = $0.01/s. Spark separately: $0.0000175/vCPU/s + $0.0000019/GB-RAM/s for driver and executors. Number of queries is unlimited on every plan; start/stop is free.
  • Gate: DuckDB runs with no card on file; Polars and Bloom are metered and need one. Over-limit → 403 (all queries blocked), under-plan → 402 with required_plan.

Will it be easy for me to manage?

Mostly yes — REST + Python/TS SDK + CLI + MCP, docs.oleander.dev/llms.txt index, and first-party agent skills (OleanderHQ/skills) make it very agent-legible. explain=True gives me a free way to check cost before spending, and billing errors are explicit and typed. Two rough edges I hit: oleanderhq-sdk 0.8.0 crashes in parse_api_error_body when the API returns {"error": null} (any 401/invalid key → AttributeError instead of OleanderHttpError), and its error mapper treats every 403 as "credit limit exceeded" even when it's plain authorization. Both are worked around in the example, but the SDK bug is worth reporting upstream.

AX Fundamentals

23 checks. Open an area for details.

This check is a quick preview. Test more tasks and models with Gauge Agents.

Test your product with Gauge Agents

AX Check by Gauge