Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

docs(examples): add document lifecycle API examples (#19153)

Sbaaoui Idriss2cbd50991be1
diff --git a/example/http/document_example.sh b/example/http/document_example.sh
new file mode 100644
index 0000000000..c714281e69
--- /dev/null
+++ b/example/http/document_example.sh
@@ -0,0 +1,47 @@
+#!/bin/bash
+set -euo pipefail
+
+HOST_ADDRESS="${RAGFLOW_HOST_ADDRESS:-http://localhost:9380}"
+API_KEY="${RAGFLOW_API_KEY:-ragflow-IzZmY1MGVhYTBhMjExZWZiYTdjMDI0Mm}"
+
+command -v jq >/dev/null || { echo "jq is required" >&2; exit 1; }
+TEMP_FILE=$(mktemp)
+DATASET_ID=""
+DOC_ID=""
+cleanup() {
+ rm -f "$TEMP_FILE"
+ [ -n "$DOC_ID" ] && curl -fsS -X DELETE "$HOST_ADDRESS/api/v1/datasets/$DATASET_ID/documents" \
+ -H 'Content-Type: application/json' -H "Authorization: Bearer $API_KEY" \
+ -d "{\"ids\":[\"$DOC_ID\"]}" >/dev/null || true
+ [ -n "$DATASET_ID" ] && curl -fsS -X DELETE "$HOST_ADDRESS/api/v1/datasets" \
+ -H 'Content-Type: application/json' -H "Authorization: Bearer $API_KEY" \
+ -d "{\"ids\":[\"$DATASET_ID\"]}" >/dev/null || true
+}
+trap cleanup EXIT
+printf '%s\n' 'RAGFlow is an open-source RAG engine.' >"$TEMP_FILE"
+
+DATASET_ID=$(curl -fsS -X POST "$HOST_ADDRESS/api/v1/datasets" \
+ -H 'Content-Type: application/json' -H "Authorization: Bearer $API_KEY" \
+ -d '{"name":"document_http_example"}' | jq -er '.data.id')
+DOC_ID=$(curl -fsS -X POST "$HOST_ADDRESS/api/v1/datasets/$DATASET_ID/documents" \
+ -H "Authorization: Bearer $API_KEY" -F "file=@$TEMP_FILE;filename=sample.txt" | jq -er '.data[0].id')
+
+curl -fsS "$HOST_ADDRESS/api/v1/datasets/$DATASET_ID/documents?id=$DOC_ID" \
+ -H "Authorization: Bearer $API_KEY" | jq .
+curl -fsS -X PATCH "$HOST_ADDRESS/api/v1/datasets/$DATASET_ID/documents/$DOC_ID" \
+ -H 'Content-Type: application/json' -H "Authorization: Bearer $API_KEY" \
+ -d '{"name":"renamed_sample.txt"}' | jq .
+curl -fsS -X POST "$HOST_ADDRESS/api/v1/datasets/$DATASET_ID/documents/parse" \
+ -H 'Content-Type: application/json' -H "Authorization: Bearer $API_KEY" \
+ -d "{\"document_ids\":[\"$DOC_ID\"]}" | jq .
+for _ in $(seq 1 60); do
+ STATUS=$(curl -fsS "$HOST_ADDRESS/api/v1/datasets/$DATASET_ID/documents?id=$DOC_ID" \
+ -H "Authorization: Bearer $API_KEY" | jq -er '.data.docs[0].run')
+ echo "Parsing status: $STATUS"
+ case "$STATUS" in
+ DONE|3) break ;;
+ FAIL|4|CANCEL|2) echo "Parsing ended with status $STATUS" >&2; exit 1 ;;
+ esac
+ sleep 2
+done
+case "$STATUS" in DONE|3) ;; *) echo "Parsing timed out" >&2; exit 1 ;; esac
diff --git a/example/sdk/document_example.py b/example/sdk/document_example.py
new file mode 100644
index 0000000000..9fcef53597
--- /dev/null
+++ b/example/sdk/document_example.py
@@ -0,0 +1,34 @@
+"""Manage a document through its dataset lifecycle with the Python SDK."""
+
+import os
+
+from ragflow_sdk import RAGFlow
+
+HOST_ADDRESS = os.environ.get("RAGFLOW_HOST_ADDRESS", "http://127.0.0.1:9380")
+API_KEY = os.environ.get("RAGFLOW_API_KEY", "ragflow-IzZmY1MGVhYTBhMjExZWZiYTdjMDI0Mm")
+
+
+rag = RAGFlow(api_key=API_KEY, base_url=HOST_ADDRESS)
+dataset = rag.create_dataset(name="document_example_dataset")
+document = None
+try:
+ documents = dataset.upload_documents([{"display_name": "sample.txt", "blob": b"RAGFlow is an open-source RAG engine.\n"}])
+ document = documents[0]
+ print(f"Uploaded {document.name} (id={document.id})")
+
+ listed = dataset.list_documents(id=document.id)
+ document = listed[0]
+ print(f"Listed {document.name} (run={document.run})")
+
+ document.update({"name": "renamed_sample.txt"})
+ print(f"Renamed document to {document.name}")
+
+ statuses = dataset.parse_documents([document.id])
+ status = next(item for item in statuses if item[0] == document.id)
+ if str(status[1]).upper() != "DONE":
+ raise RuntimeError(f"Parsing failed: {status[1]}")
+ print(f"Parsing completed: {status[2]} chunks, {status[3]} tokens")
+finally:
+ if document is not None:
+ dataset.delete_documents(ids=[document.id])
+ rag.delete_datasets(ids=[dataset.id])