Engine configuration

Coral reads engine settings from config.toml in the local state directory. See Local state for the default location and the CORAL_CONFIG_DIR override.

Memory

Use [engine.memory] to cap query-engine memory retained by DataFusion and Coral-owned operators such as dependent joins.

[engine.memory]
limit = "2Gi"

Key	Type	Default	Description
`limit`	string or integer	unset	Optional engine-wide query memory limit.

String limits must use binary units: Ki, Mi, Gi, or Ti. Integer limits are interpreted as bytes. The limit must be greater than zero.

Dependent joins

Dependent joins let Coral rewrite eligible SQL joins into dependent predicate pushdown, so join-key values from one side can be sent as filters to an HTTP-backed source. The default settings live under [engine.dependent_join].

[engine.dependent_join]
enabled = true
max_bindings = 500
max_resolver_rows = 10000
max_rows_per_binding = 1000
max_resolver_rows_per_binding = 1000
max_concurrency = 8

Key	Type	Default	Description
`enabled`	boolean	`true`	Enables the dependent-join optimizer rule globally.
`max_bindings`	integer	`500`	Maximum distinct join-key combinations Coral will push to an upstream API.
`max_resolver_rows`	integer	`10000`	Maximum rows read from the key-supplying side before Coral falls back.
`max_rows_per_binding`	integer	`1000`	Maximum rows accepted from one dependent upstream request.
`max_resolver_rows_per_binding`	integer	`1000`	Maximum key-supplying rows allowed for one join-key combination.
`max_concurrency`	integer	`8`	Concurrent upstream requests issued by one dependent join.

All numeric limits must be greater than zero.

Per-source overrides

Use [engine.dependent_join.per_source.<source>] to override any dependent-join setting for one source. Unspecified keys inherit the global value.

[engine.dependent_join]
enabled = false
max_concurrency = 8
max_bindings = 500

[engine.dependent_join.per_source.github]
enabled = true
max_concurrency = 4
max_bindings = 200

[engine.dependent_join.per_source.linear]
enabled = false

Per-source overrides use the installed source name, which is the SQL schema name before the table. In the example above, github applies to joins that read from tables such as github.pull_requests. Precedence is:

per-source override
global [engine.dependent_join] value
Coral’s built-in default

Table-level overrides are not supported.

Get started

Guides

Reference

Project

Engine configuration

Memory

Dependent joins

Per-source overrides

​Memory

​Dependent joins

​Per-source overrides

Memory

Dependent joins

Per-source overrides