Skip to content

feat: full_refresh_build config with prebuilt in-place rebuild path#750

Open
Benjamin-Knight wants to merge 1 commit into
dbt-msft:masterfrom
Benjamin-Knight:feat/full-refresh-build
Open

feat: full_refresh_build config with prebuilt in-place rebuild path#750
Benjamin-Knight wants to merge 1 commit into
dbt-msft:masterfrom
Benjamin-Knight:feat/full-refresh-build

Conversation

@Benjamin-Knight

Copy link
Copy Markdown
Collaborator

Adds a full_refresh_build model config offering a lower-disk full-refresh rebuild path. Builds on the indexes feature shipped in v1.10.1. Resolve #749

value behaviour
heap_then_index Default. Load as heap, swap, then build clustered design. Unchanged.
prebuilt Drop old table → recreate empty with final clustered design (CCI or clustered index) → INSERT WITH (TABLOCK). No intermediate copy, no swap → ~1x peak disk instead of ~2x.

Behaviour

  • Applies only under --full-refresh and on first builds; normal runs keep the configured refresh. Takes precedence over table_refresh_method: dml.
  • Drops the table, so {{ this }} self-references must be guarded by {% if is_incremental() %}; the adapter detects an unguarded self-reference in the compiled SQL and fails before dropping anything.
  • Trade-off: during a rebuild the target is empty/loading with no backup; a failure leaves an empty/partial table (recovery: rerun --full-refresh).
  • Full refreshes mark the target with a dbt_full_refresh_incomplete extended property until they complete, so a later normal incremental over a failed refresh errors instead of appending onto stale data.

Performance: parallel index build vs. serial insert (edition matters)

prebuilt swaps the default's post-load CREATE INDEX for an INSERT WITH (TABLOCK) into the existing index:

  • Enterprise: the post-load index build is parallel, so prebuilt (serial insert) can be slower on large tables — you pay build time for the disk win.
  • Non-Enterprise (Standard/Web/Express): the index build was serial anyway (parallel index ops are Enterprise-only), so prebuilt costs little/no extra time and is the clearer win.

The ~1x peak-disk benefit holds on every edition; only the time cost is edition-dependent.

Testing

  • tests/functional/adapter/mssql/test_full_refresh_build.py — 13 tests covering columnstore/rowstore/incremental/contract prebuilt paths, the self-reference guard, invalid-config-before-drop, and the incomplete-refresh marker.

Add a full_refresh_build model config. `prebuilt` rebuilds a table in
place - drop the old table, recreate it empty with its clustered design
(as_columnstore CCI or the clustered index from the indexes config), then
bulk-load via INSERT WITH (TABLOCK). No intermediate copy or rename swap,
so peak rebuild disk is ~1x instead of ~2x. Default heap_then_index is
unchanged.

- Applies only under --full-refresh and on first builds; normal runs keep
  the configured refresh. Takes precedence over table_refresh_method: dml.
- Drops the table, so {{ this }} self-references must be guarded by
  is_incremental(); the adapter fails on an unguarded self-reference
  before dropping anything.
- Full refreshes mark the target with a dbt_full_refresh_incomplete
  extended property until they complete, so a later normal incremental
  over a failed refresh errors instead of appending onto stale data.

Builds on the indexes feature shipped in v1.10.1.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Lower peak disk during full-refresh rebuilds of large columnstore/clustered tables

1 participant