schema-field-selection

Field Selection for Materializations

Control which fields are included or excluded in materializations using depth modes and field overrides.

Docs: https://docs.estuary.dev/guides/customize-materialization-fields/

When to Use

• Reduce table width by excluding unnecessary fields
• Include deeply nested fields that aren't selected by default
• Exclude sensitive fields from materializations (note: data still exists in the collection — for true PII protection, use redaction on the writeSchema instead)
• Override connector's default field recommendations

Procedure

Step 1: Pull the Materialization Spec

flowctl catalog pull-specs --name <materialization-name>

Step 2: Configure Field Selection

Add or modify the fields stanza in the binding:

bindings:
  - source: tenant/your/collection
    resource: { table: your_table }
    fields:
      recommended: true    # Depth mode (see below)
      require:             # Object — explicitly include fields
        deeply/nested/field: {}
        another_field: {}
      exclude:             # Array — explicitly exclude fields
        - sensitive_data
        - debug_info

Note: require is an object (field: {}), exclude is an array (- field).

Note: Each connector marks certain fields as required — typically the root document (flow_document) and the collection-key components, and some connectors require additional fields (e.g., CDC-style materializations that depend on _meta/op). Attempting to exclude a connector-required field returns a LOCATION_REQUIRED / FIELD_REQUIRED constraint and the publish fails. The exact list comes from each connector's Validate response.

Depth Modes

The recommended setting controls how deeply nested fields are automatically selected. UI labels are in parentheses:

Value	UI Label	Description
0	Required Only	Selects only fields the connector marks required (root document + key components, plus any connector-specific required fields)
1	Depth 1 (default)	Top-level scalar fields
2	Depth 2	Two levels of nesting
true	Unlimited Depth	All scalar fields at any depth