indykite-ciq-read

IndyKite ContX IQ - 読み取り専用ポリシー + Knowledge Query

ContX IQ（CIQ）は、IKG（IndyKite のナレッジグラフ。Cypher（Neo4j / openCypher のグラフクエリ言語）でクエリを実行するプロパティグラフデータベース）の上に構築された、コンテキストを認識するデータレイヤーです。CIQ ポリシーでは、どのグラフ要素にアクセスできるか、どのような条件の下でアクセスできるかを宣言し、CIQ Knowledge Queryでは、それらを使って何をするかを宣言します。実行呼び出しでは、実行時に具体的なパラメーター値を指定して Knowledge Query を実行します。

このスキルで扱うのは、読み取り専用の処理です。

• condition.cypher でノードとリレーションシップを照合するポリシー。allowed_reads では、Knowledge Query が返すことのできる変数を許可リストに指定します。
• nodes、relationships、および／または aggregate_values にこれらの変数を列挙する Knowledge Query。
• ポリシーの部分フィルター（$variable）に値を指定して、行を返す execute 呼び出し。

allowed_upserts と allowed_deletes は、読み取り専用の用途では意図的に対象外としており、ここでは一切扱いません。

使用する場面

次のような場合は、このスキルを有効にしてください。

• IKG からデータを読み取り、CIQ ポリシーと Knowledge Query を使って結果を整形したい場合。
• ContX IQ から取得する (workflow, agent_list) クエリを作成しており、indykite-agent-gateway スキルで使用する場合。
• indykite-mcp-server スキルが ciq_execute 経由で実行する Knowledge Query を準備している場合。
• アクセスできるはずの主体に対して、読み取り CIQ が何も返さない、または 403 を返す原因を調べている場合。

次のような場合は、このスキルを有効にしないでください。

• CIQ を通じてノードやリレーションシップを作成、更新、削除する必要がある場合。これは allowed_upserts / allowed_deletes と upsert_* / delete_* の Knowledge Query フィールドを使用しますが、わかりやすさを優先し、このスキルでは扱いません。
• yes/no の認可判断に AuthZEN を使用する場合（authzen_evaluate と MCP スキルを使用してください）。
• クエリ実行時に外部 API からデータを取得するため、External Data Resolver を呼び出す場合（別の機能です）。

前提条件

• IndyKite の プロジェクト、AppAgent、および AppAgent の 認証情報（実行時に X-IK-ClientKey に指定するトークン）。
• Config API へのアクセス権を持つ Service Account トークンと、PROJECT_GID に指定したプロジェクトの GID（どちらもポリシーと Knowledge Query の作成に使用します）。
• ポリシーで照合するノードとリレーションシップが、すでに IKG に登録されていること。CIQ はフィルタリングと投影のみを行い、データを投入することはありません。
• 認証対象の subject type（Person、User、_Application など）。CIQ ポリシーで扱える subject type は単一なので、2 つの主体が必要な場合は、ポリシーを 2 つ用意してください。

いずれかが不足している場合は、作業を中断してユーザーに伝えてください。原因のわかりにくい CIQ の拒否をデバッグするよりも、先に不足分を解決するほうがはるかに簡単です。

手順

1. 対象と Cypher パターンを選択する

対象タイプ - どちらか1つを選択します。スキーマは両方の選択肢で同一です。異なるのは subject.type、フィルター、実行時の認証だけです。

対象	次の場合に使用する	実行時の認証	フィルターの規約
_Application	システム側／ETL／カタログの処理。ユーザーは関与しません。	X-IK-ClientKey のみ。	subject.external_id = $_appId（予約済み）。
Person / User	認証済みユーザーが自ら操作を実行する場合。	X-IK-ClientKey + Authorization: Bearer <token>。	subject.external_id = $token.sub。

ポリシーで指定できる対象タイプは1つだけです。両方を許可する場合は、ポリシーを2つ作成してください。cypher 内の対象変数には、慣例として subject という名前を付けます。以下の実行可能な例では Person を使用します。たとえばカタログを読み取るサービス向けの _Application 版では、subject.type、フィルター、実行ヘッダーのみが異なります。

Cypher パターン - クエリで扱うすべてのノードとリレーションシップを指定する MATCH／OPTIONAL MATCH 句です。ポリシーと Knowledge Query から参照できるよう、それぞれに変数名を付ける必要があります。プロジェクトの IKG における正確なノードタイプ、リレーションシップタイプ、プロパティの表記が不明な場合は、まず Data Schema API から確認してください（indykite-data-schema）。名前に誤りがあっても、何も一致しないままエラーにならないことがあります。

