Docs update to reflect return_failures changes

Author: drobison00

README.md

@@ -172,12 +172,17 @@ ingestor = (
 
 print("Starting ingestion..")
 t0 = time.time()
-results = ingestor.ingest(show_progress=True)
+# Return both successes and failures so you can inspect partial errors without stopping uploads
+results, failures = ingestor.ingest(show_progress=True, return_failures=True)
 t1 = time.time()
 print(f"Time taken: {t1 - t0} seconds")
 
 # results blob is directly inspectable
 print(ingest_json_results_to_blob(results[0]))
+
+# (optional) Review any failures that were returned
+if failures:
+    print(f"There were {len(failures)} failures. Sample: {failures[0]}")
 ```
 
 You can see the extracted text that represents the content of the ingested test document.
@@ -284,6 +289,14 @@ So, according to this whimsical analysis, both the **Giraffe** and the **Cat** a
 >
 > Please also checkout our [demo using a retrieval pipeline on build.nvidia.com](https://build.nvidia.com/nvidia/multimodal-pdf-data-extraction-for-enterprise-rag) to query over document content pre-extracted w/ NVIDIA Ingest.
 
+> [!IMPORTANT]
+> About `return_failures`
+>
+> - `ingestor.ingest(..., return_failures=False)` (default): returns only successful results. Any failed jobs are omitted from the return value and are logged. If you have configured `.vdb_upload(...)` and any failures are present, `ingest()` will raise a `RuntimeError` and will NOT upload. This preserves the previous all-or-nothing bulk upload behavior.
+> - `ingestor.ingest(..., return_failures=True)`: returns a tuple `(results, failures)`. If `.vdb_upload(...)` is configured and some jobs failed, `ingest()` will still proceed to upload only the successful results to your vector database and will not raise. You can then inspect `failures` to decide whether to retry or remediate.
+>
+> This makes `return_failures=True` ideal for large batches where you want successful chunks/pages to be committed while still collecting detailed diagnostics for anything that didn’t complete.
+
 
 ## GitHub Repository Structure
 

docs/docs/extraction/data-store.md

@@ -21,6 +21,25 @@ It does not store the embeddings for images.
 NeMo Retriever extraction supports uploading data by using the [Ingestor.vdb_upload API](nv-ingest-python-api.md). 
 Currently, data upload is not supported through the [NV Ingest CLI](nv-ingest_cli.md).
 
+### Partial Failures and Upload Semantics
+
+When chaining `.vdb_upload(...)` on an `Ingestor`, upload behavior depends on the `return_failures` flag passed to `ingest()`:
+
+- `return_failures=False` (default): If any ingestion jobs fail, `ingest()` raises a `RuntimeError` and no upload occurs (all-or-nothing).
+- `return_failures=True`: `ingest()` returns `(results, failures)` and uploads only the successful results; it does not raise. Inspect `failures` and retry as needed.
+
+Example:
+
+```python
+results, failures = (
+    Ingestor(client=client)
+    .files(["doc1.pdf", "doc2.pdf"]).extract().embed()
+    .vdb_upload(collection_name="my_collection", milvus_uri="milvus.db")
+    .ingest(return_failures=True)
+)
+print(f"Uploaded {len(results)} successes; {len(failures)} failures")
+```
+
 
 
 ## Upload to Milvus

docs/docs/extraction/nv-ingest-python-api.md

@@ -115,7 +115,30 @@ For large document batches, you can enable a progress bar by setting `show_progr
 Use the following code.
 
 ```python
-result = ingestor.extract().ingest(show_progress=True)
+results, failures = ingestor.extract().ingest(show_progress=True, return_failures=True)
+print(len(results), "successful documents")
+if failures:
+    print("Failures:", failures[:1])
+```
+
+## Ingest Semantics with vdb_upload
+
+If you chain `.vdb_upload(...)` on the `Ingestor`, uploads are performed after ingestion completes. Behavior depends on `return_failures`:
+
+- `return_failures=False` (default): If any jobs fail, `ingest()` raises a `RuntimeError` and does not upload (all-or-nothing).
+- `return_failures=True`: `ingest()` returns `(results, failures)` and uploads only the successful results; it does not raise. You can inspect `failures` and retry selectively.
+
+Example:
+
+```python
+ingestor = (
+    Ingestor(client=client)
+    .files(["/path/doc1.pdf", "/path/doc2.pdf"]).extract().embed()
+    .vdb_upload(collection_name="my_collection", milvus_uri="milvus.db")
+)
+
+results, failures = ingestor.ingest(return_failures=True)
+print(f"Uploaded {len(results)} successful docs; {len(failures)} failures")
 ```
 
 

docs/docs/extraction/quickstart-guide.md

@@ -179,17 +179,24 @@ ingestor = (
 )
 print("Starting ingestion..")
 t0 = time.time()
-results = ingestor.ingest()
+results, failures = ingestor.ingest(return_failures=True)
 t1 = time.time()
 print(f"Time taken: {t1-t0} seconds")
 # results blob is directly inspectable
 print(ingest_json_results_to_blob(results[0]))
+if failures:
+    print(f"There were {len(failures)} failures. Sample: {failures[0]}")
 ```
 
 !!! note
 
     To use library mode with nemoretriever_parse, uncomment `extract_method="nemoretriever_parse"` in the previous code. For more information, refer to [Use Nemo Retriever Extraction with nemoretriever-parse](nemoretriever-parse.md).
 
+!!! important "About return_failures and vdb_upload"
+
+    - `ingestor.ingest(..., return_failures=False)` (default): returns only successful results. If `.vdb_upload(...)` is configured and any jobs fail, `ingest()` raises `RuntimeError` and does not upload (all-or-nothing).
+    - `ingestor.ingest(..., return_failures=True)`: returns `(results, failures)`. If `.vdb_upload(...)` is configured and some jobs fail, `ingest()` uploads only the successful results and does not raise; inspect `failures` for remediation.
+
 
 ```
 Starting ingestion..

docs/docs/extraction/quickstart-library-mode.md

@@ -131,18 +131,25 @@ ingestor = (
 
 print("Starting ingestion..")
 t0 = time.time()
-results = ingestor.ingest(show_progress=True)
+results, failures = ingestor.ingest(show_progress=True, return_failures=True)
 t1 = time.time()
 print(f"Time taken: {t1 - t0} seconds")
 
 # results blob is directly inspectable
 print(ingest_json_results_to_blob(results[0]))
+if failures:
+    print(f"There were {len(failures)} failures. Sample: {failures[0]}")
 ```
 
 !!! note
 
     To use library mode with nemoretriever_parse, uncomment `extract_method="nemoretriever_parse"` in the previous code. For more information, refer to [Use Nemo Retriever Extraction with nemoretriever-parse](nemoretriever-parse.md).
 
+!!! important "About return_failures and vdb_upload"
+
+    - `ingestor.ingest(..., return_failures=False)` (default): returns only successful results. If `.vdb_upload(...)` is configured and any jobs fail, `ingest()` raises `RuntimeError` and does not upload (all-or-nothing).
+    - `ingestor.ingest(..., return_failures=True)`: returns `(results, failures)`. If `.vdb_upload(...)` is configured and some jobs fail, `ingest()` uploads only the successful results and does not raise; inspect `failures` for remediation.
+
 You can see the extracted text that represents the content of the ingested test document.
 
 ```shell