indykite-ciq-create-relationship

IndyKite ContX IQ - 新しいリレーションシップを作成する

IndyKite Graph（IKG）にすでに存在する2つのノード間に、新しいリレーションシップを作成します。ContX IQ ポリシーと Knowledge Query に基づいて処理し、POST /contx-iq/v1/execute で実行します。ポリシーでは、allowed_upserts.relationships.relationship_types のホワイトリストに {type, source_node_label, target_node_label} の組を定義し、cypher で2つの端点ノードを照合します。Knowledge Query の upsert_relationships 配列では、新しいリレーションシップを指定し、source と target でこれらの cypher 変数を参照します。端点ノードはすでに存在している必要があります。作成されるのはリレーションシップのみです。

このスキルの対象は、既存の2つのノード間のリレーションシップ作成のみです。それ以外の方法は対象外です。

• 新しいノードの作成には allowed_upserts.nodes.node_types と upsert_nodes を使用します。詳細は indykite-ciq-create-node を参照してください。
• 新しいノードへのリレーションシップの作成には、両方を組み合わせます。新しいノードを指定する upsert_nodes エントリと、source または target が新しい name を指す upsert_relationships エントリを使用します。スキーマはこの方法をサポートしていますが、このスキルではわかりやすさを優先し、既存の2つの端点を使う例に限定しています。下部の「新しい端点への対応」を参照してください。
• 既存のリレーションシップのプロパティ更新には allowed_upserts.relationships.existing_relationships を使用します。
• 削除には allowed_deletes.relationships を使用します。

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

使用する場面

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

• 新しいリレーションシップで既存の2つのノードをリンクしたい場合（例：Person -[:ACCEPTED]-> Contract、Track -[:PLAYED_AT]-> Venue、User -[:OWNS]-> Document）。
• システム側のリレーションシップ取り込みのため、_Application をサブジェクトとする「カタログ配線」ポリシーと Knowledge Query を作成する場合。
• ソース／ターゲットの external_id と（任意で）新しいリレーションシップのプロパティを、実行時の input_params から指定する場合。
• リレーションシップを作成するはずの POST /contx-iq/v1/execute 呼び出しがリレーションシップを作成せず、403／422 が返される問題をデバッグする場合。

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

• 新しいノードを作成したい場合（別のノードからのリレーションシップを伴うかどうかは問いません）。indykite-ciq-create-node を使用してください。
• IKG からデータを読み取りたい場合。 indykite-ciq-read を使用してください。
• 既存のリレーションシップのプロパティを更新したい場合。別のポリシーフィールド（existing_relationships）と KQ の形式を使用します。
• リレーションシップを削除したい場合。別のポリシーフィールド（allowed_deletes.relationships）と KQ 配列を使用します。
• CIQ ではなく Capture API（POST /capture/v1/relationships）または Terraform を使ってリレーションシップを取り込みたい場合。これらは別の取り込み方法です。

前提条件

• IndyKite のプロジェクト、AppAgent、および AppAgent の認証情報（実行時に AppAgent トークンを X-IK-ClientKey に指定します）。
• Config API にアクセスできる Service Account トークンと、PROJECT_GID に指定するプロジェクトの GID。どちらもポリシーと Knowledge Query の作成に使用します。
• 両方の端点ノードが、安定した external_id とともにすでに IKG に存在すること。CIQ は端点ノードを作成しません。このポリシーは、既存の2つのノードをつなぐことを許可します。
• リレーションシップラベル（PLAYED_AT、ACCEPTED、OWNS など）と、それがつなぐソース／ターゲットのノードラベル。どちらも IKG スキーマですでに許可されているものと一致している必要があります。
• _Application 以外のサブジェクトの場合、サブジェクトのノードもすでに IKG に存在していること。

いずれかが不足している場合は、作業を中断してユーザーに伝えてください。あいまいな 403 や 422 のデバッグよりも、先に問題を解決するほうがはるかに簡単です。

手順

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 つ作成してください。以下の実行可能な例では _Application（システム側の設定）を使用しています。Person の例（ユーザーが Contract を受諾する場合など）で異なるのは、subject.type、フィルター、実行時のヘッダーのみです。

Cypher パターン - 両端のノードと対象の両方に対して MATCH する必要があります。必要な他のパスを介して両端が接続されていない場合は、個別の MATCH 句（スペースで区切ります）を使用します。プロジェクトの IKG で正確なノードの種類、リレーションシップの種類、またはプロパティ名が不明な場合は、まず Data Schema API から読み取ってください（indykite-data-schema）。名前の誤記があっても何も一致せず、パターンに一致するものがない書き込みは、何も実行されないまま 200 を返します。

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

