> 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/tech/en/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.md).

# Knowledge Management Permissions (Query Metadata) Overview

## What Is Query Metadata? <a href="#what-is-query-metadata" id="what-is-query-metadata"></a>

When deploying AI conversations, different users often need access to different scopes of knowledge: visitors can only query public information, VIP members get an additional plan document, and internal employees can access the employee handbook.

Query Metadata is a set of **conditions that narrow the knowledge retrieval scope**: it specifies which "knowledge bases, documents, FAQs, and label-matched content" a given identity, conversation, or message can reference during retrieval. It does not replace identity mechanisms — instead, it enables identities to **take effect conditionally**:

> **Contacts, conversations, and messages are containers. Query Metadata is the condition attached to the container that determines the visible scope.**

{% hint style="info" %}
Further reading: [Contact Introduction and Integration](/tech/en/authorization-integration/contacts.md), [Differences Between Roles and Contacts](/tech/en/authorization-integration/role-vs-contact.md)
{% endhint %}

## Configurable Levels <a href="#levels" id="levels"></a>

Query Metadata can be configured at three levels, each corresponding to a different integration method:

| Level            | Effective Scope                   | Configuration Method                                                                                                                                                                 |
| ---------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Message**      | That single message only          | `message.queryMetadata` in the Conversation API; knowledge selection on the right side of the internal Q\&A interface; `queryMetadata` in Web Chat embed (sent at the message level) |
| **Conversation** | All messages in that conversation | Passed in when creating a conversation via API                                                                                                                                       |
| **Contact**      | All conversations for that user   | Contact editing in the dashboard (Query Builder or JSON), Contact API                                                                                                                |

### Resolution Order <a href="#resolution-order" id="resolution-order"></a>

During retrieval, the system checks from top to bottom and uses the **first level that has a configuration**:

```
Message > Conversation > Contact > None set (no restriction — all knowledge bases attached to the AI assistant are searchable)
```

* If a level is not set (`null`) → check the next level down
* The first level with a configuration **takes full effect** and is not merged with lower levels — the upper-level configuration completely overrides lower levels
* An "empty object `{}`" also counts as configured (meaning no restriction) and stops the downward lookup — for the precise semantics of "empty set vs. unset," see the [JSON Format Guide](/tech/en/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/json-interfaces.md#empty-vs-unset)

{% hint style="info" %}
**What about internal members?** Which resources members can see within the platform is controlled by [role permissions](https://docs.maiagent.ai/org/role-permission) (a separate mechanism). When members use the internal Q\&A, they select the knowledge scope per message — this is the message level in the table above (see the [Graphical Interface Guide](/tech/en/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/graphical-interface.md)).
{% endhint %}

## How Conditions Narrow the Scope <a href="#filter-model" id="filter-model"></a>

A Query Metadata configuration consists of two parts that progressively narrow the retrievable scope:

1. `knowledge_bases`: Which **knowledge bases** are accessible, and which **documents/FAQs** within each knowledge base are accessible (select all, select all excluding a few, or select only a few)
2. `label_relations`: Within the accessible documents, further filter by **label** conditions (AND/OR, supports nesting)

```mermaid
flowchart TB
    KB["Knowledge Bases"]
    Docs["Documents / FAQs within Knowledge Bases"]
    Tags["Filter accessible content by label conditions"]
    Result["Final retrievable content"]

    KB --> Docs
    Docs --> Tags
    Tags --> Result

    classDef kbBox fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,color:#000000
    classDef docBox fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#000000
    classDef tagBox fill:#e8f5e8,stroke:#388e3c,stroke-width:2px,color:#000000
    classDef resultBox fill:#fff3e0,stroke:#f57c00,stroke-width:2px,color:#000000

    class KB kbBox
    class Docs docBox
    class Tags tagBox
    class Result resultBox
```

{% hint style="warning" %}
Query Metadata only constrains **knowledge base retrieval**: it does not enter the LLM prompt, and the AI cannot read the conditions themselves. To make the AI "aware" of a value (such as a product ID), use [contextData](/tech/en/api-integration/web-chat-sdk/web-chat-context-data.md).
{% endhint %}

## Two Ways to Build <a href="#build-methods" id="build-methods"></a>

| Method                        | Best For                                                                                          | Guide                                                                                                                                                                        |
| ----------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Query Builder** (graphical) | Manually configuring contact permissions in the dashboard, per-message selection in internal Q\&A | [Start Building — Using the Query Builder](/tech/en/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/graphical-interface.md) |
| **JSON Format**               | API integration, Web Chat embed, complex nested conditions                                        | [Start Building — Using JSON Format](/tech/en/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/json-interfaces.md)           |

## Practical Use Cases <a href="#scenarios" id="scenarios"></a>

<table><thead><tr><th width="162.5028076171875">Identity</th><th>Conditions Passed (query_metadata)</th><th>Response Result</th></tr></thead><tbody><tr><td>Visitor</td><td>Knowledge base: <code>General</code><br>Documents: None<br>Labels: <code>Visitor</code><br>FAQs: <code>1</code>, <code>2</code></td><td>Retrieves documents with the <code>Visitor</code> label from the <code>General</code> knowledge base, plus FAQ <code>1</code> and FAQ <code>2</code></td></tr><tr><td>Regular Member</td><td>Knowledge base: <code>General</code><br>Documents: <code>A</code>, <code>B</code>, <code>C</code><br>Labels: None<br>FAQs: None</td><td>Retrieves documents <code>A</code>, <code>B</code>, <code>C</code> and all FAQs from the <code>General</code> knowledge base</td></tr><tr><td>Customer Service Agent</td><td>Knowledge base: <code>Employee</code><br>Documents: None<br>Labels: <code>Customer Service</code><br>FAQs: None</td><td>Retrieves documents labeled <code>Customer Service</code> and all FAQs from the <code>Employee</code> knowledge base</td></tr><tr><td>Internal Employee</td><td>Knowledge base: <code>Employee</code><br>Documents: <code>A</code>, <code>B</code><br>Labels: None<br>FAQs: None</td><td>Retrieves documents <code>A</code>, <code>B</code> and all FAQs from the <code>Employee</code> knowledge base</td></tr><tr><td>Admin</td><td>Knowledge bases: <code>Employee</code>, <code>General</code><br>Documents: None<br>Labels: None<br>FAQs: None</td><td>Retrieves all documents and FAQs from both the <code>Employee</code> and <code>General</code> knowledge bases</td></tr></tbody></table>

When a single AI assistant serves multiple identities, you only need to change the conditions instead of duplicating the assistant — this is the core value of Query Metadata: **multi-dimensional identity cross-control** (tier × department × product line), **per-query control** (the backend dynamically assembles conditions based on the current identity), and **flexible authorization for large knowledge bases** (labels and knowledge bases split by scenario).


---

# 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/tech/en/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.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.