SQL sessions

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