> ## 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.

# Notebooks

> Interactive Python and TypeScript notebooks with pre-wired lake access.

Notebooks are interactive execution environments built into the platform. Each notebook gives you a persistent Python or TypeScript sandbox with your catalogs, lake tables, and external connections already wired in - no credentials to configure, no installs to run.

<Note>
  Notebooks are in **alpha**. They were previously called Tasks.
</Note>

New organizations start with an example notebook that loads NYC taxi trips and charts them. Add **Python**, **TypeScript**, **Spark**, or **Markdown** cells from the add-cell button.

<Tabs>
  <Tab title="Python">
    The Python sandbox runs Python 3.13 and comes with the following libraries pre-installed:

    | Library | Purpose |
    | - | - |
    | `polars` | DataFrame processing |
    | `pandas` | DataFrame processing |
    | `duckdb` | In-process SQL |
    | `pyiceberg` | Iceberg catalog client |
    | `numpy` | Numerical computing |
    | `matplotlib` | Plotting |
    | `pyarrow` | Arrow/Parquet I/O |

    ### The `oleander` module

    Every cell has access to a generated `oleander` module that wires your catalog and DuckDB connection automatically:

    ```python theme={null}
    # Pre-wired DuckDB connection with all your Iceberg catalogs attached
    conn = oleander.conn

    # Default Lakekeeper catalog as a pyiceberg catalog object
    catalog = oleander.default_catalog

    # Get any registered catalog by name
    my_catalog = oleander.get_catalog("my_catalog_name")
    ```

    Query your lake directly:

    ```python theme={null}
    result = conn.execute("SELECT * FROM oleander.default.flowers LIMIT 10").df()
    result
    ```

    Use pyiceberg for low-level catalog operations:

    ```python theme={null}
    table = catalog.load_table("default.flowers")
    df = table.scan().to_pandas()
    df.head()
    ```

    ### BigQuery

    If you have BigQuery connections configured, the DuckDB `bigquery` extension is installed automatically. BigQuery tables are accessible as `connection_name.dataset.table`:

    ```python theme={null}
    result = conn.execute("""
      SELECT date, SUM(revenue) AS total
      FROM my_bq.analytics.orders
      WHERE date >= '2024-01-01'
      GROUP BY 1
      ORDER BY 1
    """).df()
    ```

    ### State persistence

    Variables persist across cell executions within a session. If you define a DataFrame in one cell, it is available in the next. State is stored in `/tmp/_oleander_state.pkl` and survives cell reruns.

    ### Output

    DataFrames are displayed as structured tables. Matplotlib figures are rendered as inline SVG. Other values are printed as text.
  </Tab>

  <Tab title="TypeScript">
    The TypeScript sandbox runs Node 24 with `tsx` for execution. A generated `oleander` module exposes your Iceberg catalogs:

    ```typescript theme={null}
    import { defaultCatalog, getCatalog, catalogs } from './oleander';

    // List all catalogs
    console.log(catalogs.map(c => c.name));

    // Load a table from the default catalog
    const table = await defaultCatalog.loadTable({ namespace: ['default'], name: 'flowers' });
    ```
  </Tab>
</Tabs>

## Compute size

The toolbar's compute selector sizes the sandbox that runs your cells: **2**, **4**, or **8** CPUs, with 2 GB of memory per CPU. Changing it resizes the sandbox in place, so variables and state carry over. 8 CPUs is the ceiling for notebook sandboxes; it is separate from the larger tiers the [query router](/platform/query-routing/overview#machine-sizing) uses for lake queries.

## Ask AI

Press <kbd>⌘E</kbd> in a cell to generate or edit its code from a plain-English prompt. The assistant knows the sandbox's libraries and your catalog structure.

## SQL cells

SQL cells run through the [query router](/platform/query-routing/overview), like the lake editor. **Auto** picks the engine for each run, or you can pin **DuckDB**, **Polars**, **Bloom**, or **SparkSQL** from the cell's run settings. SparkSQL writes its result to a table and links to the Spark run instead of returning rows.

Pick a catalog to scope table autocomplete. Up to 500 rows of each result are saved with the cell.

## Spark cells

Submit inline PySpark code as a managed Spark job directly from a notebook cell. The job runs in the `oleander.tasks` namespace and returns a run ID you can track in the platform. Lineage from Spark cell runs is captured automatically.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.