indykite-ciq-create-node-with-link

IndyKite ContX IQ - 新しいノードを作成し、既存のノードにリンクする

IndyKite Graph（IKG）に新しいノードを作成し、単一のアトミックな POST /contx-iq/v1/execute 呼び出しで、1つ以上の既存ノードに接続します。ポリシーでは、ノードラベルと1つ以上のリレーショントリプルを許可リストに登録します。また、Knowledge Query には、新しいノード用の upsert_nodes と、新しいエッジ用の upsert_relationships の両方を含めます。upsert_nodes の新しいノードの変数 name は、upsert_relationships の source または target として参照します。これは、indykite-ciq-create-node と indykite-ciq-create-relationship のパターンを組み合わせたものです。

これは、「新しいエンティティをグラフに取り込む」ための標準的なパターンです。IndyKite の開発者ハブのリソースでは、保険の Contract の例（policyAllowWriteContract と knowledgeQueryAllowWriteContract）で使用されています。この例では、1回の execute で新しい Contract ノードを作成し、2つのリレーションシップ（Vehicle への COVERS、Person からの ACCEPTED）を通じて接続します。

以下の用途は意図的に対象外としています。

• ノードだけを作成し、リンクしない場合 - indykite-ciq-create-node を使用します。
• 既存の2つのノードだけをリンクする場合 - indykite-ciq-create-relationship を使用します。
• 既存のノードのプロパティまたはリレーションシップのプロパティを更新する場合 - まったく別の操作です。

使用する場面

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

• CIQ を通じて、1つのアトミックな操作で新しいエンティティを取り込む（ノードを作成し、既存ノードとのリレーションシップも作成する）。
• 標準的な保険／契約のパターンを実装する。既存の Vehicle と既存の Person にリンクされた新しい Contract ノードを作成する。
• 「ドキュメントにコメントを追加する」フローを構築する。新しい Comment ノードを既存の Document にリンクする。
• 新しいノードの external_id と、source／target のエンドポイントの両方を input_params からパラメーター化する。
• 新しいノードを正しく接続するはずの、ノード作成を組み合わせた execute で 403／422 が発生する問題をデバッグする。

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

• ノードの作成だけが必要な場合 - indykite-ciq-create-node を使用します。
• 既存の2つのノードのリンクだけが必要な場合 - indykite-ciq-create-relationship を使用します。
• 既存の要素にプロパティを書き込む必要がある場合 - プロパティ書き込み用のスキルを使用します。

前提条件

• IndyKite のプロジェクト、AppAgent、および AppAgent の認証情報。
• Config API にアクセスできる Service Account トークンと、PROJECT_GID に設定されたプロジェクトの GID。どちらもポリシーと Knowledge Query の作成に使用します。
• 新しいノードのリンク先となるエンドポイントノードが、すでに IKG に存在すること。
• 操作で使用するノードラベルとリレーションシップラベルが、プロジェクトのデータモデルで許可されていること。
• 新しいノードの external_id の設定方針が決まっていること。通常は $param を使ってパラメーター化します。

手順

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つ作成してください。以下の実行可能な例では _Application を使用します（保険契約の取り込み）。Person の例（たとえば、ユーザーが自身の所有する既存の Document に関連付けた新しい Comment を投稿する場合）では、subject.type、フィルター、実行時のヘッダーのみが異なります。

Cypher パターン - 対象と、新しいノードがリンクする既存のすべてのエンドポイントを MATCH する必要があります。新しいノード自体は MATCH しません。upsert_nodes で宣言します。プロジェクトの IKG における正確なノードの種類、リレーションシップの種類、プロパティの表記が不明な場合は、まず Data Schema API から確認してください（indykite-data-schema）。名前に誤字があると一致するものはなく、パターンが何にも一致しない書き込みは、何も行わずに 200 を返します。

使用例（このスキル全体で使用。developer-hub の policyAllowWriteContract リソースからそのまま引用）：

_Application が新しい Contract ノードを作成し、既存の Company が所有する既存の Vehicle に :COVERS でリンクし、既存の Person から :ACCEPTED でリンクします。

MATCH (subject:_Application)-[r1:HAS_AGREEMENT_WITH]->(company:Company)-[r2:OWNS]->(vehicle:Vehicle)
MATCH (person:Person)

