docs(backfill): document null date_partition_parameter without depends_on_past

[kbammarito]

Description

What

Adds two rows to the backfill capability matrix in docs/cookbooks/backfilling_a_table.md for a day-partitioned table with an explicit date_partition_parameter: null and no depends_on_past — a config the matrix didn't cover:

• offset 0 (default) → target is the whole table, so each date WRITE_TRUNCATEs everything; must be backfilled single-date (multi-date leaves only the last run). e.g. cohort_daily_churn_v1.
• non-zero date_partition_offset → each run targets one shifted partition (run_date + offset), so multi-date is correct. e.g. clients_first_seen_28_days_later_v1.

Why

A multi-date backfill on the offset-0 case silently rewrites the whole table per date with no error (hit on DENG-11021). Docs-only.

Related Tickets & Documents

Reviewer, please follow this checklist

[github-actions]

This PR adds two rows to the backfill capability matrix in docs/cookbooks/backfilling_a_table.md, covering day-partitioned tables with an explicit date_partition_parameter: null and no depends_on_past — one for the default offset 0, one for a non-zero date_partition_offset.

I verified the referenced example tables' metadata (cohort_daily_churn_v1, clients_first_seen_28_days_later_v1, rolling_cohorts_v2) and the underlying logic in date_range.py, query.py, and backfill.py. The non-zero-offset row is accurate for the managed workflow. My one finding concerns the offset-0 row: the behavior it describes belongs to bqetl query backfill, not the managed bqetl backfill workflow this matrix documents — details inline.

[github-actions]

issue: This row describes the wrong command for this matrix. The matrix intro scopes it to the managed workflow ("The managed backfill workflow (bqetl backfill create / initiate)..."), but the managed workflow cannot complete this config at all — not even single-date. During complete, _copy_backfill_staging_to_prod takes the per-partition branch for a day-partitioned table (partitioning_type is DAY, not None), calls get_backfill_partition(date, None, 0, DAY) which always returns None for a null param with offset 0 (date_range.py:95), and raises ValueError("Null partition found completing backfill") (backfill.py:1412-1423). This is not date-range dependent: the test test_copy_backfill_staging_to_prod_null_partition_param_without_override_raises (tests/cli/test_cli_backfill.py:3700) proves it raises with start_date == end_date.

The "WRITE_TRUNCATE the whole table per date, only the last run survives, so backfill single-date" behavior you describe is a property of the unmanaged bqetl query backfill command (query.py:516-525, --replace) — the DENG-11021 scenario — not of bqetl backfill. As written, a reader who follows this row (set start_date == end_date and run the managed backfill) will still hit Null partition found at complete.

Two things to fix: (1) ⚠️ elsewhere in this table means "override required" (an enforced gate); using it for an unenforced "single-date only" advisory overloads the symbol; and (2) the guidance should state that this config isn't completable via the managed workflow and that the single-date rule applies to bqetl query backfill. Note that cohort_daily_churn_v1's own backfill.yaml is a managed multi-date Initiate entry (DENG-11021) — exactly the entry the managed complete would reject.

[github-actions]

This PR adds two rows to the backfill capability matrix in docs/cookbooks/backfilling_a_table.md, covering a day-partitioned table with an explicit date_partition_parameter: null and no depends_on_past: offset 0 (whole-table WRITE_TRUNCATE, single-date only) and non-zero date_partition_offset (per-partition, multi-date safe).

I verified the technical claims against the code. get_backfill_partition (bigquery_etl/backfill/date_range.py:95) returns None — i.e. the whole-table destination — exactly when date_partition_parameter is None and date_partition_offset == 0, and a decorated $partition destination otherwise; resolve_date_partition_parameter defaults an omitted param to submission_date. The managed initiate flow replays the query per date over the entry range with no override for the plain offset-0 case, so the staging table is re-truncated per date, matching the "only the last run survives" claim. The three example tables' metadata.yaml all match their described configs. The claims are accurate; my one comment is a documentation-clarity suggestion about how the new ⚠️ row relates to the table's enforcement framing.

[github-actions]

suggestion: The ⚠️ in this row means something different from the other ⚠️ rows and it's worth making that explicit. The intro frames the table around what the tool enforces ("some are allowed only with an explicit override flag", and line 29: "The rejections are enforced by validate_table_metadata"), and the other ⚠️ rows are Override required — the backfill code stops you until you set a flag. This row is the opposite: a multi-date range on an offset-0 null-param table is not rejected — it runs without error and silently keeps only the last date (which is exactly the DENG-11021 footgun this PR documents). The note says "only the last run survives" but never states that the tool won't stop you, so a reader scanning the Allowed? column could reasonably assume this config is guarded like the Override required rows. Consider adding a few words to the note making the unenforced/silent nature explicit, e.g. "the backfill code does not reject a multi-date range here — it runs with no error and silently keeps only the last date."