From 77577b606a63207f992696d79b9fd9c357de3bd3 Mon Sep 17 00:00:00 2001
From: importcpp <57519936+importcpp@users.noreply.github.com>
Date: Sun, 27 Sep 2026 21:30:49 +0800
Subject: [PATCH] docs(python): document streaming transform fill

---
 docs/src/python/python.md | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/docs/src/python/python.md b/docs/src/python/python.md
index ccc44a55e..e003c5ff1 100644
--- a/docs/src/python/python.md
+++ b/docs/src/python/python.md
@@ -367,6 +367,27 @@ still work. Queries return descriptors. Call
 
 ::: lancedb.streaming.StreamingDataset
 
+When a transform fails for some rows, fill mode replaces each failed row in place:
+
+```python
+dataset = StreamingDataset(
+    table,
+    num_splits=8,
+    transform=transform,
+    on_transform_error="fill",
+    fill_value={"id": -1, "vector": [0.0, 0.0]},
+)
+for row in dataset:
+    train(row)
+print(dataset.rows_filled)
+```
+
+The placeholder must have the same structure as a successful transform output.
+Pass `repair(exc, row_batch) -> row` instead of `fill_value` to construct a
+replacement from the failed one-row Arrow batch. Keep the repair deterministic
+when using elastic training or checkpoints. Fill mode preserves split lengths
+and sample positions.
+
 ::: lancedb.streaming.StreamingDataLoader
 
 ::: lancedb.permutation.permutation_builder