このスキル全体で使用する例：

Person（対象）が Car を OWNS します。ある人物の external_id を指定して、その人物が所有する車を返します。

MATCH (subject:Person)-[r:OWNS]->(car:Car)

変数：subject、r、car。

2. 読み取り専用の CIQ ポリシーを作成する

ポリシー JSON を作成します。読み取り専用ポリシーに必要なのは、次の3項目だけです。

• meta.policy_version - 現在は 1.0-ciq です。
• subject.type - 選択した対象タイプです。
• condition.cypher と（任意の）condition.filter - パターンと任意のフィルターです。実行時に指定する部分フィルターには $varname を使用します。アンカーと範囲指定を行っても条件の処理が遅いままの場合に使用できる、任意の追加項目 condition.skip_resource_label もあります。使用する前にポリシーリファレンスを確認してください。
• allowed_reads - Knowledge Query が返すことを許可するすべての変数を列挙します。ノード／リレーションシップのすべてのプロパティを許可するには <var>.* を、単一のプロパティを許可するには <var>.property.<name> を使用します。

書き込みを禁止するには、allowed_upserts と allowed_deletes を完全に省略してください。これらを省略するのが、書き込みを禁止するためのサポートされた方法です。

実行例の読み取り専用ポリシーの全体は、assets/policy-read-cars.jsonを参照してください。

Config API を通じて作成します。

# set the current project_id, and stringify only the `policy` field, before POSTing
jq --arg pid "$PROJECT_GID" '.project_id = $pid | .policy |= tojson' assets/policy-read-cars.json \
  | curl -X POST "$API_URL/configs/v1/authorization-policies" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $SERVICE_ACCOUNT_TOKEN" \
      -d @-

201 Created が返すポリシーの id（GID）を POLICY_ID としてエクスポートします。Knowledge Query の作成時に、この値が policy_id に挿入されます。

完全なスキーマ（すべての演算子、すべての属性パターン、token_filter の用途）については、references/policy-reference.mdを参照してください。

3. ナレッジクエリを作成する

読み取り専用のナレッジクエリは、ポリシーを参照し、返す内容を指定します。読み取りに関係する4つのフィールドは次のとおりです。

• nodes - レスポンスに含めるノード変数（または<var>.property.<name>）。
• relationships - 含めるリレーションシップ変数。
• aggregate_values - cypher内の集計関数によって生成される変数（例：COLLECT(...) AS xs → "xs"）。
• batch_read - デフォルトのタイムアウトを超えるリスクがあるほど大きな結果セットが予想される場合に限り、trueに設定します。タイムアウトが5分に延長されます。

実行例の完全なナレッジクエリについては、assets/knowledge-query-read-cars.jsonを参照してください。

Config APIを使って作成します（POLICY_IDには、前の手順で取得したポリシーのGIDを設定します）。

# set the current project_id and policy_id, and stringify only the `query` field, before POSTing
jq --arg pid "$PROJECT_GID" --arg polid "$POLICY_ID" '.project_id = $pid | .policy_id = $polid | .query |= tojson' assets/knowledge-query-read-cars.json \
  | curl -X POST "$API_URL/configs/v1/knowledge-queries" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $SERVICE_ACCOUNT_TOKEN" \
      -d @-

201 Createdが返すのは、ナレッジクエリのid（GID）です。この値をexecute（およびMCPのciq_executeツール）で参照します。

upsert_*とdelete_*（読み取りの場合は省略）を含む、ナレッジクエリのすべてのフィールドのスキーマ詳細については、references/knowledge-query-reference.mdを参照してください。

4. クエリを実行する

executeエンドポイントは、具体的なパラメーター値を使ってナレッジクエリを実行時に実行します。

POST <API_URL>/contx-iq/v1/execute

認証：

• 常に必要：X-IK-ClientKey: <AppAgent-credentials-token>。
• subject.typeが**_Applicationではない場合**：Authorization: Bearer <user-access-token>も必要です。トークンのsubがサブジェクト識別子です。トークンが解決する正確なtype／idを確認するには、GET /contx-iq/v1/whoamiを呼び出してください（indykite-ciq-whoami）。
• subject.typeが**_Applicationの場合**：予約済みの$_appIdパラメーターには、アプリケーションのexternal_idが自動入力されます。input_paramsには渡さないでください。

リクエスト：

{
  "id": "<knowledge_query_gid_or_name>",
  "input_params": {
    "person_external_id": "alice"
  }
}

実行可能なシェルヘルパーについては、scripts/execute.shを参照してください。

