indykite-ciq-add-property

IndyKite ContX IQ - 既存ノードへのプロパティの追加

IndyKite Graph（IKG）にすでに存在するノードのプロパティを、ContX IQ ポリシーと Knowledge Query に基づいて設定または上書きし、POST /contx-iq/v1/execute で実行します。ポリシーでは、変更を許可する cypher によってマッチされたノードを allowed_upserts.nodes.existing_nodes でホワイトリストに登録します。Knowledge Query の upsert_nodes ではこれらの変数を参照し、ノードはすでに存在するため external_id は指定せず、設定するプロパティをメタデータとともに（任意で）列挙します。IKG ではこれをアップサートとして扱います。新しいプロパティの追加と、既存プロパティの上書きは同じ操作であり、プラットフォームは両者を区別しません。

このスキルが対象とするのは、既存ノードへのプロパティ書き込みのみです。以下の操作は意図的に対象外です。

• 新しいノードの作成には allowed_upserts.nodes.node_types と、新しい name および external_id を含む Knowledge Query の upsert_nodes エントリーを使用します。詳しくは indykite-ciq-create-node を参照してください。
• 新しいリレーションシップの作成には allowed_upserts.relationships.relationship_types を使用します。詳しくは indykite-ciq-create-relationship を参照してください。
• リレーションシップのプロパティの更新には allowed_upserts.relationships.existing_relationships を使用します。
• プロパティの削除には <var>.property.<name> パスを指定して allowed_deletes.nodes を使用します。

読み取りについては、indykite-ciq-read を参照してください。

使用するタイミング

ユーザーが以下を希望する場合に、このスキルを有効にします。

• IKG にすでに存在するノードのプロパティを設定する（例：Person の music_mood を更新する、LicenseNumber の status を設定する、検証済みプロパティに assurance_level メタデータを付与する）。
• Person をサブジェクトとする「自身のデータを更新する」ポリシーを作成する（標準的なパターン：MATCH (subject:Person) + subject.external_id = $token.sub + existing_nodes: ["subject"]）。
• _Application をサブジェクトとする「システム側のプロパティ書き込み」ポリシーを作成し、AppAgent からたどれるノードを更新する。
• source、assurance_level、カスタムメタデータフィールドなどのプロパティメタデータを書き込む。
• 成功するはずのプロパティ書き込みの実行で 403 / 422 が返され、原因を調査している。

ユーザーが以下を希望する場合は、このスキルを有効にしないでください。

• 新しいノードを作成する場合は、indykite-ciq-create-node を使用してください。
• 新しいリレーションシップを作成して、既存の2つのノードを結び付ける場合は、indykite-ciq-create-relationship を使用してください。
• リレーションシップのプロパティを更新する場合は、別のポリシーフィールド（existing_relationships）を使用します。このスキルの対象外です。
• プロパティまたはノードを削除する場合は、別のポリシーフィールド（allowed_deletes）を使用します。
• データを読み取る場合は、indykite-ciq-read を使用してください。
• Capture API を使用してデータを取り込む場合は、別のデータ取り込み経路を使用します。

前提条件

• IndyKite のプロジェクト、AppAgent、および AppAgent の認証情報（実行時に AppAgent トークンを X-IK-ClientKey に指定します）。
• Config API にアクセスできる Service Account トークンと、PROJECT_GID に設定するプロジェクトの GID。どちらもポリシーと Knowledge Query の作成に使用します。
• 対象ノードがすでに IKG に存在すること。CIQ はノードを作成しません。このポリシーは、そのプロパティの変更を許可します。
• ポリシー／KQ が書き込むプロパティ名の明確な一覧。プロパティ名は KQ にハードコードする必要があります。$param にできるのは値とメタデータのみです。
• _Application 以外のサブジェクトの場合、サブジェクトのノードもすでに IKG に存在すること。

いずれかが不足している場合は作業を止め、ユーザーに伝えてください。先に不足分を解消するほうが、原因のはっきりしない 403 や空の結果を調査するよりもはるかに簡単です。

手順

1. 対象と Cypher アンカーを選択する

対象の種類 - いずれかを選択します。スキーマはどちらの選択肢でも同じで、異なるのは 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 つ作成してください。以下の実行可能な例では Person（「自身のプロフィールを更新」）を使用します。_Application の例（たとえば、imported_at タイムスタンプを補完する ETL ジョブ）では、subject.type、フィルター、実行時のヘッダーのみが異なります。

