Document protected upsert download consumption guard

build-with-pinot/ingestion/upsert-and-dedup/upsert.md

@@ -847,7 +847,7 @@ Reconciliation:
 - Keys still pointing to replaced segment → revert to prior immutable location.
 - Keys without prior location → removed.
 - Un reconcilable keys → logged, and metrics emitted for the user to take action.
-Make sure ParallelSegmentConsumptionPolicy is always ∈ {`DISALLOW_ALWAYS`, `ALLOW_DURING_BUILD_ONLY`}.
+For these tables, use `DISALLOW_ALWAYS` for `parallelSegmentConsumptionPolicy` when a segment download may revert metadata. `ALLOW_DURING_BUILD_ONLY` is accepted only with pauseless consumption; without pauseless consumption, a failed local build can fall back to a download after the next segment starts consuming.
 
 #### UNSAFE
 
@@ -1085,7 +1085,7 @@ For partial upsert tables or tables with `dropOutOfOrderRecord=true` or `outOfOr
 | Mode | Description |
 |---|---|
 | `RESTRICTED` | *(Default)* Skips consuming-segment reload and rejects explicit force commit for partial-upsert tables and upsert tables with `dropOutOfOrderRecord` or `outOfOrderRecordColumn` configured. |
-| `PROTECTED` | Enables reloads/force commits with upsert metadata reversion during segment replacements. Requires `ParallelSegmentConsumptionPolicy` set to `DISALLOW_ALWAYS` or `ALLOW_DURING_BUILD_ONLY`. |
+| `PROTECTED` | Enables reloads/force commits with upsert metadata reversion during segment replacements. For partial-upsert tables and upsert tables with `dropOutOfOrderRecord` or `outOfOrderRecordColumn`, table-config validation rejects `ALLOW_ALWAYS`, `ALLOW_DURING_DOWNLOAD_ONLY`, and `ALLOW_DURING_BUILD_ONLY` without pauseless consumption. Use `DISALLOW_ALWAYS`; `ALLOW_DURING_BUILD_ONLY` is accepted with pauseless consumption. With no explicit policy, the deprecated `allowPartialUpsertConsumptionDuringCommit=true` flag is also rejected. |
 | `UNSAFE` | Allows reloads without metadata reversion. Use only if inconsistency is acceptable or handled externally. |
 
 > **Note:** This cluster config is distinct from the table-level `upsertConfig.consistencyMode` setting (SYNC / SNAPSHOT / NONE), which controls query-vs-upsert concurrency on a single server.

reference/configuration-reference/monitoring-metrics.md

@@ -25,6 +25,7 @@ Pinot provides metrics out of the box so that you can monitor every aspect of pe
 | REALTIME_UPSERT_INCONSISTENT_ROWS | Table-level count of unreplaced primary keys for upsert tables configured to drop or track out-of-order records (excluding partial upsert). | Meter |
 | FULL_UPSERT_KEYS_NOT_REPLACED | Table-level count of unreplaced primary keys for other full-upsert tables. | Meter |
 | UPSERT_METADATA_REVERT_FAILURES | Table-level meter counting protected upsert metadata revert failure events, not distinct segments. Alert on increases and inspect the `UPSERT_METADATA_REVERT_FAILED` server log for the affected table, partition, and segment; Pinot does not repair the metadata automatically. | Meter |
+| UPSERT_REVERT_WITH_CONSUMPTION_DURING_DOWNLOAD | Table-level meter incremented when the next segment can consume while a download replaces a segment and reverts its upsert metadata. This can leave the next segment's snapshot missing restored rows. Investigate the server error log and use `parallelSegmentConsumptionPolicy=DISALLOW_ALWAYS` for the affected table. | Meter |
 | LAST_REALTIME_SEGMENT_CREATION_DURATION_SECONDS | time in seconds it took for latest real-time segment to get created |  |
 | LAST_REALTIME_SEGMENT_CREATION_WAIT_TIME_SECONDS | time in seconds it took for segment creation to start (generally due to waiting for a lock to get acquired) |  |
 | LAST_REALTIME_SEGMENT_INITIAL_CONSUMPTION_DURATION_SECONDS | time in seconds spent consuming records for latest segment |  |