> 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

Use Query Metadata to control the scope of knowledge that an AI assistant can retrieve. See the "Start Building" subpages for detailed setup instructions.

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

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

Query Metadata is a set of **conditions that restrict the scope of knowledge retrieval**. It specifies which knowledge bases, documents, FAQs, and content matching label conditions can be referenced when retrieving knowledge for a particular identity, conversation, or message. It does not replace the identity mechanism; instead, it enables an identity to **take effect conditionally**:

> **Contacts, conversations, and messages are containers. Query Metadata consists of conditions attached to those containers that actually determine the visible scope.**

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

## Available Configuration Levels <a href="#levels" id="levels"></a>

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

| Level            | Scope                             | Configuration method                                                                                                                                                                   |
| ---------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Message**      | Only that message                 | `message.queryMetadata` in the Conversation API; knowledge selection on the right side of the internal Q\&A interface; `queryMetadata` in a Web Chat embed (sent at the message level) |
| **Conversation** | All messages in that conversation | Included when creating a conversation through the API                                                                                                                                  |
| **Contact**      | All conversations for that user   | Edit the contact in the admin console (query builder or JSON), or use the Contact API                                                                                                  |

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

During retrieval, the **first configured level** is selected from top to bottom:

```
Message > Conversation > Contact > None configured (unrestricted; all knowledge bases attached to the AI assistant can be queried)
```

* If a level is not configured (`null`), resolution continues to the next level.
* The first configured level takes effect **in its entirety** and is not merged with lower levels. A higher-level configuration completely overrides lower-level configurations.
* An empty object (`{}`) also counts as configured. It means unrestricted access and stops resolution from continuing. See [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) for the precise semantics of "empty set vs. not configured."

{% hint style="info" %}
**What about internal members?** The resources that members can access within the platform are controlled by [role permissions](https://docs.maiagent.ai/org/role-permission), which is a separate mechanism. When members use internal Q\&A, they select the knowledge scope for each 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`: Defines which **knowledge bases** are available and which **documents/FAQs** are available within each knowledge base (select all, select all except a few, or select only specific items).
2. `label_relations`: Further filters the available documents by **label** conditions (AND/OR, with nesting supported).

```mermaid
flowchart TB
    KB["Knowledge Bases"]
    Docs["Documents / FAQs in the Knowledge Base"]
    Tags["Further Filter Available 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
```

<figure><img src="https://3415477754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNBTi475lqozGpB7xObpE%2Fuploads%2Fgit-blob-d5f64342fe0f0f23717cda6c0696e03866230265%2Fimage%20(33).png?alt=media" alt=""><figcaption><p>Diagram of document filtering condition levels</p></figcaption></figure>

{% hint style="warning" %}
Query Metadata restricts **knowledge base retrieval** only. It is not included in the LLM prompt, so 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 Conditions <a href="#build-methods" id="build-methods"></a>

| Method                        | Best for                                                                                                                | Guide                                                                                                                                                                      |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Query Builder** (graphical) | Manually configuring contact permissions in the admin console and selecting knowledge for each message 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 embedding, and 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>Provided conditions (query_metadata)</th><th>Response result</th></tr></thead><tbody><tr><td>Visitor</td><td>Knowledge base: <code>General</code><br>Documents: None<br>Label: <code>Visitor</code><br>FAQ: <code>1</code>, <code>2</code></td><td>Retrieves documents with the <code>Visitor</code> label and FAQ <code>1</code> and FAQ <code>2</code> from the <code>General</code> knowledge base</td></tr><tr><td>Standard member</td><td>Knowledge base: <code>General</code><br>Documents: <code>A</code>, <code>B</code>, <code>C</code><br>Label: None<br>FAQ: None</td><td>Retrieves documents <code>A</code>, <code>B</code>, and <code>C</code> and all FAQs from the <code>General</code> knowledge base</td></tr><tr><td>Customer service representative</td><td>Knowledge base: <code>Employees</code><br>Documents: None<br>Label: <code>Customer Service</code><br>FAQ: None</td><td>Retrieves documents labeled <code>Customer Service</code> and all FAQs from the <code>Employees</code> knowledge base</td></tr><tr><td>Internal employee</td><td>Knowledge base: <code>Employees</code><br>Documents: <code>A</code>, <code>B</code><br>Label: None<br>FAQ: None</td><td>Retrieves documents <code>A</code> and <code>B</code> and all FAQs from the <code>Employees</code> knowledge base</td></tr><tr><td>Administrator</td><td>Knowledge bases: <code>Employees</code>, <code>General</code><br>Documents: None<br>Label: None<br>FAQ: None</td><td>Retrieves all documents and FAQs from the <code>Employees</code> and <code>General</code> knowledge bases</td></tr></tbody></table>

When the same AI assistant serves multiple identities, you only need to change the conditions; there is no need to duplicate the assistant. This is the core value of Query Metadata: **multidimensional identity-based access control** (tier × department × product line), **per-query control** (the backend assembles conditions in real time based on the current identity), and **flexible authorization for large knowledge bases** (labels and knowledge bases are divided according to each 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.