大きな結果セットは、2つのオプションのボディフィールドでページ分割します。page_size（ページごとの行数。デフォルトは100）と、1始まりのページ番号であるpage_token（1または省略で最初のページ、2で次のページ）です。レスポンスにトークンは含まれないため、自分で番号を増やし、page_sizeより短いページが返された時点で停止してください。ヘルパーは最初のページを送信します。それ以降のページでは、未加工のボディにこの2つのフィールドを追加してください。MCPのciq_executeツールも、同じ2つのオプション引数を受け取ります（indykite-mcp-server）。

認証の組み合わせ、レスポンスの形式、ページ分割、エラーの仕様を含むexecuteの完全なリファレンスについては、references/execution-reference.mdを参照してください。

5. レスポンスを読み取り、確認する

レスポンスの形式は次のとおりです。

{
  "data": [
    { "nodes": { "<var>.<attr>": "<value>", ... } },
    { "relationships": { ... } }
  ]
}

一致ごとに1行が返されます。nodesのキーは<var>.<attr>、relationshipsのキーも同様です。ポリシーまたはナレッジクエリで変数が許可されていても、IKGに一致するものがなければ、データ配列は空になります。

レスポンスが期待どおりでない場合は、ポリシーを変更する前に、次のチェックリストを確認してください。

1. 変数がレスポンスに含まれていますか？ ポリシーのallowed_reads.nodes／relationships／aggregate_valuesと、ナレッジクエリのnodes／relationships／aggregate_valuesの両方に指定されている必要があります。返されるのは、両方に共通する項目です。
2. フィルターは実際に機能していますか？ attributeの誤記（例：subject.external_idとperson.external_id）があると、一致がない状態でもエラーは表示されません。属性の命名規則を再確認してください。
3. サブジェクトは正しく設定されていますか？ _Application以外のサブジェクトでは、Bearerトークンのsubがサブジェクト識別子です。トークンがないとサブジェクトがバインドされず、多くのポリシーで一致がなくなります。
4. データは実際にIKGに存在しますか？ 同じ形式でIS NOT NULLフィルターを使った確認用クエリを実行し、データの存在を確認してください。

成果

このスキルが正常に適用されると、次の状態になります。

• プロジェクトに読み取り専用の CIQ ポリシーが存在します。このポリシーには単一の subject.type、名前付き変数を含む cypher パターン、任意の部分フィルター、allowed_reads の許可リストがあり、allowed_upserts と allowed_deletes はありません。
• Knowledge Query はそのポリシーを参照し、nodes／relationships／aggregate_values で返す変数を正確に列挙します。
• POST /contx-iq/v1/execute（または MCP の ciq_execute ツール）は、有効な input_params に対して期待される行を返し、有効だが一致するものがない場合は空の data 配列を返します。
• 同じ Knowledge Query は、変更を加えずに indykite-mcp-server スキルから ciq_execute で呼び出せます。

このスキルのファイル

• references/policy-reference.md - 読み取り専用ポリシーのスキーマ、演算子、属性の命名規則、部分フィルター、token_filter、ステップアップ認証に関するアドバイス。
• references/knowledge-query-reference.md - Knowledge Query のスキーマ。このスキルで使用する読み取り専用フィールドと、その他すべてのフィールドの概要を1行ずつ記載しています。
• references/execution-reference.md - POST /contx-iq/v1/execute のリクエストとレスポンスの形式、認証の組み合わせ、一般的なエラーコード。
• assets/policy-read-cars.json - Person -[:OWNS]-> Car の例で実行できる読み取り専用ポリシー。
• assets/knowledge-query-read-cars.json - 対応する Knowledge Query。
• scripts/execute.sh - 正しいヘッダーを付けて /contx-iq/v1/execute にリクエストを送信する Bash ヘルパー。

エージェント固有の注意事項

このスキルは汎用的な Markdown の指示を使用しており、README に記載されているすべてのエージェントで動作します。エージェントは HTTP リクエスト（curl、HTTP クライアント、または IndyKite Terraform プロバイダー。参考資料を参照）を送信できる必要があります。Claude Code のフック、Cursor の @ メンション、Copilot のワークスペースコンテキストは必要ありません。

参考資料

• ContX IQ ガイド（開発者ハブ）
• Config API ドキュメント
• Cypher クエリー言語マニュアル（Neo4j；openCypher） - IndyKite Knowledge Graph 上で CIQ ポリシーと Knowledge Query の条件に使用されるグラフクエリー言語です。
• IndyKite Terraform プロバイダー - indykite_authorization_policy と indykite_knowledge_query
• 認証情報ガイド
• External Data Resolver ガイド（ここでは対象外ですが、後続の作業に役立ちます）