indykite-ciq-create-node

IndyKite ContX IQ - 新しいノードを作成する

ContX IQ のポリシーと Knowledge Query を使い、POST /contx-iq/v1/execute で実行して、IndyKite Graph（IKG）に新しいノードを作成します。ポリシーでは、作成可能なノードラベルのホワイトリスト allowed_upserts.nodes.node_types を宣言します。Knowledge Query の upsert_nodes 配列では、ノード名を指定し、external_id を設定して、書き込むプロパティを列挙します。（CIQ の書き込みでは、読み取りと同じポリシー＋Knowledge Query の形式を使います。）

このスキルが扱うのは、新しいノードの作成のみです。その他の書き込み方法は意図的に対象外としています。

• 既存ノードのプロパティを更新する場合は、allowed_upserts.nodes.existing_nodes と、ポリシーの cypher にある変数を参照する upsert_nodes エントリを含む Knowledge Query を使います（external_id はありません）。フィールドも KQ の形式も異なります。
• リレーションシップを作成する場合は、allowed_upserts.relationships.relationship_types（{type, source_node_label, target_node_label} のトリプル）と、Knowledge Query の upsert_relationships 配列を使います。
• 削除には、allowed_deletes と delete_nodes / delete_relationships を使います。

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

使用するタイミング

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

• CIQ を通じて IKG に新しいノードを作成したい（例：新しい Track、Document、Account、その他のエンティティを取り込む）。
• _Application サブジェクトの「カタログ書き込み」ポリシーと Knowledge Query を作成している。これは ETL やシステム側でのデータ取り込みに一般的なパターンです。
• 実行時の input_params から、新しいノードの external_id とプロパティをパラメーター化したい。
• ノードを作成するはずの POST /contx-iq/v1/execute 呼び出しで作成されなかったため、403 / 422 をデバッグしている。

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

• IKG からデータを読み取りたい場合は、indykite-ciq-read を使います。
• 既存ノードのプロパティを更新したい場合は、別のポリシーフィールド（existing_nodes）と KQ 形式を使います。
• ノード間のリレーションシップを作成したい場合は、別のポリシーフィールド（relationship_types）と KQ 配列（upsert_relationships）を使います。
• 何かを削除したい場合は、別のポリシーフィールド（allowed_deletes）と KQ 配列を使います。
• CIQ ではなく Capture API（POST /capture/v1/nodes）または Terraform を使ってデータを取り込みたい場合は、それぞれ別のデータ取り込み方法です。

前提条件

• IndyKite のプロジェクト、AppAgent、および AppAgent の認証情報（AppAgent トークンは実行時に X-IK-ClientKey に渡します）。
• Config API へのアクセス権を持つ Service Account トークンと、PROJECT_GID に設定するプロジェクトの GID。どちらもポリシーと Knowledge Query の作成に使います。
• 新しいノードが使用するノードラベル（Track、Document、Customer など）。これはすでにプロジェクトのデータモデルに含まれている必要があります。
• _Application 以外のサブジェクトの場合は、IKG 内にすでにサブジェクトのノードがあること（CIQ はサブジェクトを作成せず、そのサブジェクトに対して認可します）。
• external_id の計画。これは新しいノードの安定した識別子です。呼び出し元は毎回、次のどちらかを選ぶ必要があります。ポリシー／KQ に直接記述する（まれ）か、実行時に $param として渡す（一般的）。

不足しているものがあれば、そこで作業を止めてユーザーに伝えてください。曖昧な 403 や 422 のデバッグよりも、最初に不足を解消する方がはるかに簡単です。

手順

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 を使用します。たとえば、ユーザーが自分の Playlist を作成する Person 用のバリエーションでは、subject.type、フィルター、実行時のヘッダーだけが異なります。

Cypher アンカー - 書き込み専用のポリシーでも、対象をアンカーする MATCH 句が必要です。新しいノードは cypher ではマッチさせず、Knowledge Query の upsert_nodes で宣言します。

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

システム側のカタログ取り込み：_Application が、新しい Track ノードを作成し、実行時に external_id、title、loudness を指定します。

MATCH (subject:_Application)

これが cypher の全体です。対象を識別するのに必要な最小限の内容だけです。ここに Track は登場しません。

2. allowed_upserts.nodes.node_types でポリシーを作成する

次の4つのブロックを使って、ポリシー JSON を作成します。

• meta.policy_version - 現在は 1.0-ciq です。
• subject.type - 実行例では _Application です。
• condition.cypher と condition.filter - 対象をアンカーします。_Application の場合、subject.external_id = $_appId でフィルターします（実行時に AppAgent から自動入力される予約済みの値です）。
• allowed_upserts.nodes.node_types - Knowledge Query が新しいノードとして作成できるノードラベルの配列です。

このポリシーでノードの作成のみを行う場合は、allowed_reads、allowed_deletes、その他の allowed_upserts のサブフィールドを省略してください。これらを省略することが、該当する操作を禁止するためのサポート対象の方法です。

実行例の完全な作成専用ポリシーについては、assets/policy-create-track.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/assets/policy-create-track.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 に挿入されます。

完全なスキーマ（演算子、属性の規約、existing_nodes と allowed_reads を省略する理由）については、references/policy-reference.md を参照してください。

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

ナレッジクエリはポリシーを参照し、書き込む内容を指定します。upsert_nodes の各エントリには、作成するノードを 1 つ記述します。