Cypher パターン - 更新対象のノードを解決する MATCH 句です。ここで使用する変数名は、existing_nodes と upsert_nodes[].name で参照されます。最も単純な例は MATCH (subject:Person)（対象ノードそのもの）です。より一般的な例では、パスをたどって関連ノードを指定します。例：MATCH (subject:Person)-[:OWNS]->(car:Car)-[:HAS]->(ln:LicenseNumber)。プロジェクトの IKG にある正確なノードの種類、リレーションシップの種類、プロパティ名が不明な場合は、まず Data Schema API から確認してください（indykite-data-schema）。名前に誤字があると何も一致せず、パターンに一致するものがない書き込みは何も行いませんが、それでも 200 が返されます。

実行例（このスキル全体で使用。音楽データセットの第 8 章 ciqpolicy4 に基づいています）：

Person が自身のプロフィールのプロパティ（例：music_mood、dance_skill）を更新します。

MATCH (subject:Person)

変数：subject。KQ は upsert_nodes でこの名前を参照します。

2. allowed_upserts.nodes.existing_nodes を使ってポリシーを作成する

次の 4 つのブロックを含むポリシー JSON を作成します。

• meta.policy_version - 現在は 1.0-ciq です。
• subject.type - 実行例では Person です。
• condition.cypher と condition.filter - 更新対象のノードをアンカーします。Person の場合、subject.external_id = $token.sub でフィルターします。
• allowed_upserts.nodes.existing_nodes - プロパティへの書き込みを Knowledge Query に許可する、cypher 内の変数の配列です。Knowledge Query の upsert_nodes[].name は、このリストに含まれている必要があります。

このポリシーでプロパティのみを書き込む場合は、allowed_reads、allowed_deletes、およびその他の allowed_upserts サブフィールドを省略します。実際には allowed_reads と組み合わせることもよくあります（読み取りと自身のプロフィールの更新を行うパターン）が、ここでは説明を明確にするため対象外としています。

実行例の書き込み専用ポリシーの全体は、assets/policy-update-own-profile.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' indykite-ciq-add-property/assets/policy-update-own-profile.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 に挿入されます。

スキーマの全体（node_types を省略する理由、_Application の例、policyMetaData のメタデータの例）については、references/policy-reference.md を参照してください。

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

ナレッジクエリーはポリシーを参照します。upsert_nodes の各エントリーは、ノードの更新を記述します。

• name - ポリシーの cypher 内の変数と必ず一致させてください（例：subject、car、ln）。これが作成ノードのスキルとの構造上の違いです。ここで新しい名前を使うと、作成を意味することになります。
• type - 既存のノードを更新する場合は省略します。（作成の場合は新しいノードのラベルを指定しますが、更新の場合はマッチしたノードのラベルが使われます。）
• external_id - 省略します。作成の場合にのみ必須です。
• properties - {type, value, metadata?} アイテムの配列です。type（プロパティ名）はハードコードされており、value はハードコードするか $param を指定できます。metadata は省略可能で、同じルールに従います。

結果に、トップレベルの nodes 配列で投影するプロパティを列挙して返します（例：subject.property.music_mood）。これにより、書き込まれた値を確認できます。

実行例を網羅したナレッジクエリーについては、assets/knowledge-query-update-own-profile.json を参照してください。

Config API で作成します。

# 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' indykite-ciq-add-property/assets/knowledge-query-update-own-profile.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）が含まれます。

設定できない保護対象のプロパティ名（_service、create_time、external_id、id、type、update_time）、メタデータのサブ配列、$token.iss の置換を含む knowledgeQueryMetaData の詳細な例など、スキーマの詳細は references/knowledge-query-reference.md を参照してください。

4. 認証して実行する

実行エンドポイントは、読み取り、ノード作成、リレーションシップ作成の場合と同じです。

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

実行例の Person を対象とした認証：

• X-IK-ClientKey: <AppAgent-credentials-token> - 必須です。
• Authorization: Bearer <user-access-token> - 必須です。トークンの sub クレームが $token.sub としてポリシーフィルターで使われ、Cypher のアンカーがそのユーザーに限定されます。

_Application を対象とするプロパティ書き込みでは、Bearer ヘッダーを省略してください。予約済みの $_appId は AppAgent から自動的に設定されます。

リクエスト：

{
  "id": "<knowledge_query_gid_or_name>",
  "input_params": {
    "new_music_mood":  "Acoustic Sadness",
    "new_dance_skill": 0.67
  }
}

実行可能なシェルヘルパー：scripts/execute.sh。

実行に関する完全なリファレンス（認証の組み合わせ、レスポンスの形式、エラーの意味）：references/execution-reference.md。

5. レスポンスを検証し、プロパティの書き込みを確認する

