Notebooks

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