# Getting Started—Using "Query Builder"

## Contact Query Metadata Configuration

You can use the "Query Builder" in the MaiAgent service to graphically create query metadata. Here's an example of creating contact query metadata:

### Step 1: Enter the Contacts Area in the MaiAgent Backend Service

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-e1193c589be2e94dd3b408588d7ea9a426bb3d2a%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-07%20165727.png?alt=media" alt=""><figcaption><p>Contacts Area Entry</p></figcaption></figure>

### Step 2: Configure the Desired Contact

1. Find the contact that needs configuration and click Edit

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-3e040c93c8149b98cec909c9f006f59876673de0%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-07%20165859.png?alt=media" alt=""><figcaption><p>Contact Edit Entry</p></figcaption></figure>

2. After clicking, the following screen will appear

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-ce1f2353f60000f676e26df8cd028b2729a238e1%2Fquery%20metadata%20maker.png?alt=media" alt=""><figcaption><p>Query Builder Entry</p></figcaption></figure>

Click the Query Builder directly to enter the graphical interface

### Step 3: Select the Permissions You Want to Grant

1. Check the knowledge bases you want to grant access to, or optionally select specific documents within that knowledge base

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-3cb875fe8a74fe9532e04d2d816b04dab3c3f3b3%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-07%20170306.png?alt=media" alt=""><figcaption><p>Select Knowledge Bases and Documents</p></figcaption></figure>

2. If you want to grant access to documents with specific tags, click "Show Tag Filter" to open the tag configuration space

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-4858e1ff92d8efc4cd28216d2ff05c207215aaca%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-07%20170306-1.png?alt=media" alt=""><figcaption><p>Tag Filter Configuration</p></figcaption></figure>

Here you can select the criteria you want to create, choosing `"OR"` (meets any condition) or `"AND"` (meets all conditions) as the document access standard within the granted knowledge bases

## Message Configuration

You can also use the right-side menu shown below to select the knowledge permissions you want to grant:

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-c197581d7292296d9555671138c8d7ed62ce5a70%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-08%20095028.png?alt=media" alt=""><figcaption><p>Internal Conversation: Select Available Knowledge Permissions</p></figcaption></figure>

You can also use "Show Tag Filter" to configure tag filtering conditions

{% hint style="info" %}
Before sending each different message, you can still modify the right-side permissions for knowledge management
{% endhint %}

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-1fd810ec8e5c4b185673a93858d73a36bca5d085%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-08%20124143.png?alt=media" alt=""><figcaption><p>Available Documents List</p></figcaption></figure>

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-e6b0091dcec82fe35f8d8f6f859ed8fd886249a0%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-08%20124344.png?alt=media" alt=""><figcaption><p>Selected Documents Status</p></figcaption></figure>

Currently able to reference three files: CV, SOP, and Survey

After unchecking CV in the next message and sending again:

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-9805fef0555d8b09f66eebd0114738a62852f580%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-08%20124830.png?alt=media" alt=""><figcaption><p>Example of Unchecking Document</p></figcaption></figure>

The Agent will no longer be able to use the CV file, and the citation library will not display CV citations:

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-18ee67d0a77a1ce864386d755225372b9f15fd63%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-08%20124958.png?alt=media" alt=""><figcaption><p>Citation Library Change: After Removing CV</p></figcaption></figure>

Permissions can be adjusted before sending each message, affecting the content that can be cited in that round's response.

## Pre-configuration When Loading Web Chat

MaiAgent provides the ability to pre-configure query metadata before Web Chat formally initializes. If you want to restrict conversation content before contact (e.g., when providing Web Chat services to customers without registered contact accounts), you can provide query metadata during embedding, and the system will enable message-level knowledge base document filtering mechanism by default.

For Web Chat configuration, please refer to: [Technical Manual: Getting Started—Using JSON Format](https://docs.maiagent.ai/tech/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/json-interfaces#webchat-chu-shi-hua-she-ding)

{% hint style="info" %}
You can also use JSON format to construct query metadata, please refer to [Technical Manual: Getting Started—Using JSON Format](https://docs.maiagent.ai/tech/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/json-interfaces)
{% endhint %}