音楽データセットのドメイン：external_id が与えられた既存の Track から既存の Venue への PLAYED_AT リレーションシップを、_Application が追加します。

MATCH (subject:_Application)
MATCH (track:Track)
MATCH (venue:Venue)

ポリシーと KQ の残りの部分で参照する変数：subject、track、venue。新しいリレーションシップは KQ で宣言するため、Cypher には記述しません。

新しいエッジを追加する前に、既存のパスを通じて両端に到達できるよう制約する必要がある場合は、代わりに接続されたパターンを使用してください。たとえば、PLAYED_AT リンクを許可する前に、Track と Venue が既存の :CATALOGED_BY リレーションシップを共有していることを必須にできます。この判断は Cypher で行います。

2. allowed_upserts.relationships.relationship_types を使用してポリシーを作成する

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

• meta.policy_version - 現在は 1.0-ciq です。
• subject.type - 実行例では _Application です。
• condition.cypher と condition.filter - 対象を指定し、external_id で両端を固定します。_Application の場合は subject.external_id = $_appId（予約済み、自動入力）でフィルターします。各端点について、external_id を $param に対してフィルターします。
• allowed_upserts.relationships.relationship_types - Knowledge Query が新しいリレーションシップとして作成できる {type, source_node_label, target_node_label} の組の配列です。

このポリシーでリレーションシップの作成のみを許可する場合は、allowed_reads、allowed_deletes、その他の allowed_upserts サブフィールドは省略します。操作を禁止するには、そのブロックを省略する方法がサポートされています。

実行例の完全なリレーションシップ作成ポリシーについては、assets/policy-create-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-create-relationship/assets/policy-create-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 の組、および existing_relationships と node_types を省略する理由）については、references/policy-reference.md を参照してください。

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

ナレッジクエリではポリシーを参照し、何を書き込むかを指定します。upsert_relationships の各エントリは、新しいリレーションシップを 1 つ記述します。

• name - ポリシーの cypher で使われていない一意の変数名です。慣例として、new を先頭に付けるか、ドメイン固有の名詞を使います。レスポンスでは、この名前が新しいリレーションシップの識別子を格納するキーとして使われます。
• source - ポリシーの cypher にある始点の変数名です。relationship_types[].source_node_label で宣言された値と一致する必要があります。
• target - ポリシーの cypher にある終点の変数名です。target_node_label と一致する必要があります。
• type - リレーションシップのラベルです。ポリシーの relationship_types[].type と一致する必要があります。
• properties - 任意です。{type, value} アイテムの配列です。ノードプロパティとは異なり、リレーションシッププロパティには metadata を指定できません（ナレッジクエリの保存時に、metadata キーは不明なフィールドとして拒否されます）。詳細は references/knowledge-query-reference.md を参照してください。

レスポンスに新しいリレーションシップを含めるには、トップレベルの relationships 配列にその変数名を指定します。

実行中の例を網羅したナレッジクエリについては、assets/knowledge-query-create-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-create-relationship/assets/knowledge-query-create-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）が含まれます。

4. 認証して実行する

実行エンドポイントは、読み取りやノード作成の場合と同じです。

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

実行中の _Application をサブジェクトとする例の認証方法は次のとおりです。

• X-IK-ClientKey: <AppAgent-credentials-token> - 必須です。
• Authorization: Bearer … - _Application の場合は省略します。予約済みの $_appId は、アプリケーションの external_id から自動入力されます。

Person をサブジェクトとするリンク作成フローでは、Authorization: Bearer <user-access-token> を追加し、ポリシーで subject.external_id = $token.sub のフィルターを指定してください。

リクエスト：

{
  "id": "<knowledge_query_gid_or_name>",
  "input_params": {
    "track_external_id": "track-99",
    "venue_external_id": "venue-1"
  }
}

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

実行の詳細（認証、リクエスト／レスポンス、エラーの意味）については、references/execution-reference.md を参照してください。

5. レスポンスを確認し、新しいリレーションシップを確かめる

リレーションシップ作成の実行に成功すると、射影されたノードに加え、変数名をキーとした内部グラフ識別子を含む relationships ブロックが返されます。

{
  "data": [
    {
      "nodes": {
        "track.external_id": "track-99",
        "venue.external_id": "venue-1"
      },
      "relationships": {
        "newPlayedAt": {
          "Id": 1152932499723124700,
          "ElementId": "5:3a2b09d5-…:1152932499723124736",
          "StartId": 0,
          "StartElementId": "4:3a2b09d5-…:0",
          "EndId": 15
        }
      }
    }
  ]
}

