Knowledge management permissions (Query Metadata) overview

This article explains how to control the data and knowledge scope that AI assistants can reference through Query Metadata; for detailed settings refer to the "Get Started" subpage

Feature description

When implementing an AI conversation system, the usable scope of the "Knowledge / AI / Inbox" usually needs fine-grained control due to different user permissions and usage requirements.

In MaiAgent, you can use Query Metadata attached to different conversations/identity levels to determine "which content this person/this conversation can reference."

What is Query Metadata / "query metadata"?

Query Metadata is a set of dynamic conditions that limit the scope of queries and can specify the data content that a user can query under a certain conversation platform, such as "knowledge bases, FAQs, documents that match tag conditions," etc.

It does not replace roles or contacts; rather, it allows these identities to "take effect conditionally," achieving conversation-level least-privilege control.

Role / Contact / Conversation are containers; Query Metadata is the conditional restriction setting that actually controls the visible scope

Learn more through the following articles:

• Contact integration steps

• Difference between Role and Contact

Permission level concept

Before service construction, the Agent confirms all knowledge bases that can be referenced at that time through Query Metadata at different levels. The permission level reference order is as follows:

AI > Inbox > User (Message / Contact / Role) > query_metadata > query permissions

You can specify permissions at each level using a graphical interface or JSON format

You can refer to the following documentation for operations:

1. Graphical interface guide (Contact, Internal conversation settings)

2. JSON interface setup guide (Contact, Web chat embed settings)

• Contact / Role are identity containers

• Message corresponds to the internal conversation and can control which knowledge bases are used in the conversation via filtering

• query_metadata It is the actual "set of filter conditions" executed during the conversation

Document filtering condition evaluation levels

Diagram of document filtering condition levels

The open filtering logic is:

Through successive propagation, Query Metadata becomes the actual decision basis for AI response logic

Practical application scenarios

Identity	Incoming conditions (query_metadata)	Response results
Visitor	Knowledge base:General Document files: none Tags:Visitor FAQ:1,2	Obtain General Contains in the knowledge base Visitor Tagged documents and FAQs 1,FAQ 2
Regular member	Knowledge base:General Document files:A,B,C Tags: none FAQ: none	Obtain General In the knowledge baseA,B,C Documents and all FAQs
Customer service staff	Knowledge base:Employee Document files: none Tags:Customer service FAQ: none	Obtain Employee Documents in the knowledge base labeled as Customer service Tagged documents and all FAQs
Internal staff	Knowledge base:Employee Document files:A,B Tags: none FAQ: none	Obtain Employee In the knowledge base A,B Documents and all FAQs
Administrator	Knowledge base:Employee,General Document files: none Tags: none FAQ: none	Obtain Employee And General All document content and FAQs in the knowledge base

---

Summary: the value for enterprises of using query_metadata

🎯 Multidimensional identity cross-control(Role + Region + Product line)

🎯 Real-time query control: No need to duplicate assistants; just change conditions to switch scenarios

🎯 Flexible management of large knowledge bases: Tags and knowledge bases can be split and authorized according to scenarios

It is recommended to incorporate query_metadata into the core of the product architecture so that enterprises can achieve maximum authorization flexibility with minimal configuration, ensure knowledge security while improving conversational experience and maintenance efficiency.