変数：subject、r1、company、r2、vehicle、person。新しい Contract ノードは、upsert_nodes で新規の name として宣言します。2つの新しいリレーションシップでは、エンドポイントとして vehicle、person、新規の name を参照します。

2. node_types と relationship_types の両方を指定してポリシーを作成する

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

• meta.policy_version - 現在は 1.0-ciq です。
• subject.type - 実行例では _Application です。
• condition.cypher と condition.filter - cypher で対象と既存のエンドポイントを照合します。フィルターでは、external_id（$_appId と $vehicleID、$personID）でそれらを固定します。
• allowed_upserts.nodes.node_types - 新しいノードのラベル（例：["Contract"]）。
• allowed_upserts.relationships.relationship_types - 新しいリレーションシップごとに1つのトリプルを指定し、方向とラベルを一致させます。

実行例のノードとリレーションシップをまとめて作成するポリシー全体については、assets/policy-create-contract.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-node-with-link/assets/policy-create-contract.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 の create がこれを policy_id に注入します。

スキーマの詳細（node_types と relationship_types の連携、方向が重要な理由、existing_nodes を追加した場合の内容）については、references/policy-reference.md を参照してください。

3. upsert_nodes と upsert_relationships の両方を使用してナレッジクエリを作成する

ナレッジクエリには、2 つの書き込み用配列があります。

upsert_nodes - 新しいノードを宣言します。indykite-ciq-create-node と同じ形式です。

• name - 新しい変数名（cypher 内では未使用のもの）、例：contract。
• type - ノードのラベル。allowed_upserts.nodes.node_types と一致する必要があります。
• external_id - 新しいノードでは必須です。通常は $param を指定します。
• is_identity - 任意のブール値です。true にすると、以下の注記にあるように、ノードがアイデンティティノードとして作成されます。
• labels - type とともに付与する追加ラベルの任意の配列です。
• properties - {type, value, metadata?} 項目の配列です。

アイデンティティノード。 upsert_nodes エントリーに "is_identity": true を設定します。Capture API と同じフラグです。これにより DigitalTwin ラベルが追加されます。IKG はこのラベルでアイデンティティノードを識別します。"labels": ["DigitalTwin"] でも同じ結果になりますが、フラグの使用をおすすめします。キーのスペルを間違えるとナレッジクエリの保存時に拒否されますが、ラベルのスペルを間違えても、単なる別のラベルとしてそのまま保存されます。どちらもポリシーの node_types 許可リストには含めません。このリストでは type のみがチェックされます。2.0-kbac のサブジェクトとして機能させる必要がある場合は、必ずノードをアイデンティティノードとして作成してください。アイデンティティではないサブジェクトでは、2.0-kbac の判定はすべてエラーなく false になります（3.0-kbac では不要です）。ラベルが付与されたことを確認するには、新しいノードをサブジェクトとして 2.0-kbac の評価を実行します。

upsert_relationships - 新しいリレーションシップをそれぞれ宣言します。indykite-ciq-create-relationship と同じ形式ですが、重要な違いが 1 つあります。

• name - 新しいリレーションシップごとに指定する新しい変数名（例：r3、r4）。
• source - 変数名です。cypher 変数（既存のノード） または upsert_nodes エントリーの name（作成したばかりのノード） を指定できます。
• target - 同様に、cypher 変数または upsert_nodes の name を指定できます。
• type - ポリシーの relationship_types と一致する必要があります。

この source／target の柔軟性によって、複合操作が可能になります。r3 は作成したばかりの contract と既存の vehicle をつなぎ、r4 は既存の person と作成したばかりの contract をつなぎます。

実行例で使用する、ノードとリレーションシップを同時に作成するナレッジクエリの完全版については、assets/knowledge-query-create-contract.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-node-with-link/assets/knowledge-query-create-contract.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）が取得できます。

どの配列が相互に作用するか、ノードとリレーションシップの両方を含むレスポンス形式など、スキーマの詳細については、references/knowledge-query-reference.md を参照してください。

4. 認証して実行する

実行エンドポイントは、他のすべての CIQ 操作と同じです。

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

_Application サブジェクトの場合：

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

リクエスト：

