> 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/ja/identity-and-access/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.md).

# ナレッジ管理権限（Query Metadata／クエリメタデータ）の概要

Query Metadata（クエリメタデータ）で Agent が検索できるナレッジの範囲を制御します。詳細な設定方法は「構築を始める」サブページをご覧ください。

## Query Metadata とは？ <a href="#what-is-query-metadata" id="what-is-query-metadata"></a>

Query Metadata（クエリメタデータ）は、**ナレッジの検索範囲を制限する条件の集合**です。特定の連絡先／会話／メッセージが検索時に参照できるナレッジベース、ドキュメント、FAQ、ラベル条件に一致するコンテンツを指定します。**連絡先／会話／メッセージはコンテナであり、Query Metadata はそのコンテナに付与され、実際に参照可能な範囲を決める条件です**。ロールはコンテナではありません。

概念、活用例、管理画面での操作は、ユーザーマニュアルの[ナレッジ管理権限：クエリメタデータ](https://docs.maiagent.ai/org/querymetadata)をご覧ください。本ページはエンジニア向けの入口として、各レベルに対応する API フィールド、解決順序、条件モデルを説明します。JSON の記述方法は[構築を始める—JSON 形式を使用する](/tech/ja/identity-and-access/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/json-interfaces.md)をご覧ください。

{% hint style="info" %}
関連情報：[連絡先（Contact）の概要と連携](/tech/ja/serve/contacts.md)、[ロール（Role）と連絡先（Contact）の違い](/tech/ja/serve/contacts/role-vs-contact.md)
{% endhint %}

## 設定できるレベル <a href="#levels" id="levels"></a>

Query Metadata は次の 3 つのレベルに設定でき、それぞれ異なる連携方法に対応しています。

| レベル                  | 適用範囲           | 設定方法                                                                                             |
| -------------------- | -------------- | ------------------------------------------------------------------------------------------------ |
| **メッセージ（Message）**   | そのメッセージのみ      | 会話 API の `message.queryMetadata`、内部 Q\&A 画面右側のナレッジ選択、Web Chat 埋め込みの `queryMetadata`（メッセージレベルで送信） |
| **会話（Conversation）** | その会話のすべてのメッセージ | 会話作成 API で指定します                                                                                  |
| **連絡先（Contact）**     | そのユーザーのすべての会話  | 管理画面での連絡先編集（クエリビルダーまたは JSON）、連絡先 API                                                             |

### 解決順序 <a href="#resolution-order" id="resolution-order"></a>

検索時は、上から順に**最初に「設定されている」レベル**を採用します。

```
Message > Conversation > Contact > Agent のデフォルトラベルフィルター > すべて未設定（制限なし、Agent に紐付いたすべてのナレッジベースを検索可能）
```

* あるレベルが未設定（`null`）の場合 → 次のレベルを確認します
* 最初に設定されているレベルの**設定全体が適用され**、下位レベルとは結合されません。上位レベルの設定が下位レベルを完全に上書きします
* 「空のオブジェクト `{}`」も設定済みとみなされ（制限なしを意味します）、下位レベルの確認を終了します。「空の集合と未設定」の正確な意味は [JSON 形式ガイド](/tech/ja/identity-and-access/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/json-interfaces.md#empty-vs-unset)をご覧ください
* **Agent のデフォルトラベルフィルター**（Agent 設定の `defaultLabelRelations`）は、Message、Conversation、Contact の 3 レベルがすべて `null` の場合にのみ適用されます。そのラベル条件で Agent に紐付いたすべてのナレッジベースをフィルタリングします。いずれかのレベルが設定されている場合（`{}` を含む）は適用されません。管理画面での設定方法は、ユーザーマニュアルの[ナレッジベースのラベルフィルター](https://docs.maiagent.ai/build/agent/label-filter)をご覧ください

{% hint style="info" %}
**内部メンバーの場合は？** メンバーがプラットフォーム内で閲覧できるリソースは、別の仕組みである[ロール権限](https://docs.maiagent.ai/org/roles/role-permission)で制御します。内部 Q\&A を使う際はメッセージごとにナレッジの範囲を選択します。これは上表のメッセージレベルに該当します。操作方法は、ユーザーマニュアルの[構築を始める—「クエリビルダー」を使用する](https://docs.maiagent.ai/org/querymetadata/query-builder)をご覧ください。
{% endhint %}

## 条件で範囲を絞り込む仕組み <a href="#filter-model" id="filter-model"></a>

Query Metadata は 2 つの部分で構成され、検索可能な範囲を段階的に絞り込みます。

1. `knowledge_bases`：許可する**ナレッジベース**と、各ナレッジベース内で許可する**ドキュメント／FAQ**を指定します（すべて選択、一部を除外してすべて選択、一部のみ選択）
2. `label_relations`：許可済みのドキュメントを、さらに**ラベル**条件（AND／OR、ネスト可能）でフィルタリングします

```mermaid
flowchart TB
    KB["ナレッジベース"]
    Docs["ナレッジベース内のドキュメント / FAQ"]
    Tags["許可済みのコンテンツをラベル条件でさらに絞り込みます"]
    Result["最終的に検索できるコンテンツ"]

    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 が制限するのは**ナレッジベースの検索**のみです。LLM のプロンプトには含まれず、AI は条件そのものを読み取れません。商品 ID などの値を AI に認識させるには、[contextData](/tech/ja/serve/web-chat-sdk/web-chat-context-data.md) を使用してください。

Text to SQL やツールにも適用されません。Agent がデータベースを検索する際は Query Metadata を参照せず、リクエストレベルにテーブルを制限するフィールドはありません。データベースの範囲は、有効化、Agent との紐付け、<mark style="color:blue;">テーブルの指定</mark>、アカウント権限でのみ制御できます。[Text to SQL：よくある質問](/tech/ja/advanced-genai-tech/text-to-sql.md#faq)をご覧ください。
{% endhint %}

## 2 つの構築方法 <a href="#build-methods" id="build-methods"></a>

| 方法                  | 適した用途                                | ガイド                                                                                                                                           |
| ------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **クエリビルダー**（グラフィカル） | 管理画面で連絡先の権限を手動設定、内部 Q\&A でメッセージごとに選択 | ユーザーマニュアルの[構築を始める—「クエリビルダー」を使用する](https://docs.maiagent.ai/org/querymetadata/query-builder)                                                   |
| **JSON 形式**         | API 連携、Web Chat 埋め込み、複雑なネスト条件        | [構築を始める—JSON 形式を使用する](/tech/ja/identity-and-access/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/json-interfaces.md) |

## 実際の活用例 <a href="#scenarios" id="scenarios"></a>

同じ Agent が複数のユーザー区分に対応する場合、区分に応じて Query Metadata を切り替えるだけでよく、Agent を複製する必要はありません。訪問者、会員、カスタマーサポート担当者、社内従業員、管理者にそれぞれ指定する条件の比較表は、ユーザーマニュアルの[実際の活用例](https://docs.maiagent.ai/org/querymetadata#practical-use-cases)をご覧ください。


---

# 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/ja/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.