Dify External Knowledge Integration#

RAGFlow exposes a Dify-compatible retrieval API that lets Dify treat any RAGFlow knowledge base as an external knowledge source. The integration is implemented in api/apps/restful_apis/dify_retrieval_api.py and is automatically registered with the Quart/Flask app via the dynamic blueprint loader in api/apps/__init__.py 1.

Endpoints#

The retrieval endpoint accepts both POST (JSON body) and GET (query string) 2. Required fields are knowledge_id and query; optional fields live under retrieval_setting 3.

Request Shape#

{
  "knowledge_id": "<kb_id>",
  "query": "user question",
  "use_kg": false,
  "retrieval_setting": {
    "top_k": 1024,
    "score_threshold": 0.0
  },
  "metadata_condition": {
    "logic": "and",
    "conditions": [
      { "name": "brand_name", "comparison_operator": "is", "value": "Pampers" }
    ]
  }
}

Response Shape#

The endpoint returns a records array where each item contains content, score, title, and a metadata object 4. The metadata always includes doc_id and document_id (the same value) — the latter is required by Dify's external retrieval contract 5.

Retrieval Logic#

The handler executes the following steps:

1. Auth & access control — Validates the API key and checks cross-tenant access 6.
2. Metadata pre-filter — If metadata_condition is present, calls meta_filter + convert_conditions from common/metadata_utils.py to compute a whitelist of matching doc_ids. If the filter produces no matches, a sentinel value ("-999") is passed so the retrieval returns zero results instead of bypassing the filter 7.
3. Vector retrieval — Calls settings.retriever.retrieval(...) with the embedding model configured on the KB, passing the doc_ids whitelist 8.
4. Child-chunk expansion — Optionally expands parent-level chunks to their children via retrieval_by_children 9.
5. Knowledge graph (KG) augmentation — If use_kg=true, a KG retrieval result is prepended to the ranked chunks 10.

Metadata Filtering#

Metadata filtering is handled in common/metadata_utils.py:

• convert_conditions normalizes Dify operator names (e.g. "is" → "=", "not is" → "≠", ">=" → "≥") before passing conditions to meta_filter.
• meta_filter filters document IDs in-memory across 14+ operators including equality, inequality, range (>, <, ≥, ≤), contains, in, empty, start with, end with. String comparisons are case-insensitive; date comparisons require strict YYYY-MM-DD format on both sides 11.

The logic key ("and" / "or") controls how multiple conditions are combined; it defaults to "and" 12.

Historical note: Prior to the metadata filtering implementation, metadata_condition was silently ignored and the API returned all documents regardless of filter values 13. This has since been fixed. See issue #8301 for historical context.

Go Backend Implementation#

A parallel production-ready Go implementation was added in PR #15704 (internal/handler/dify_retrieval_handler.go) and the metadata utilities were ported to Go in PR #15648 (internal/common/metadata_utils.go). The Go handler supports the same metadata_condition shape and uses a named sentinel (service.NoMatchDocIDSentinel) for no-match behavior 14.

Key Source Files#