Issue with Document Retrieval When Manual Metadata Mode Is Enabled

[Synchronzied]

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).
• [FOR CHINESE USERS] 请务必使用英文提交 Issue，否则会被关闭。谢谢！:)
• Please do not modify this template :) and fill in all the required fields.

1. Is this request related to a challenge you're experiencing? Tell me about your story.

When using metadata in the knowledge base, if manual mode is enabled, no documents can be retrieved even without specifying any metadata conditions. However, retrieval works normally when manual mode is disabled.

2. Additional context or comments

No response

[dosubot[bot]]

This is a known issue in Dify: when manual metadata mode is enabled, document retrieval can fail—even if you haven't set any metadata conditions—because the backend expects a valid logical_operator (like "and" or "or") in the metadata filtering configuration. If this is missing or set incorrectly, retrieval returns no results or errors, and the backend doesn't handle it defensively in manual mode. Even with no conditions, a MetadataCondition object is still created, which blocks retrieval unless properly initialized. This behavior is specific to manual mode; disabling it restores normal retrieval source.

Workarounds: always set the logical_operator explicitly in your metadata filtering conditions when using manual mode, and use the "contains" operator for flexible matching (especially for long or variable fields). If you still see issues, try recreating the dataset and chatflow, or upgrade to the latest Dify version, as ongoing improvements may help source.

This limitation is recognized by the maintainers, and defensive error handling for missing logical_operator in manual mode is not yet patched in the backend, so manual configuration is currently the safest workaround source.

To reply, just mention @dosu.

---

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

   

[Synchronzied]

In Dify, which table stores the metadata of the knowledge base?
@dosu.

[dosubot[bot]]

The metadata definitions for the knowledge base in Dify are stored in the table named dataset_metadatas. The links between metadata and specific documents are managed by the dataset_metadata_bindings table. Each document can also store its own metadata values inline as JSON in the doc_metadata field of the documents table. These three work together to define, bind, and store metadata for knowledge base documents.
See model definitions

To reply, just mention @dosu.

---

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

   

[Synchronzied]

When uploading metadata via the API, is it necessary to enable metadata using
url = f"https://api.dify.ai/v1/datasets/{dataset_id}/metadata/built-in/{action}"?
If so, how should the action be set?
@dosu.