indykite-ciq-add-relationship-property

IndyKite ContX IQ - 既存のリレーションシップにプロパティを追加する

ContX IQ ポリシーと Knowledge Query を使用して、IndyKite Graph（IKG）にすでに存在するリレーションシップのプロパティを設定または上書きし、POST /contx-iq/v1/execute で実行します。ポリシーでは、cypher で一致したリレーションシップのうち変更を許可するものをホワイトリストに登録します（allowed_upserts.relationships.existing_relationships）。Knowledge Query の upsert_relationships では、これらの変数を参照し、設定するプロパティをメタデータとともに任意で指定します。リレーションシップはすでに存在するため、source／target／type は指定しません。新しいプロパティの追加も既存プロパティの上書きも、同じ操作です。プラットフォームでは区別されません。

このスキルは、既存のノードにプロパティを設定する indykite-ciq-add-property に対応する、リレーションシップ向けのスキルです。構造は対称的で、フィールド名が異なります。

次の操作は意図的に対象外です。

• 新しいリレーションシップの作成には、allowed_upserts.relationships.relationship_types と、新しい name および source／target／type を指定した Knowledge Query の upsert_relationships エントリを使用します。詳しくは indykite-ciq-create-relationship を参照してください。
• ノードへのプロパティ設定には、allowed_upserts.nodes.existing_nodes を使用します。詳しくは indykite-ciq-add-property を参照してください。
• リレーションシップのプロパティ削除には、<var>.<property> のパスを指定して allowed_deletes.relationships を使用します。詳しくは indykite-ciq-delete を参照してください。

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

使用するタイミング

次の場合にこのスキルを有効にします。

• ユーザーが、IKG にすでに存在するリレーションシップのプロパティを設定したい場合（例：既存の :PLAYED_AT に verified: true を追加する、既存の :LIKES に weight を設定する、既存の :OWNS エッジに confidence メタデータを付与する）。
• 既存のリレーションシップに、後からプロベナンス、信頼スコア、または監査フィールドを追加している場合。
• 成功するはずのリレーションシッププロパティ書き込みの実行で、403／422 が発生する原因を調査している場合。

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

• 既存の2つのノード間に新しいリレーションシップを作成したい場合。 indykite-ciq-create-relationship を使用してください。
• ノードにプロパティを設定したい場合。 indykite-ciq-add-property を使用してください。
• プロパティを削除したい場合。 indykite-ciq-delete を使用してください。
• データを読み取りたい場合。 indykite-ciq-read を使用してください。
• Capture API を使用してデータを取り込む場合。取り込み経路が異なります。

前提条件

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

これらが不足している場合は、作業を中断してユーザーに伝えてください。先に解決しておくほうが、原因のはっきりしない 403 や空の結果をデバッグするよりも、はるかに簡単です。

手順

1. サブジェクトとサイファーのアンカーを選択する

サブジェクトの種類 - いずれか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つ作成してください。以下の実行可能な例では _Application を使用しています（既存のエッジに対するシステム側のアノテーション処理）。Person の例（たとえば、ユーザーが自身の :LIKES エッジに priority を設定する場合）では、異なるのは subject.type、フィルター、実行ヘッダーのみです。

サイファーのパターン - 既存のリレーションシップを MATCH し、変数にバインドする必要があります。変数名は existing_relationships と upsert_relationships[].name が参照します。リレーションシップを一意に特定できるよう、フィルター内で両方のエンドポイントを external_id によって固定してください。プロジェクトの IKG における正確なノードの種類、リレーションシップの種類、プロパティの表記が不明な場合は、まず Data Schema API から確認してください（indykite-data-schema）。名前のタイプミスは何も一致しなくてもエラーにならず、パターンに何も一致しない書き込みは、200 を返すだけで何も行いません。

使用例（このスキル全体で使用）：

_Application が既存の (:Track)-[:PLAYED_AT]->(:Venue) リレーションシップに verified フラグと first_played_at タイムスタンプを設定して注釈を付けます。

MATCH (subject:_Application)
MATCH (track:Track)-[r:PLAYED_AT]->(venue:Venue)

変数は subject、track、r、venue です。リレーションシップ変数 r を更新します。

2. allowed_upserts.relationships.existing_relationships を使ってポリシーを作成する

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

• meta.policy_version - 現在は 1.0-ciq です。
• subject.type - 実行例では _Application です。
• condition.cypher と condition.filter - サイファーで既存のリレーションシップを照合し、フィルターで subject.external_id = $_appId（予約済み）と、ソースおよびターゲットのエンドポイントを external_id によって固定します。
• allowed_upserts.relationships.existing_relationships - サイファー内のリレーションシップ変数の配列です。Knowledge Query がそのプロパティに書き込めるようにします。Knowledge Query の upsert_relationships[].name はこのリストに含まれている必要があります。

このポリシーでリレーションシップのプロパティのみを書き込む場合は、allowed_reads、allowed_deletes、その他の allowed_upserts サブフィールドを省略してください。

実行例の書き込み専用ポリシー全体は、assets/policy-annotate-played-at.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-relationship-property/assets/policy-annotate-played-at.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 に挿入されます。

スキーマ全体（relationship_types を省略する理由、Person のバリエーション、保護対象のプロパティ名）については、references/policy-reference.md を参照してください。

3. upsert_relationships を使用してナレッジクエリを作成する

