> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-en/org/querymetadata.md).

# Knowledge Management Permissions: Query Metadata

## Feature Description

When deploying an AI conversation system, organizations typically need fine-grained control over the available scope of "Knowledge Bases / AI Assistants / Conversation Platforms" based on user permissions and usage requirements.

In MaiAgent, you can use query metadata attached to different conversation / identity levels to determine "what content this person / this conversation can reference."

### What Is Query Metadata?

Query metadata is a set of dynamic conditions that define the query scope. It can specify which "knowledge bases, FAQs, and documents matching tag conditions" a user can query on a given conversation platform.

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

> **Roles / Contacts / Conversations are containers; query metadata is the condition settings that actually control the visible scope**

{% hint style="info" %}
Learn more from the following articles:

* [**Contacts**](/maiagent-user-guide/maiagent-user-guide-en/org/contact.md)
* [**Role Permission Management**](/maiagent-user-guide/maiagent-user-guide-en/org/role-permission.md)
  {% endhint %}

## Permission Level Concept

Before constructing a service, the Agent verifies all available knowledge bases through query metadata at different levels. The permission level reference order is as follows:

```
AI Assistant > Conversation Platform > User (Conversation / Contact / Role) > Query Metadata > Query Permissions
```

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

> See the following documentation for instructions:
>
> 1. [Getting Started — Using the "Query Builder"](/maiagent-user-guide/maiagent-user-guide-en/org/query-builder.md)
> 2. Technical Manual: [JSON Interface Configuration Guide (Contacts, Web Chat Embed Settings)](https://docs.maiagent.ai/tech/authorization-integration/json-interfaces)

<figure><img src="/files/8Pv7ecbkHQuaVlo6ZbLo" alt=""><figcaption></figcaption></figure>

* Contacts / Roles are identity containers
* Conversations correspond to internal conversations where you can control the knowledge bases used through filtering
* Query metadata is the "set of filter conditions" actually applied during conversations

### Document Filtering Condition Level Hierarchy

<figure><img src="/files/sCjIuakCDhhYwRXO5S2S" alt=""><figcaption></figcaption></figure>

Through layer-by-layer transmission, query metadata becomes the actual decision-making basis for AI response logic

## Practical Use Cases

<figure><img src="/files/ng6Y0rqtRl00jX881LAz" alt=""><figcaption></figcaption></figure>

***

## Summary: The Value of Query Metadata for Enterprises

🎯 **Multi-dimensional identity cross-control** (role + region + product line)

🎯 **Real-time query control**: No need to duplicate assistants — just change the conditions to switch between scenarios

🎯 **Flexible large-scale knowledge base management**: Tags and knowledge bases can be split and authorized by scenario

> **Incorporate query metadata into your product architecture core to achieve maximum authorization flexibility with minimal configuration,**\
> **ensuring knowledge security while improving conversation experience and operational efficiency.**


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-en/org/querymetadata.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.