Enterprise only
A Function refresh can encounter a bad row, fail to initialize a model, lose
a worker, or fail while publishing results. These need different remedies.
This guide uses the existing refresh error policy
and Python error records; it does not require a new retry or quarantine API.
Choose a row-error policy
The defaultskip writes null outputs for failed rows and records errors,
subject to the refresh’s failure limits, 5% of evaluated rows unless set.
fail stops the job on a row error:
skip does not make initialization,
infrastructure or publication failures successful. If wait() raises,
refresh the job record, inspect job.failure, and
inspect any recorded row errors. A failed/cancelled job can have committed
some output, but retention of every successful call is not guaranteed.
External effects are not rolled back and can be repeated during recovery.
Inspect and group recorded errors
Scope diagnostics to the job you are investigating:attempts and traceback
details depend on the server/image version. This client-side grouping counts
only returned detail records. truncated=True or fragment summaries with
more skipped than recorded rows mean it is incomplete; do not label it a full
error census. See SHOW ERRORS for SQL and its limits.
Records are historical observations, not a deduplicated list of currently
failed rows. Reading errors without job_id can include older attempts that
have since succeeded. A null output can mean unfilled, skipped, or a computed
nullable field; output nullness alone is not a current-error test.
Retry exactly identified rows
On tables with stable row IDs, supporting server/SDK versions returnrecord.row_id from the refresh’s pinned source version. Keep that table and
branch identity with the records. Compaction can move physical addresses, so
do not derive a row ID from fragment numbers or offsets.
The following deliberately refuses incomplete or unidentified error sets.
Review historical records against the current inputs before using them as a
retry selection. Keep this selection small enough for a SQL predicate.
_rowaddr after a rewrite.
Python where= requires the Enterprise client, not stable
0.41.0, plus a matching server.
Repair with a newer Function
Registering a new version does not change an existing column’s immutable binding. To evaluate a fix while retaining old outputs, register the corrected callable and declare a separate output column. For example, with a correctedembed_fixed callable already defined and a text input column:
Quarantine inputs for review
Use an application-owned table of source table/branch, recorded table version, stable row ID or business key, Function version, cause and review disposition. Keep Blob payloads in the source table; a quarantine entry can refer to their source identity. Choose an ordinary table name such asfunction_quarantine,
and explicitly exclude its reviewed IDs in subsequent input selections.
Quarantine is an application workflow here: there is no implied built-in
quarantine lifecycle, automatic current-error clearing or exactly-once retry.
Do not delete source rows merely to hide an error. For very large failure sets,
bounded error listings cannot select every row; use a smaller reviewed scope
or wait for a deployment with the required complete selection support.
Native retry policies, full current-error summaries, in-place version upgrades
and materialized-view row-error handling have separate server/SDK prerequisites.
Do not apply REFRESH COLUMN options to a materialized view and assume the
same policy; consult the MV refresh reference
for your deployment’s accepted options.