Id／ElementId は、新しいエッジに割り当てられたプラットフォーム内部の識別子です。使用する必要はありませんが、エッジが書き込まれたことを確認できます。

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

1. 両方のエンドポイントが存在する。 ポリシーの cypher が実際に一致する必要があります。track.external_id または venue.external_id がシードされていない場合、cypher は行を返さず、upsert_relationships が関連付ける対象もありません。
2. トリプルが一致する。 KQ の (source, target, type) は、ポリシーの relationship_types[] のトリプルと一致する必要があります。ラベル（cypher 変数経由）と type の両方が一致していなければなりません。
3. 変数が cypher に存在する。 source と target はラベルではなく、cypher の変数名です。"source": "track"（変数名）の代わりに "source": "Track"（ラベル）と指定すると、リクエストは失敗します。
4. name が未使用である。 新しいリレーションシップの name は、ポリシーの cypher にある既存の変数と重複してはいけません。
5. リレーションシップがまだ存在していない。 同じ source／target ペアで再実行すると、重複を作成する代わりにアップサート（既存のエッジとの一致）になります。

その他の失敗（認証形式の誤り、input_params の不足、不正な JSON）については、references/troubleshooting.md を参照してください。

新しいエンドポイントへの適用

1 回の実行でターゲットノードとリレーションシップを作成する必要がある場合、たとえば新しい Comment を作成して既存の Document にリンクする場合は、このスキルのパターンと indykite-ciq-create-node を組み合わせます。

• ポリシー：新しいノードラベル用の allowed_upserts.nodes.node_types と、新しいエッジ用の allowed_upserts.relationships.relationship_types の両方を含めます。
• Knowledge Query：新しいノードの upsert_nodes エントリと、source または target が新しいノードの name である upsert_relationships エントリを含めます。

2 つのスキルでそれぞれの部分を扱います。組み合わせるには、両側に upsert_* 配列エントリを 1 つ追加するだけです。各操作はポリシーで許可リストに登録する必要があります。

成果

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

• リレーションシップ作成用の CIQ ポリシーが存在します。subject.type は 1 つで、両方のエンドポイントノードに一致する Cypher パターンがあり、external_id でノードを特定する部分フィルターと、allowed_upserts.relationships.relationship_types の許可リストが設定されています。node_types、existing_relationships、allowed_reads（意図的に追加した場合を除く）、allowed_deletes はありません。
• Knowledge Query がそのポリシーを参照し、新しいリレーションシップを upsert_relationships にちょうど 1 つ記載しています。新しい name、cypher の source/target 変数、適切な type が設定されています。
• POST /contx-iq/v1/execute が、投影されたノードと新しいリレーションシップの内部識別子を含む data を返します。
• 後続の読み取り（例：indykite-ciq-read 経由）で、IKG 内に新しいエッジが見つかります。

このスキルのファイル

• references/policy-reference.md - リレーションシップ作成ポリシーのスキーマ、{type, source_node_label, target_node_label} の 3 要素、他のブロックを省略する理由。
• references/knowledge-query-reference.md - upsert_relationships のスキーマ、任意のプロパティ、新しいリレーションシップの返し方。
• references/execution-reference.md - リレーションシップの書き込みに使う POST /contx-iq/v1/execute、認証の組み合わせ、Id / ElementId / StartId / EndId を含むレスポンス形式。
• references/troubleshooting.md - 403 / 422 / Cypher の一致なし / 変数とラベルの混同について、症状 → 原因 → 解決方法を示す表。
• assets/policy-create-played-at.json - 実行可能な _Application → (Track)-[:PLAYED_AT]->(Venue) ポリシー。
• assets/knowledge-query-create-played-at.json - 対応する Knowledge Query。
• scripts/execute.sh - 適切なヘッダーを付けて /contx-iq/v1/execute に POST する Bash ヘルパー。

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

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

参考資料

• ContX IQ ガイド（開発者ハブ）
• 音楽データセットのチュートリアル — 第 8 章「ContX IQ ポリシー」と第 9 章「ナレッジクエリ」 — 実際のグラフに対する読み取り／書き込み／削除の具体的なパターンです。kqb パターンは、リレーションシップ作成の標準的なパターンです。
• 開発者ハブのリソース — CIQ の例 — リソースのサンプルに、実行可能な policyAllowUpsertRelationships と knowledgeQueryUpsertRelationships のペアが含まれています。
• Config API のドキュメント
• Cypher クエリ言語マニュアル（Neo4j、openCypher） — IndyKite Knowledge Graph に対する CIQ ポリシーとナレッジクエリの条件で使われるグラフクエリ言語です。
• IndyKite Terraform プロバイダー — indykite_authorization_policy と indykite_knowledge_query
• 認証情報ガイド