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

# SQL sessions

> session

ReferenceApplies to: Unified engine deployments

`[session]`

## New session defaults

### `default_settings.current_catalog`

Chooses the catalog a new SQL session uses before the user selects another one.

* **Default:** `"default"`
* **Type:** string

> **Example**
>
> With `"warehouse"`, an unqualified table lookup starts in that catalog. `USE CATALOG other_catalog` changes the current catalog for that session.

### `default_settings.namespace`

Chooses the namespace a new SQL session uses for unqualified table names.

* **Default:** `["default"]`
* **Type:** array

> **Example**
>
> `["sales"]` starts new sessions in the sales namespace. A namespace with multiple components is written as an ordered array.

### `default_settings.time_zone`

Chooses the timezone used by new sessions for time-dependent SQL behavior.

* **Default:** `"UTC"`
* **Type:** string

> **Example**
>
> `"UTC"` gives sessions a common timezone. Use a supported timezone name when timestamp expressions must follow another timezone.

### `default_settings.case_sensitive`

Chooses whether identifier lookup distinguishes uppercase and lowercase names.

* **Default:** `false`
* **Type:** boolean

> **Example**
>
> When enabled, names such as `Orders` and `orders` are resolved with case sensitivity. This controls identifiers, not the case of text stored in a column.

### `default_settings.ansi_enabled`

Chooses the initial ANSI SQL behavior for new sessions.

* **Default:** `true`
* **Type:** boolean

> **Example**
>
> Set it to true when new sessions should request ANSI behavior. This flag does not add SQL features that the selected executor does not support.

## Submission overrides

### `submission_options.worker_scope`

Chooses whether a worker is allocated for one task or reused within a workload run.

* **Default:** Unset
* **Type:** choice: `Task`, `Workload`; optional

> **Example**
>
> `"Task"` gives tasks their own allocations. `"Workload"` lets tasks in the same run reuse a worker pool.

### `submission_options.parallelism`

Limits how many tasks in one workload run may execute at the same time.

* **Default:** Unset
* **Type:** integer; positive; optional

> **Example**
>
> `2` allows up to two concurrent tasks. If unset, workload-scoped workers default to one; task-scoped workers have no additional cap here.

### `submission_options.execution_target`

Chooses the engine expected to execute the task.

* **Default:** Unset
* **Type:** choice: `DataFusion`, `DuckDb`; optional

> **Example**
>
> `"DuckDb"` selects Native Engine. `DataFusion` is another serialized target, but it needs a compatible executor; the current native worker starts Native Engine.

### `submission_options.execution_timeout`

Limits how long a task is allowed to execute.

* **Default:** Unset
* **Type:** duration; optional

> **Example**
>
> `{ secs = 300, nanos = 0 }` gives a task five minutes. Leaving this optional field unset gives the task no execution time limit.

### `submission_options.compute_requirements`

Specifies the CPU, memory, and optional execution budgets requested for a worker allocation.

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

> **Example**
>
> Request `cpu_millicores = 2000` and `memory_bytes = 2147483648` for a two-CPU, 2 GiB worker. The compute provider must be able to supply it.

### `submission_options.compute_requirements.cpu_millicores`

Sets the requested CPU capacity. A value of 1000 means one CPU.

* **Default:** Set when used
* **Type:** integer; positive

> **Example**
>
> `2000` requests two CPUs; `500` requests half a CPU. This is the allocation request, not a command to resize the controller.

### `submission_options.compute_requirements.memory_bytes`

Sets the memory requested for one worker allocation.

* **Default:** Set when used
* **Type:** integer (bytes); positive

> **Example**
>
> `2147483648` requests 2 GiB. For Kubernetes, the provider uses the allocation when setting the worker container’s memory request and limit.

### `submission_options.max_attempts`

Limits how many execution attempts may be made for a task.

* **Default:** Unset
* **Type:** integer; positive; optional

> **Example**
>
> `3` allows up to three task attempts. An uncertain write still needs its saved outcome checked before another write attempt can be made.

### `submission_options.missed_run_policy`

Chooses what happens to scheduled occurrences that were missed.

* **Default:** Unset
* **Type:** choice: `RunOnce`, `RunAll`, `Skip`; optional

> **Example**
>
> If three scheduled times passed while the service was unavailable, `RunOnce` catches up once, `RunAll` considers all three, and `Skip` ignores them.

### `submission_options.overlap_policy`

Chooses what happens when a scheduled run is due while an earlier run is still active.

* **Default:** Unset
* **Type:** choice: `Wait`, `Skip`, `Allow`; optional