• name - ポリシーの cypher で使用されていない一意の変数名です。他の配列（nodes、relationships）が参照する変数です。
• type - ノードラベルです。ポリシーの allowed_upserts.nodes.node_types に含まれている必要があります。
• external_id - 新しいノードでは必須です。1 回限りの書き込みでは値をハードコードするか、呼び出し元が実行時に指定するように $param を使用します（一般的なケース）。
• is_identity - 任意のブール値です。true にすると、ノードがアイデンティティノードとして作成されます。下記の注を参照してください。
• labels - type とともに付与する追加ラベルの任意の配列です。
• properties - {type, value, metadata?} 項目の配列です。type（プロパティ名）はハードコードする必要があります。value はハードコードするか、$param を使用できます。

トップレベルの nodes 配列に変数名を指定して、新しいノードをレスポンスに含めます。

アイデンティティノード。 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 の評価を実行します。

実行例のナレッジクエリ全体は、assets/knowledge-query-create-track.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/assets/knowledge-query-create-track.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 ツールが参照する値です。

設定できない保護対象のプロパティ名を含む、すべてのナレッジクエリフィールドのスキーマ詳細については、references/knowledge-query-reference.md を参照してください。

4. 認証して実行する

execute エンドポイントは読み取り時と同じです。

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

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

• X-IK-ClientKey: <AppAgent-credentials-token> - 必須です。
• Authorization: Bearer … - _Application サブジェクトでは省略します。AppAgent 自体がサブジェクトを認証し、アプリケーションの external_id から $_appId が自動入力されます。

Person サブジェクトの作成フローでは、Authorization: Bearer <user-access-token> を追加します。ポリシーの subject.external_id = $token.sub フィルターによって、cypher アンカーがそのユーザーに固定されます。

リクエストボディ：

{
  "id": "<knowledge_query_gid_or_name>",
  "input_params": {
    "track_external_id": "track-99",
    "track_title": "New Hot Track",
    "track_loudness": -7.5
  }
}

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

execute の詳細なリファレンス（認証の組み合わせ、レスポンス形式、エラーコード）については、references/execution-reference.md を参照してください。

5. 応答を検証し、新しいノードを確認する

作成処理が成功すると、新しいノードのプロジェクションが返されます。

{
  "data": [
    {
      "nodes": {
        "newTrack.external_id": "track-99",
        "newTrack.property.title": "New Hot Track",
        "newTrack.property.loudness": -7.5
      }
    }
  ]
}

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

1. ラベルがホワイトリストに登録されています。 Knowledge Query の upsert_nodes[].type は、ポリシーの allowed_upserts.nodes.node_types に含まれている必要があります。不一致の場合 → 403。
2. external_id が設定されています。 新しいノードの作成には必須です（"$track_external_id" のように）パラメーター化する場合、呼び出し元が input_params で値を指定する必要があります。値がない場合 → 422 invalid_argument: missing or wrong input params。
3. name が Cypher 変数と競合していません。 upsert_nodes[].name の変数名は新しい名前にしてください。ポリシーの cypher にすでに登場する名前は使わないでください。競合すると、ポリシーは新規作成ではなく既存の一致対象を更新しようとします。
4. プロパティ名が保護対象のセットに含まれていません。 _service、create_time、external_id、id、type、update_time はプロパティとして設定できません。これらはプラットフォームによって管理されます。
5. ノードがすでに存在していません。 同じ external_id で再実行すると、新規作成ではなくアップサート（更新）が行われます。応答は似たものになりますが、新しいノードは追加されません。

その他の失敗例（認証形式の誤り、不正な JSON、サブジェクトフィルターの不一致）については、references/troubleshooting.md を参照してください。

結果

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

• 作成専用の CIQ ポリシーがプロジェクトに存在します。このポリシーには単一の subject.type、サブジェクトをアンカーする Cypher パターン、任意の部分フィルター、および allowed_upserts.nodes.node_types のホワイトリストがあり、allowed_reads、allowed_deletes、existing_nodes は含まれません。
• Knowledge Query がそのポリシーを参照し、upsert_nodes に、新しいノードを 1 つだけ記述します。ノードには一意の name、適切な type、external_id、設定するプロパティが含まれます。
• POST /contx-iq/v1/execute（または MCP の ciq_execute ツール）は、成功時に新しいノードのプロジェクションを返します。
• 後続の読み取りクエリ（たとえば indykite-ciq-read を使用）で、IKG 内に新しいノードが見つかります。

このスキルのファイル

• references/policy-reference.md - 書き込みに特化したポリシースキーマ、allowed_upserts.nodes の詳細（existing と node_types の違い）、その他のブロックを省略する理由。
• references/knowledge-query-reference.md - upsert_nodes スキーマ、プロパティとメタデータ、labels による ID ノード、保護対象のプロパティ名、新しいノードの返却。
• references/execution-reference.md - 書き込み用の POST /contx-iq/v1/execute、_Application 予約済み $_appId を含む認証の組み合わせ、応答形式。
• references/troubleshooting.md - 403／422／external_id の重複／プロパティ不足のパターン。
• assets/policy-create-track.json - _Application → 新しい Track の例で実行可能な作成専用ポリシー。
• assets/knowledge-query-create-track.json - 対応する Knowledge Query。
• scripts/execute.sh - 適切なヘッダーを付けて /contx-iq/v1/execute に POST する Bash ヘルパー。

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

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

参考資料

• ContX IQ ガイド（開発者ハブ）
• 音楽データセットのチュートリアル - 第 8 章「ContX IQ ポリシー」と第 9 章「ナレッジクエリ」 - 実際のグラフに対する読み取り／書き込み／削除の具体的なバリエーションです。
• Config API のドキュメント
• Cypher クエリ言語マニュアル（Neo4j、openCypher） - IndyKite ナレッジグラフ上の CIQ ポリシーとナレッジクエリの条件で使用されるグラフクエリ言語です。
• IndyKite Terraform プロバイダー - indykite_authorization_policy と indykite_knowledge_query
• 認証情報ガイド