> ## Documentation Index
> Fetch the complete documentation index at: https://docs.e6data.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Notebooks

> notebooks

ReferenceApplies to: Unified engine deployments

`[notebooks]`

## Notebook service

### `service.max_document_bytes`

Limits the saved size of one document handled by this service.

* **Default:** `16777216`
* **Type:** integer (bytes); positive

> **Example**
>
> `1048576` gives one document a 1 MiB budget. This measures saved document bytes, not the size of tables queried by the document.

### `service.max_cells`

Limits how many cells one notebook document may contain.

* **Default:** `1024`
* **Type:** integer; positive

> **Example**
>
> `1024` allows a notebook with up to 1024 SQL, Python, or other supported cells.

### `service.max_event_bytes`

Limits the size of one output event produced by a notebook run.

* **Default:** `1048576`
* **Type:** integer (bytes); positive

> **Example**
>
> `1048576` allows an event up to 1 MiB. This must fit inside the total output-byte budget.

### `service.max_output_bytes`

Limits how much output data one notebook execution may retain.

* **Default:** `16777216`
* **Type:** integer (bytes); positive

> **Example**
>
> `16777216` gives retained output a 16 MiB budget. A large printed value and many small events both use that budget.

### `service.max_output_events`

Limits how many output events a notebook execution may retain.

* **Default:** `4096`
* **Type:** integer; positive

> **Example**
>
> `4096` bounds a run that produces many small output events, even if their combined bytes are below the byte limit.

### `service.max_page_size`

Limits how many records one list response may return.

* **Default:** `100`
* **Type:** integer; positive

> **Example**
>
> `100` returns a long list over pages of at most 100 items. A client can still request a smaller page.

### `service.runner_page_size`

Sets how many pending notebook work items the runner reads in one page.

* **Default:** `16`
* **Type:** integer; positive

> **Example**
>
> `16` processes work in pages of up to 16 items. This value must not exceed the notebook service’s list-page limit.

### `poll_interval`

Sets how often the notebook service checks for execution work.

* **Default:** `100 ms`
* **Type:** duration

> **Example**
>
> A 100 ms interval checks about ten times per second. It does not automatically rerun every open notebook.

### `idle_timeout`

Sets how long an unused SQL notebook session may stay open.

* **Default:** `1800 s`
* **Type:** duration

> **Example**
>
> `{ secs = 1800, nanos = 0 }` keeps an idle SQL notebook session for up to 30 minutes before retirement.

## Python runtime

### `python_runtime`

Supplies the settings needed to start and manage Python notebook processes.

* **Default:** Unset
* **Type:** object; optional

> **Example**
>
> Omit this object to leave Python execution unavailable. Adding it configures Python hosting, but the notebooks role and Python execution permission must also be enabled.

### `python_runtime.python`

Chooses the Python interpreter used to run Python notebook cells.

* **Default:** `"python3"`
* **Type:** string

> **Example**
>
> `"@bundled/python"` selects the interpreter shipped in a full Laminar package. An absolute path selects your own installed interpreter.

### `python_runtime.environment`

Supplies environment variables to Python notebook processes. Sensitive values are hidden in Settings. `IPYTHONDIR`, `JUPYTER_RUNTIME_DIR`, and `XDG_CACHE_HOME` are computed from the runtime scratch directory and cannot be set here.

* **Default:** `{}`
* **Type:** map

> **Example**
>
> An entry such as `APP_MODE = "analysis"` makes that variable available to Python code. These values are treated as sensitive in Settings.

### `python_runtime.engine_endpoint`

Tells the Python notebook bridge which HTTP engine address to use.

* **Default:** `"http://127.0.0.1:15003"`
* **Type:** string

> **Example**
>
> A local host can use `"http://127.0.0.1:15003"`. If the engine is remote, use an address that the Python process can actually reach.

### `python_runtime.spark_endpoint`

Tells the Python runtime where its Spark Connect client should connect.

* **Default:** `"sc://127.0.0.1:15002"`
* **Type:** string

> **Example**
>
> `"sc://laminar-controller:15002"` points it to a Spark Connect listener on port 15002. It does not use the browser HTTP port.

### `python_runtime.user_id`

Chooses the user identity passed to the Python bridge and its clients.

* **Default:** `"local"`
* **Type:** string

> **Example**
>
> `"local"` identifies notebook client activity with that configured value. The listener may apply its own server-owned identity separately.

### `python_runtime.startup_timeout`

Limits how long the host waits for a Python process to start and become ready.

* **Default:** `30 s`
* **Type:** duration

> **Example**
>
> `{ secs = 30, nanos = 0 }` allows 30 seconds for startup, including the bridge’s initial exchange.

### `python_runtime.execution_timeout`

Limits how long the host waits for a Python cell execution.

* **Default:** `300 s`
* **Type:** duration

> **Example**
>
> `{ secs = 900, nanos = 0 }` gives a cell up to 15 minutes to finish. This Python host timeout is separate from a SQL task timeout.

### `python_runtime.control_timeout`

Limits how long the host waits for a Python process to answer a control operation.

* **Default:** `10 s`
* **Type:** duration

> **Example**
>
> `{ secs = 10, nanos = 0 }` gives an interrupt or shutdown request up to ten seconds to respond.

### `python_runtime.max_message_bytes`

Limits the size of one message exchanged with the Python process.

* **Default:** `4194304`
* **Type:** integer (bytes); positive

> **Example**
>
> `4194304` allows a bridge message up to 4 MiB. A large Python result must still fit the notebook output limits.

### `python_runtime.event_capacity`

Limits how many Python bridge events may wait in memory for a consumer.

* **Default:** `64`
* **Type:** integer; positive

> **Example**
>
> `64` allows up to 64 queued events. Once the queue fills, the producer must wait rather than growing the queue without a bound.

### `python_runtime.max_kernels`

Limits how many Python notebook processes this host may keep active at once.

* **Default:** `4`
* **Type:** integer; positive

> **Example**
>
> `4` allows up to four kernels. Each kernel has its own process state and consumes host resources.

### `python_runtime.idle_timeout`

Sets how long an unused Python kernel can remain open before the host retires it.

* **Default:** `1800 s`
* **Type:** duration

> **Example**
>
> `{ secs = 1800, nanos = 0 }` allows 30 minutes of idle time. This is separate from how long an active cell may run.

## Python and output limits

`notebooks.python_runtime` is unset in the native baseline. The field entries list the Python host values used when that optional object is created. The `python` field accepts a configured interpreter path or `@bundled/python` for the installed package runtime. Omitting the object leaves Python notebook execution unavailable even if the Python feature flag is true.

## Python in Kubernetes

The container image includes Python and the notebook packages at `/opt/laminar/python/bin/python3`. Set `notebooks.python_runtime.python` to this path on the controller. The controller checks that the required packages can load before starting services.

Python notebook cells and pandas code run in the controller pod. Supported SQL and PySpark query plans run on Kubernetes task workers using Rust and DuckDB. Workers do not start Python processes. PySpark workload definitions are compiled with the controller's Python runtime before execution.

Use the controller's local HTTP and Spark Connect listeners for `engine_endpoint` and `spark_endpoint`. Each kernel gets a separate temporary working directory. Notebook documents and saved outputs use `storage_root`. Temporary files and Python variables do not survive a controller restart. CPU and memory used by Python count against the controller pod's resources.

Notebook event bytes must fit the total output byte budget. Runner page size must fit the notebook service page size. Uploaded session artifacts have separate total, chunk-size, and chunk-count limits.


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