[Bug]: Add document meta_fields,but it cant't work when I converse with chat assistant

[wangjuu]

Self Checks

• I have searched for existing issues search for existing issues, including closed ones.
• I confirm that I am using English to submit this report (Language Policy).
• Non-english title submitions will be closed directly ( 非英文标题的提交将会被直接关闭 ) (Language Policy).
• Please do not modify this template :) and fill in all the required fields.

RAGFlow workspace code commit ID

4321e567

RAGFlow image version

infiniflow/ragflow:v0.23.1

Other environment information

Actual behavior

I update document to add meta_fields after upload a document,however,when i call the converse with chat assistant interface,even if i use metadata_condition for classification,it still retrieves other types of documents

Expected behavior

I want to distinguish documents based on the meta_fields,and be able to extract the text from the corresponding document when calling converse with chat assistant interface to answer questions,without involving other types of documents.

Steps to reproduce

The following interfaces were used in sequence
1.upload documents
2.update document->add meta_fields
meta_fields={
    "doc_type":"contract"
}
3.parse documents

4.converse with chat assistant->use metadata_condition
"metadata_condition":{
    "logic":"and",
    "condition":[
    {
        "name":"doc_type",
        "comparison_operator":"is",
        "value":"contract"
     }]
}

Additional information

No response

[dosubot]

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

This is a known issue in RAGFlow v0.23.1: filtering by meta_fields using metadata_condition during chat assistant conversations is unreliable due to backend bugs. Even with the correct filter structure and document metadata, the system may still retrieve documents of other types because the filtering logic does not always execute as intended in this version. This problem was fixed after v0.23.1—a bug fix for metadata updates and filtering was merged on 2026-01-26, which should resolve these issues in newer versions. Upgrading to a version after this fix is recommended for reliable metadata_condition filtering in chat assistant conversations (details).

If you cannot upgrade, possible workarounds include: ensuring all documents have the correct meta_fields set, using tags for filtering instead of metadata_condition, or updating each document individually after upload. However, these do not guarantee reliable filtering in v0.23.1 due to the underlying backend limitations (workaround reference). Also, updating meta_fields does not automatically trigger re-indexing or immediate reflection in retrieval indices in this version, which may contribute to the issue.

If you need more technical details or want to verify the fix in a newer version, let me know!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[wangjuu]

@dosu The current version being used is the official Docker image.How can i update the version using the source code?Could you provide a feasible update plan?

[dosubot]

To upgrade RAGFlow from the official Docker image (v0.23.1) and resolve the metadata filtering bug, you have two main options: update to a newer official Docker image or build/run from the latest source code. Here’s a feasible update plan:

1. Back up your data and configs: Save your data volumes and config files like /ragflow/conf/service_conf.yaml, docker/.env, and docker/service_conf.yaml.template. For extra safety, use docker/migration.sh to back up and restore Docker volumes if needed (reference).

2. Update using Docker (recommended for most users):

   • Edit docker/.env and set RAGFLOW_IMAGE to a newer tag, such as infiniflow/ragflow:nightly or a specific stable release after late 2025 (these include the metadata filtering fixes) (reference).
   • Run:

     docker compose -f docker/docker-compose.yml pull
     docker compose -f docker/docker-compose.yml up -d
     

   • Do not use down -v as this deletes your data volumes (reference).

3. Update using source code (if you want to build your own image):

   • Clone the repo:
     git clone https://github.com/infiniflow/ragflow.git
   • (Optional) Checkout a specific tag:
     git checkout <tag>
   • Build the Docker image:
     docker build --platform linux/amd64 -f Dockerfile -t infiniflow/ragflow:nightly .
   • Update docker/.env to use your new image tag.
   • Restart with Docker Compose as above (reference).

4. After upgrade:

   • Double-check your configs and data.
   • Test metadata filtering in chat assistant to confirm the bug is fixed.

If you have custom code, commit it to a separate branch before upgrading, then reapply your changes after the upgrade (reference).

Let me know if you need specific steps for a source-only (non-Docker) deployment or have custom plugins/configs to preserve.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[Magicbook1108]