プロパティ書き込みの実行が成功すると、KQ の nodes 配列に列挙した投影が返されます。

{
  "data": [
    {
      "nodes": {
        "subject.property.music_mood":  "Acoustic Sadness",
        "subject.property.dance_skill": 0.67
      }
    }
  ]
}

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

1. existing_nodes 内の変数。 KQ の upsert_nodes[].name は、ポリシーの allowed_upserts.nodes.existing_nodes に含まれている必要があります。一致しない場合 → 403。
2. Cypher がノードにマッチしていること。 Cypher が行を返さない場合（例：ユーザーの external_id が Person としてシードされていない場合）、アップサート先がなくなります。その場合は 200 で data が空になります。
3. name が Cypher の変数と一致していること。 新しい名前（Cypher に存在しない名前）を使うと、プラットフォームはそのエントリーを作成として解釈します。一致する node_types の許可リストがないため、通常は拒否されます。
4. upsert_nodes エントリーに external_id がないこと。 external_id を含めると、操作のセマンティクスが「作成」に切り替わります。既存のマッチに対するプロパティ書き込みでは、省略してください。
5. プロパティ名が保護対象ではないこと。 _service、create_time、external_id、id、type、update_time はプロパティとして設定できません。これらはプラットフォームによって管理されます。
6. プロパティ値の型が IKG スキーマと一致していること。 数値プロパティに "-7.5"（文字列）を送信すると、拒否されます。

その他の失敗ケース（認証形式の誤り、input_params の不足、メタデータの問題など）については、references/troubleshooting.md を参照してください。

成果

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

• プロパティ書き込み用の CIQ ポリシーが存在します。このポリシーには単一の subject.type、更新対象のノードを特定する Cypher パターン、任意の部分フィルター、ホワイトリストとしての allowed_upserts.nodes.existing_nodes が含まれます。node_types、allowed_reads、allowed_deletes は含まれません。
• Knowledge Query はそのポリシーを参照し、Cypher の変数名を再利用する upsert_nodes エントリーを列挙します。external_id は省略し、設定するプロパティ（および任意のメタデータ）を宣言します。
• POST /contx-iq/v1/execute が投影されたプロパティ値を返し、書き込みが確認されます。
• その後の読み取りクエリ（例：indykite-ciq-read を使用）で、ノードに新しいプロパティ値が設定されていることを確認できます。

このスキルのファイル

• references/policy-reference.md - 書き込みに特化したポリシースキーマ、existing_nodes の詳細、Person と _Application のパターン、その他のブロックを省略する理由。
• references/knowledge-query-reference.md - 更新用の upsert_nodes（Cypher の変数を使用し、external_id は指定しない）、プロパティとメタデータ、knowledgeQueryMetaData の詳細な例、保護対象のプロパティ名。
• references/execution-reference.md - プロパティ書き込み用の POST /contx-iq/v1/execute、認証の組み合わせ、詳細な Props ブロックを含むレスポンス形式。
• references/troubleshooting.md - 403／空の data／型の不一致／メタデータのパターン。
• assets/policy-update-own-profile.json - music-dataset Chapter 8 の ciqpolicy4 をモデルにした、実行可能な Person を subject とする「自分のプロフィールを更新する」ポリシー。
• assets/knowledge-query-update-own-profile.json - 対応する Knowledge Query（music_mood と dance_skill を設定）。
• scripts/execute.sh - 適切なヘッダーを指定して /contx-iq/v1/execute に POST する Bash ヘルパー。

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

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

参考資料

• ContX IQ ガイド（開発者ハブ） - allowed_upserts.nodes.existing_nodes と properties／metadata 配列を含む完全なスキーマ。
• Music dataset チュートリアル - Chapter 8「ContX IQ policies」 - ciqpolicy4 は Person を subject とする「自分のデータを更新する」パターンの標準例です。kq4b はその書き込み用バリアントです。
• Music dataset チュートリアル - Chapter 9「Knowledge Queries」 - 読み取り／書き込み／削除のバリアントにおける命名規則（kq／kqb／kqc）。
• 開発者ハブのリソース - CIQ の例 - policyMetaData と knowledgeQueryMetaData で、$token.iss の置換とプロパティごとのメタデータを使う、より詳細なプロパティ書き込みパターンを紹介しています。
• Config API ドキュメント
• Cypher クエリ言語マニュアル（Neo4j、openCypher） - IndyKite Knowledge Graph 上の CIQ ポリシーと Knowledge Query の条件で使用されるグラフクエリ言語。
• IndyKite Terraform provider
• 認証情報ガイド