Hi @bravecharge! I'm Dosu and I’m helping the ragflow team.

@bravecharge — By design, meta_fields are not included in chunk retrieval results by default. They're stored at the document level (in dedicated per-tenant indexes like ragflow_doc_meta_{tenant_id}) rather than at the chunk level [1]. So the core retrieval pipeline returns chunks without meta_fields attached.

How to access meta_fields during recall:

• Dify-compatible retrieval API (/api/apps/sdk/dify_retrieval) is the one endpoint that explicitly fetches the document object for each chunk and includes meta_fields in the response metadata [2]. If you're integrating via Dify, you'll get them automatically.
• Standard retrieval — you'd need to take the doc_id from each returned chunk and fetch the document separately (e.g., via GET /datasets/{dataset_id}/documents/{document_id}) to access its meta_fields.

v0.25.0 metadata bugs: This version had several metadata-related regressions — including a persistence bug where newly added metadata wouldn't save [3] and a KeyError: 'properties' crash during metadata generation [4]. These have all been fixed. If you're on v0.25.0, upgrading to v0.25.1 (released April 29, 2026) or the nightly Docker image should resolve those issues.

If you need meta_fields returned directly in the standard recall results (without a separate document fetch), that's currently not supported out of the box — it would require a code change to the retrieval pipeline.

To reply, just mention @dosu.

Docs are dead. Just use Dosu.

@bravecharge Here is a complete breakdown of how meta_fields work during the recall/retrieval process in RAGFlow and how you can access them:

Why meta_fields are missing from standard retrieval chunks

By design, RAGFlow stores meta_fields at the Document level (in dedicated tenant indexes like ragflow_doc_meta_{tenant_id}), rather than embedding them directly into individual chunk records (ragflow_chunk_*).

Because of this separation, standard vector search / retrieval endpoints (POST /api/v1/retrieval) return chunk objects containing doc_id, content, and similarity scores — but without the full document meta_fields object attached by default.

3 Ways to Retrieve meta_fields During Recall

Method 1: Use the Dify-Compatible Retrieval Endpoint (Automatic)

The Dify-compatible retrieval API (POST /api/apps/sdk/dify_retrieval) automatically joins each retrieved chunk with its parent document and populates meta_fields in the response:

curl -X POST "http://<YOUR_RAGFLOW_HOST>/api/apps/sdk/dify_retrieval" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "knowledge_id": "<DATASET_ID>",
    "query": "Your search query",
    "retrieval_setting": {
      "top_k": 5,
      "score_threshold": 0.5
    }
  }'

Response JSON will include the document metadata inside each result item.

Method 2: Python SDK Document Join (Post-Recall)

If you are using the ragflow_sdk in Python, you can fetch meta_fields by doing a single batch query for the returned doc_ids:

from ragflow_sdk import RAGFlow

rag = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_RAGFLOW_HOST>")
dataset = rag.get_dataset(id="<DATASET_ID>")

# 1. Perform retrieval
chunks = dataset.retrieve(question="Your query", top_k=5)

# 2. Extract unique document IDs from chunks
doc_ids = list(set([chunk.doc_id for chunk in chunks]))

# 3. Retrieve document metadata dictionary
docs = dataset.list_documents(id=doc_ids)
doc_meta_map = {doc.id: doc.meta_fields for doc in docs}

# 4. Access meta_fields for each chunk
for chunk in chunks:
    chunk_meta = doc_meta_map.get(chunk.doc_id, {})
    print(f"Chunk: {chunk.content[:50]}... | Meta: {chunk_meta}")

Method 3: Direct HTTP REST Document Metadata Batch Fetch

If calling the REST API directly:

1. Call POST /api/v1/datasets/{dataset_id}/retrieval to get your chunks.
2. Collect the doc_id list from the response.
3. Call GET /api/v1/datasets/{dataset_id}/documents?id=<doc_id1>,<doc_id2> to retrieve the document details containing meta_fields.

Note for v0.25.0 Users

If you updated meta_fields on v0.25.0 and they appear empty or missing:

• v0.25.0 contained a known regression where newly added metadata wouldn't save persistently.
• Fix: Upgrade to v0.25.1+ (or the latest nightly docker image) where metadata index sync bugs have been resolved.

Summary Checklist

If this helps resolve your issue, please feel free to mark it as the accepted answer so others in the community can easily find it!