ナレッジクエリではポリシーを参照します。upsert_relationships の各エントリは、関係の更新を 1 つ記述します。

• name - ポリシーの cypher にある関係変数（例：r）と一致する必要があります。ここが、関係作成スキルと構造上異なる点です。ここで新しい名前を使うと、作成を意味します。
• source / target / type - 既存の関係を更新する場合は省略します。エンドポイントとラベルは、一致したエッジから取得されます。指定する必要はなく、指定するとプラットフォームで混乱が生じる可能性があります。
• properties - {type, value, metadata?} アイテムの配列です。ノードの場合と同じ形式です。

最上位の relationships および／または nodes 配列に、投影するプロパティを列挙して、レスポンスに結果を含めてください。

実行中の例に対応する完全なナレッジクエリについては、assets/knowledge-query-annotate-played-at.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-relationship-property/assets/knowledge-query-annotate-played-at.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、id、type、update_time）や、メタデータのサブ配列を含むスキーマの詳細は、references/knowledge-query-reference.md を参照してください。

4. 認証して実行する

実行エンドポイントは、読み取り、ノードプロパティの書き込み、関係作成スキルの場合と同じです。

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

実行中の _Application 対象の例における認証：

• X-IK-ClientKey: <AppAgent-credentials-token> - 必須です。
• Authorization: Bearer … - _Application の場合は省略します。

Person 対象の関係プロパティを書き込む場合は、Authorization: Bearer <user-access-token> を追加します。

リクエスト：

{
  "id": "<knowledge_query_gid_or_name>",
  "input_params": {
    "track_external_id": "track-99",
    "venue_external_id": "venue-1",
    "first_played_at":   "2026-04-22T19:00:00Z"
  }
}

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

実行に関する詳細なリファレンス：references/execution-reference.md。

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

関係プロパティの書き込みが成功すると、リクエストした投影が返されます。

{
  "data": [
    {
      "relationships": {
        "r": {
          "Id": 1152932499723124700,
          "ElementId": "5:3a2b09d5-…:1152932499723124736",
          "Props": {
            "verified":         true,
            "first_played_at":  "2026-04-22T19:00:00Z"
          }
        }
      }
    }
  ]
}

レスポンスが期待したものと異なる場合は、次の項目を確認してください。

1. existing_relationships 内の変数。 KQ の upsert_relationships[].name は、ポリシーの existing_relationships リストに含まれている必要があります。一致しない場合 → 403。
2. Cypher が関係に一致したか。 cypher が行を返さない場合（例：ソースまたはターゲットの external_id がシードされていない、あるいは :PLAYED_AT エッジが存在しない場合）、アップサートの対象はありません。200 で data は空になります。
3. name が cypher 変数と一致するか。 新しい名前を使うと作成を意味し、relationship_types も宣言されていない限り拒否されます。
4. upsert_relationships のエントリに source / target / type がないこと。 これらのいずれかを含めると、操作は「作成」のセマンティクスに切り替わります。
5. 保護されていないプロパティ名であること。 _service、create_time、id、type、update_time は、関係のプロパティとして設定できません。

その他の失敗例については、references/troubleshooting.md を参照してください。

結果

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

• 関係プロパティ書き込み用の CIQ ポリシーが存在します。このポリシーには単一の subject.type、更新対象の関係に一致する Cypher パターン、external_id でエンドポイントを固定する部分フィルター、allowed_upserts.relationships.existing_relationships の許可リストが含まれています。
• ナレッジクエリがそのポリシーを参照し、cypher 変数名を再利用し、source / target / type を省略して、設定するプロパティを宣言した upsert_relationships エントリを列挙します。
• POST /contx-iq/v1/execute が投影されたプロパティ値を返し、書き込みが確認されます。
• 後続の読み取り（例：indykite-ciq-read による読み取り）で、関係に新しいプロパティ値が見つかります。

このスキルのファイル

• references/policy-reference.md - ポリシースキーマ、existing_relationships の詳細、他のブロックを省略する理由。
• references/knowledge-query-reference.md - 更新用の upsert_relationships（cypher からの変数であり、source／target／type はありません）、プロパティとメタデータ、保護された名前。
• references/execution-reference.md - リレーションシッププロパティを書き込む POST /contx-iq/v1/execute と、リレーションシップの Props ブロックを含むレスポンス形式。
• references/troubleshooting.md - 症状 → 解決方法の表。
• assets/policy-annotate-played-at.json - 実行可能な _Application による :PLAYED_AT ポリシーの注釈付け。
• assets/knowledge-query-annotate-played-at.json - 対応する Knowledge Query。
• scripts/execute.sh - Bash ヘルパー。

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

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

参考資料

• ContX IQ guide (developer hub) - allowed_upserts.relationships.existing_relationships を含む、スキーマ全体。
• Music dataset tutorial - Chapter 8 "ContX IQ policies" and Chapter 9 "Knowledge Queries" - 読み取り／書き込み／削除のバリアントの命名規則。
• Developer-hub resources - CIQ examples - policyMetaData／knowledgeQueryMetaData のペアは、同様のノードプロパティ書き込みの例を示しています。このスキルでは、同じパターンをリレーションシップ変数に適用します。
• Config API documentation
• Cypher query language manual (Neo4j; openCypher) - IndyKite Knowledge Graph に対する CIQ ポリシーと Knowledge Query の条件で使用されるグラフクエリ言語。
• IndyKite Terraform provider