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

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

Query Metadata（クエリメタデータ）を使用して、AI アシスタントが検索できるナレッジの範囲を制御します。詳細な設定方法については、「構築を開始」サブページを参照してください。

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

対話型 AI を導入する際、ユーザーごとに参照できるナレッジの範囲を変える必要があることがよくあります。たとえば、訪問者は公開情報のみ、VIP 会員は追加のプランドキュメント、社内従業員は従業員ハンドブックを検索できるようにします。

Query Metadata は、**ナレッジ検索の範囲を制限する条件**のセットです。特定の ID、会話、またはメッセージについて、検索時に参照できる「ナレッジベース、ドキュメント、FAQ、ラベル条件に一致するコンテンツ」を指定します。ID の仕組みに代わるものではなく、ID が**条件に応じて機能する**ようにします。

> **連絡先、会話、メッセージはコンテナであり、Query Metadata はコンテナに紐づけられ、実際の表示範囲を決定する条件です。**

{% hint style="info" %}
関連情報：[連絡先（Contact）の概要と連携](/tech/ja/authorization-integration/contacts.md)、[ロール（Role）と連絡先（Contact）の違い](/tech/ja/authorization-integration/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 > すべて未設定（制限なし。AI アシスタントに紐づくすべてのナレッジベースを検索可能）
```

* あるレベルが未設定（`null`）の場合は、次のレベルを確認します。
* 最初に設定されているレベルが**全体として適用**され、下位レベルとはマージされません。上位レベルの設定が下位レベルを完全に上書きします。
* 空のオブジェクト（`{}`）も設定済みと見なされます。これは制限なしを意味し、下位レベルの確認を終了します。「空のセットと未設定」の厳密な意味については、[JSON 形式ガイド](/tech/ja/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" %}
**社内メンバーの場合はどうなりますか？** メンバーがプラットフォーム内で参照できるリソースは、別の仕組みである[ロール権限](https://docs.maiagent.ai/org/role-permission)によって制御されます。メンバーが社内 Q\&A を利用する場合は、メッセージごとにナレッジ範囲を選択します。これは上表のメッセージレベルに該当します。詳しくは、[グラフィカルインターフェースガイド](/tech/ja/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/graphical-interface.md)を参照してください。
{% 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
```

<figure><img src="https://605688223-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVYMUz6J7vDZ0QTvb1rbN%2Fuploads%2Fgit-blob-d5f64342fe0f0f23717cda6c0696e03866230265%2Fimage%20(33).png?alt=media" alt=""><figcaption><p>ドキュメントのフィルタリング条件レベルを示す図</p></figcaption></figure>

{% hint style="warning" %}
Query Metadata が制限するのは**ナレッジベース検索**のみです。LLM prompt には含まれないため、AI は条件自体を読み取れません。商品 ID などの値を AI に認識させるには、[contextData](/tech/ja/api-integration/web-chat-sdk/web-chat-context-data.md)を使用してください。
{% endhint %}

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

| 方法                  | 適した用途                                             | ガイド                                                                                                                                                      |
| ------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **クエリビルダー**（グラフィカル） | 管理画面で連絡先の権限を手動設定する場合、社内 Q\&A でメッセージごとにナレッジを選択する場合 | [構築を開始—「クエリビルダー」を使用する](/tech/ja/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/graphical-interface.md) |
| **JSON 形式**         | API 連携、Web Chat の組み込み、複雑なネスト条件                    | [構築を開始—JSON 形式を使用する](/tech/ja/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/json-interfaces.md)       |

## 実際のユースケース <a href="#scenarios" id="scenarios"></a>

<table><thead><tr><th width="162.5028076171875">ID</th><th>渡す条件（query_metadata）</th><th>レスポンス結果</th></tr></thead><tbody><tr><td>訪問者</td><td>ナレッジベース：<code>一般</code><br>ドキュメント：なし<br>ラベル：<code>訪問者</code><br>FAQ：<code>1</code>、<code>2</code></td><td><code>一般</code>ナレッジベースから、<code>訪問者</code>ラベルが付いたドキュメント、FAQ <code>1</code>、FAQ <code>2</code>を取得します</td></tr><tr><td>一般会員</td><td>ナレッジベース：<code>一般</code><br>ドキュメント：<code>A</code>、<code>B</code>、<code>C</code><br>ラベル：なし<br>FAQ：なし</td><td><code>一般</code>ナレッジベースから、ドキュメント<code>A</code>、<code>B</code>、<code>C</code>とすべての FAQ を取得します</td></tr><tr><td>カスタマーサポート担当者</td><td>ナレッジベース：<code>従業員</code><br>ドキュメント：なし<br>ラベル：<code>カスタマーサポート</code><br>FAQ：なし</td><td><code>従業員</code>ナレッジベースから、<code>カスタマーサポート</code>ラベルが付いたドキュメントとすべての FAQ を取得します</td></tr><tr><td>社内従業員</td><td>ナレッジベース：<code>従業員</code><br>ドキュメント：<code>A</code>、<code>B</code><br>ラベル：なし<br>FAQ：なし</td><td><code>従業員</code>ナレッジベースから、ドキュメント<code>A</code>、<code>B</code>とすべての FAQ を取得します</td></tr><tr><td>管理者</td><td>ナレッジベース：<code>従業員</code>、<code>一般</code><br>ドキュメント：なし<br>ラベル：なし<br>FAQ：なし</td><td><code>従業員</code>および<code>一般</code>ナレッジベースのすべてのドキュメントと FAQ を取得します</td></tr></tbody></table>

同じ AI アシスタントが複数の ID に対応する場合、条件を切り替えるだけでよく、アシスタントを複製する必要はありません。これが Query Metadata の中心的な価値です。つまり、**多次元の ID による横断的なアクセス制御**（ランク × 部門 × 製品ライン）、**クエリごとの制御**（バックエンドが現在の ID に基づいて条件をリアルタイムに組み立てる）、**大規模ナレッジベースの柔軟な認可**（シナリオに応じてラベルとナレッジベースを分割する）を実現します。


---

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