dosu is correct on updating your code.

[wangjuu]

@dosu After updating to use Docker,i try to use converse with chat assistant again,it also show other irrelevant documents.Is chat assistant need additional configuration?
For example,is the metadata button for the chat assistant and dataset supposed to be turned on,and how to open it in the interface?
Or are there any other necessary configurations?

[dosubot]

No extra configuration is usually needed for metadata filtering in the chat assistant after upgrading, but a few things must be set up correctly:

• Metadata filtering only works if the relevant fields (like doc_type) are present in every document's meta_fields, and the filter field name matches exactly. If you batch-uploaded documents, update each one to include the correct metadata field details.
• In the chat assistant UI, there is a metadata filter section (sometimes shown as a toggle or button). You can open chat settings and look for "Metadata—Conditions" or similar. If your dataset has metadata fields, they will appear here for you to select and filter. If the options are empty, it means your documents don't have metadata fields defined yet details.
• In the dataset interface, you can manage metadata fields via the metadata management modal. There is a button to open metadata settings and switches to enable/disable built-in metadata fields. Make sure the fields you want to filter by are enabled code reference.
• Recent versions support interactive metadata filtering in the UI, including searching and direct modification of filter values PR #12585.
• There is no separate "chat-only" toggle for metadata filtering; once metadata is defined for a dataset, the backend will honor metadata_condition filters when retrieving chunks backend logic.
• Double-check your retrieval parameters (similarity threshold, top_k, rerank settings) in chat config, as stricter settings can cause unexpected results details.

If you still see irrelevant documents, verify that all documents have the correct metadata, the filter field names match, and you are not passing explicit document_ids (which disables metadata filtering). If the metadata filter UI is missing, check your dataset's metadata setup and enable the fields in the dataset settings modal.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[wangjuu]

@dosu Even if i set meta_fields for all documents in dataset,it still can't work well.
1.Still search for other documents
2.When no relevant knowledge is found, irrelevant sources will be displayed.

And my goal is to be able to categorize documents within the dataset,and when answering questions,to filter the relevant documents based on the classification without including those that do not match the meta_field.Besides using meta_fields in document,are there any better methods?

Please help me solve the problems

[dosubot]

Strict metadata filtering in RAGFlow can still fail even if meta_fields are set for all documents, mainly due to backend logic and how the system handles cases where no documents match the filter. If the filter returns no matches, the backend may fall back to returning all documents or irrelevant sources, especially if the special doc_id '-999' is not handled correctly in your version. This is a known issue in some releases and may persist if the retrieval stack or UI is out of sync with the backend logic (details).

To troubleshoot and improve strict filtering:

• Double-check that every document has the correct meta_fields and that the filter field name matches exactly (e.g., "doc_type" not "doctype") (details).
• Use the metadata management UI to verify and edit metadata fields. Recent versions allow searching and direct modification of metadata values in the UI, making it easier to ensure consistency (PR #12560).
• In chat assistant, try using "Manual" mode for metadata filtering and set explicit conditions (Equals, In, etc.) for the strictest control (guide).
• Tune retrieval parameters like similarity_threshold and vector_similarity_weight to reduce irrelevant results (guide).
• If you still see irrelevant sources when no match is found, this is likely due to the backend returning all documents instead of none—a bug fixed in newer versions (details).

For better categorization and filtering beyond meta_fields, consider:

• Using tag sets: RAGFlow supports auto-tagging chunks with user-defined tag sets. Tags can be used to influence retrieval, especially when chunks are semantically similar and hard to distinguish by metadata alone. You configure tag sets in the dataset, re-parse documents, and the system will auto-tag chunks based on similarity to tag descriptions (tag sets guide).
• Splitting documents into multiple datasets for higher-level categorization, then selecting the relevant dataset(s) at query time.
• Combining metadata filtering with tag-based retrieval for stricter domain separation.

If you want to batch-update metadata, use the batch_update_metadata method to ensure all documents have the correct fields (backend reference). After updating metadata, you do not need to re-parse documents, but you should verify the metadata index is up to date.

Let me know if you want step-by-step instructions for tag sets or batch metadata updates.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}