> 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/identity-and-access/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 knowledge an Agent can retrieve. See the Getting Started subpage for detailed configuration.

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

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 a contact, conversation, or message can reference during retrieval. **Contacts, conversations, and messages are containers; Query Metadata consists of conditions attached to those containers that determine their actual visibility scope**. Roles are not containers.

For concepts, use cases, and admin operations, see [Knowledge Access Permissions: Query Metadata](https://docs.maiagent.ai/org/querymetadata) in the user manual. This page is the entry point for engineers, covering the API fields at each level, resolution order, and condition model. For JSON syntax, see [Getting Started—Using JSON](/tech/en/identity-and-access/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/json-interfaces.md).

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

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

Query Metadata can be configured at three levels, each with 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 the Web Chat embed (submitted at the message level) |
| **Conversation** | All messages in that conversation | Included in the API request that creates the conversation                                                                                                                                     |
| **Contact**      | All conversations for that user   | Contact editing in the admin interface (Query Builder or JSON), Contact API                                                                                                                   |

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

During retrieval, the system selects the **first configured level** in this order:

```
Message > Conversation > Contact > Agent default label filter > None configured (unrestricted; all knowledge bases attached to the Agent are searchable)
```

* If a level is unset (`null`) → check the next level
* The first configured level **takes effect in its entirety**, without merging with lower levels—the higher-level configuration completely overrides the lower levels
* An empty object `{}` also counts as configured (meaning unrestricted) and stops further lookup. For the precise semantics of empty collections versus unset values, see the [JSON Guide](/tech/en/identity-and-access/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/json-interfaces.md#empty-vs-unset)
* The **Agent default label filter** (`defaultLabelRelations` in Agent settings) applies only when Message, Conversation, and Contact are all `null`: its label conditions filter all knowledge bases attached to the Agent. If any of the three levels is configured (including `{}`), it does not apply. For admin configuration, see [Knowledge Base Label Filtering](https://docs.maiagent.ai/build/agent/label-filter) in the user manual

{% hint style="info" %}
**What about internal members?** [Role permissions](https://docs.maiagent.ai/org/roles/role-permission) control which resources members can see in the platform through a separate mechanism. When using internal Q\&A, members select the knowledge scope per message, corresponding to the message level in the table above. For instructions, see [Getting Started—Using Query Builder](https://docs.maiagent.ai/org/querymetadata/query-builder) in the user manual.
{% endhint %}

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

Query Metadata consists of two parts that progressively narrow the retrieval scope:

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

```mermaid
flowchart TB
    KB["Knowledge bases"]
    Docs["Documents / FAQs in the knowledge bases"]
    Tags["Further 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 restricts only **knowledge base retrieval**: it is not included in the LLM prompt, so the AI cannot read the conditions themselves. To let the AI know a value (such as a product ID), use [contextData](/tech/en/serve/web-chat-sdk/web-chat-context-data.md).

It also does not apply to Text to SQL or tools: the Agent does not use Query Metadata when querying a database, and there is no request-level field for restricting tables. Database scope can only be controlled through enablement, Agent association, <mark style="color:blue;">table selection</mark>, and account permissions. See [Text to SQL: FAQ](/tech/en/advanced-genai-tech/text-to-sql.md#faq).
{% 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 interface; per-message selection in internal Q\&A | User manual: [Getting Started—Using Query Builder](https://docs.maiagent.ai/org/querymetadata/query-builder)                                         |
| **JSON**                      | API integration, Web Chat embedding, complex nested conditions                                          | [Getting Started—Using JSON](/tech/en/identity-and-access/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>

When one Agent serves multiple user identities, simply provide different Query Metadata for each identity; there is no need to duplicate the Agent. For a comparison of the conditions for visitors, members, customer service staff, internal employees, and administrators, see [Practical Use Cases](https://docs.maiagent.ai/org/querymetadata#practical-use-cases) in the user manual.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/tech/en/identity-and-access/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.