> **Example**
>
> `Wait` queues the next run, `Skip` ignores that overlapping occurrence, and `Allow` permits both runs to be active.

## Execution tuning

### `submission_options.compute_requirements.tuning`

Sets detailed execution budgets within an allocation’s CPU and memory.

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

> **Example**
>
> For a two-CPU worker, set `threads = 2` and explicit query, buffer, and spill budgets here. Omitted tuning values are calculated from the allocation.

### `submission_options.compute_requirements.tuning.threads`

Chooses how many execution threads one task may use within its assigned CPU allocation.

* **Default:** Unset
* **Type:** integer; positive; optional

> **Example**
>
> For a task allocated 2000 millicores, `2` allows two execution threads. Leave it unset to derive a value from the allocation; setting more threads does not allocate more CPUs.

### `submission_options.compute_requirements.tuning.query_memory_bytes`

Sets how much of a worker’s allocated memory may be used by the query engine.

* **Default:** Unset
* **Type:** integer (bytes); positive; optional

> **Example**
>
> On a 2 GiB worker, `1073741824` reserves a 1 GiB query budget. Leave room for connector buffers and process overhead; this budget cannot exceed 80% of the allocation.

### `submission_options.compute_requirements.tuning.buffer_bytes`

Sets the memory budget used for task data buffers.

* **Default:** Unset
* **Type:** integer (bytes); positive; optional

> **Example**
>
> `67108864` gives a 64 MiB buffer budget. It must fit alongside query memory and the configured number of output buffers.

### `submission_options.compute_requirements.tuning.batch_rows`

Sets how many rows may be handled in one reader batch.

* **Default:** Unset
* **Type:** integer; positive; optional

> **Example**
>
> `65536` reads up to 65,536 rows per batch when this setting is omitted. Smaller batches can reduce memory held at once; the maximum is 1048576.

### `submission_options.compute_requirements.tuning.write_batch_rows`

Sets the maximum rows per sink batch independently of reader batches. The executor also limits batching by its byte budget. One oversized input value may need a larger buffer.

* **Default:** Unset; resolves to 65536
* **Type:** integer; positive; at most 1048576; optional

### `submission_options.compute_requirements.tuning.write_parallelism`

Sets the number of worker-local Iceberg file writers. Writers use bounded queues and share a memory budget. All writers must finish before one Iceberg commit publishes their files.

* **Default:** Unset; resolves to execution threads
* **Type:** integer; positive; must not exceed execution threads; optional

> **Example**
>
> On a four-core worker, `write_parallelism: 4` allows four file writers. Each writer can encode and upload while the other writers continue. A one-core worker defaults to one writer.

### `submission_options.compute_requirements.tuning.spill_bytes`

Limits task data temporarily written to disk when execution needs it.

* **Default:** Unset
* **Type:** integer (bytes); optional

> **Example**
>
> `8589934592` gives an 8 GiB task spill budget. Zero disables task spill, while an omitted value is calculated from allocation memory.

### `submission_options.compute_requirements.tuning.output_buffer_batches`

Limits how many output batches wait for the next consumer.

* **Default:** Unset
* **Type:** integer; positive; optional

> **Example**
>
> `2` allows two batches to wait. Raising this can keep more data in memory; task tuning allows at most 32.

## Settings

### `max_session_bytes`

Limits how much saved session state one session may contain.

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

> **Example**
>
> `16777216` gives one saved session record a 16 MiB budget. Large uploaded artifacts have their own limits below.

### `max_history_page_size`

Limits how many past SQL operations one session-history response may return.

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

> **Example**
>
> `100` returns long operation histories over pages of at most 100 entries.

## Uploaded artifacts

### `max_artifact_bytes`

Limits the total size of one artifact uploaded into a session.

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

> **Example**
>
> `268435456` allows an artifact up to 256 MiB. The artifact may be uploaded as several smaller chunks.

### `max_artifact_chunk_bytes`

Limits the bytes in one chunk of a session artifact upload.

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

> **Example**
>
> `4194304` allows a 4 MiB upload chunk. A 20 MiB artifact would need several chunks.

### `max_artifact_chunks`

Limits how many chunks one uploaded artifact can contain.

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

> **Example**
>
> `4096` caps the chunk count even when each chunk is small. The total artifact byte limit still applies.

## Resource overrides

Session submission fields are optional overrides. An empty `[session.submission_options]` leaves workload defaults in control. If a resource object is supplied, include its required CPU and memory fields. Tuning fields within it remain optional.


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