{
  "id": "<knowledge_query_gid_or_name>",
  "input_params": {
    "vehicleID": "car2",
    "personID":  "ryan",
    "contract_external_id": "ct853",
    "contractNumber":       "rbjh853"
  }
}

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

実行の詳細については、references/execution-reference.md を参照してください。

5. 応答を検証し、関連付けを確認する

結合作成が成功すると、新しいノードのプロジェクションと、新しいリレーションシップの識別子が返されます。

{
  "data": [
    {
      "nodes": {
        "contract.external_id":     "ct853",
        "contract.property.number": "rbjh853"
      },
      "relationships": {
        "r3": { "Id": …, "ElementId": "…", "StartId": …, "EndId": … },
        "r4": { "Id": …, "ElementId": "…", "StartId": …, "EndId": … }
      }
    }
  ]
}

応答が期待どおりでない場合は、次の項目を確認してください。

1. 両方の許可リストエントリがあること。 KQ の upsert_nodes[].type は allowed_upserts.nodes.node_types に含まれ、各 upsert_relationships[] のトリプルは allowed_upserts.relationships.relationship_types に含まれている必要があります。いずれかが一致しない場合 → 403。
2. エンドポイントが存在すること。 リレーションシップが参照するすべての Cypher 変数（vehicle、person）が実在するノードに解決される必要があります。MATCH が行を見つけられない場合、関連付ける対象がなく、data が空の 200 が返されます。
3. 相互参照が一致していること。 upsert_nodes 内の新しいノードの name（例：contract）は、upsert_relationships[].source または target で使用されている文字列と完全に一致する必要があります。ここに誤字があると、関連付けはエラーなく失敗します。
4. 方向が一致していること。 リレーションシップのトリプルは方向を表します。(Contract)-[:COVERS]->(Vehicle) と (Vehicle)-[:COVERS]->(Contract) は異なります。
5. すべての $param が存在すること。 contract_external_id、contractNumber、vehicleID、personID のすべてが input_params に含まれている必要があります。

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

結果

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

• 結合作成 CIQ ポリシーが存在します。このポリシーには subject.type が 1 つだけあり、subject と既存のエンドポイントノードに一致する Cypher パターン、部分フィルター、そして値が設定された 両方の allowed_upserts.nodes.node_types と allowed_upserts.relationships.relationship_types が含まれます。
• Knowledge Query はポリシーを参照し、新しいノードを upsert_nodes に、新しいリレーションシップを 1 つ以上 upsert_relationships に指定します（新しいノードの name は source または target として参照されます）。
• 1 回の POST /contx-iq/v1/execute で、新しいノードのプロジェクションと、新しいリレーションシップの識別子が返されます。
• 後続の読み取りで、新しいエンティティがグラフに関連付けられていることを確認できます。

このスキル内のファイル

• references/policy-reference.md - 結合された node_types + relationship_types、ハイブリッドな作成・更新フローで任意指定できる existing_nodes。
• references/knowledge-query-reference.md - upsert_nodes と upsert_relationships の連携、source／target の相互参照、labels による ID ノード、複数リレーションシップのパターン。
• references/execution-reference.md - リクエスト／レスポンス、アトミック性の保証、再実行時の冪等性。
• references/troubleshooting.md - 403／空のデータ／関連付けの不一致／相互参照のパターン。
• assets/policy-create-contract.json - developer-hub のリソースにある policyAllowWriteContract を基にした、保険の Contract の標準的な例。
• assets/knowledge-query-create-contract.json - 対応する Knowledge Query。
• scripts/execute.sh - Bash ヘルパー。

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

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

参考資料

• ContX IQ ガイド（開発者ハブ） - upsert_nodes と upsert_relationships の相互参照方法を含む完全なスキーマです。
• 開発者ハブのリソース - policyAllowWriteContract と knowledgeQueryAllowWriteContract - このスキルの基盤となっている、保険契約の標準的な例です。
• 音楽データセットのチュートリアル - 第9章「ナレッジクエリ」 - コンテキストを考慮した取り込みパターンに対応する kqb の書き込みバリエーションです。
• Config API のドキュメント
• Cypher クエリ言語マニュアル（Neo4j、openCypher） - IndyKite Knowledge Graph 上の CIQ ポリシーとナレッジクエリの条件で使用されるグラフクエリ言語です。
• IndyKite Terraform プロバイダー