On this page

Presets

A preset is a YAML file in the project’s presets/ directory that supplies default configuration merged into actions by type. A flowgroup or template applies presets by listing their names under presets:; presets are merged in list order. A preset file has the shape:

name: <preset_name>
version: "1.0"
extends: <parent_preset_name>
description: <text>
defaults:
  load_actions:
    <source_type>:
      ...
  transform_actions:
    <transform_type>:
      ...
  write_actions:
    <target_type>:
      ...

See also

Guide: Apply shared defaults with a preset. Concept: Choosing a reuse tool.

Top-level fields

Field

Type

Required

Default

Description

name

string

Yes

—

Preset identifier. Flowgroups and templates reference the preset by this name.

version

string

No

"1.0"

Version string for the preset.

extends

string

No

—

Name of a parent preset. This preset’s defaults are merged over the parent’s resolved defaults.

description

string

No

—

Free-text description of the preset.

defaults

mapping

No

—

Default configuration keyed by action type (see below).

defaults keys

Each key under defaults supplies defaults merged into matching actions by their type and sub-type.

Key

Matches

Merge target

load_actions.<source_type>

Load actions whose source.type equals <source_type> (e.g. cloudfiles, delta, jdbc).

Deep-merged into the action’s source mapping.

transform_actions.<transform_type>

Transform actions whose transform_type equals <transform_type> (e.g. sql, python).

Merged into the action’s top-level fields.

write_actions.<target_type>

Write actions whose write_target.type equals <target_type> (e.g. streaming_table, materialized_view).

Deep-merged into the action’s write_target mapping. A schema_suffix value is appended to the target schema.

defaults

The flowgroup itself.

Each key sets a flowgroup-level field default.

Precedence and current limitations

Parent extends settings are merged first, then the child preset. Presets listed on a template apply before presets listed on its flowgroup; within a list, later entries win conflicts. Dictionaries merge recursively, while lists and scalars replace earlier values.

For load actions, the resolved preset overrides conflicting values in source. For writes it overrides write_target. For example, an action’s source.options.cloudFiles.maxFilesPerTrigger: 50 becomes 200 when its preset sets that same option to 200. Use a later preset to override a shared preset deliberately; check the generated result.

The current resolver fills transform and flowgroup defaults only when a key is absent from the serialised model. Supported model fields are already present, even when their value is null, so those defaults do not fill omitted transform or flowgroup fields. Set those fields explicitly in the action or flowgroup. This differs from the merge used for load and write mappings.

Preset-level operational_metadata selection is read separately; use an explicit list of column names. See Operational metadata.

Example

name: bronze_defaults
version: "1.0"
description: "Standard bronze-layer defaults"
defaults:
  load_actions:
    cloudfiles:
      options:
        cloudFiles.schemaEvolutionMode: addNewColumns
  write_actions:
    streaming_table:
      table_properties:
        quality: bronze

A preset may build on another with extends:

name: bronze_cloudfiles
version: "1.0"
extends: bronze_defaults
defaults:
  load_actions:
    cloudfiles:
      options:
        cloudFiles.maxFilesPerTrigger: 200