indykite-ciq-delete

IndyKite ContX IQ - ノード、リレーションシップ、またはプロパティを削除する

ContX IQ ポリシーと Knowledge Query に基づいて、IndyKite Graph（IKG）からノード、リレーションシップ、または個別のプロパティを削除し、POST /contx-iq/v1/execute で実行します。2 つのポリシーフィールド（allowed_deletes.nodes、allowed_deletes.relationships）と 2 つの Knowledge Query 配列（delete_nodes、delete_relationships）で操作を指定します。要素全体を削除するには、ポリシーの cypher にある変数名を渡します。1 つのプロパティだけを削除するには、<var>.<property>（ノードの場合は <var>.property.<name>）を渡します。共通の操作インターフェースで 3 つのモードに対応しています。

モード	ポリシーフィールド	KQ 配列	KQ エントリーの形式
ノード全体を削除する	allowed_deletes.nodes: ["car"]	delete_nodes	"car" - cypher 変数
ノードプロパティを 1 つ削除する	allowed_deletes.nodes: ["car.property.color"]	delete_nodes	"car.property.color" - 変数とプロパティのパス
リレーションシップ全体を削除する	allowed_deletes.relationships: ["r"]	delete_relationships	"r" - cypher 変数
リレーションシッププロパティを 1 つ削除する	allowed_deletes.relationships: ["r.status"]	delete_relationships	"r.status" - 変数とプロパティ名

このスキルでは、4 つのサブケースすべてを扱います。実行可能な例では、最も一般的なケース（呼び出し元自身の Person ノードのプロパティ削除）に焦点を当て、その他のモードについてはリファレンスとポリシーのスニペットで説明します。

作成については、indykite-ciq-create-node / indykite-ciq-create-relationship を参照してください。プロパティの書き込みについては、indykite-ciq-add-property / indykite-ciq-add-relationship-property を参照してください。読み取りについては、indykite-ciq-read を参照してください。

使用するタイミング

ユーザーが次のことを行いたい場合に、このスキルを有効にします。

• CIQ を通じて IKG からノード、リレーションシップ、またはプロパティを削除したい。
• 認証済みユーザー自身のデータに対して、「忘れられる権利」や GDPR に準拠したデータ消去の仕組みを実装している。
• もはや適用されない :PLAYED_AT、:OWNS、その他のリレーションシップを解除したい。
• 誤って設定したプロパティを消去したい（プロパティの書き込みでは値が上書きされますが、プロパティを実際に削除できるのは delete_nodes のみであることを理解したうえで）。
• CIQ の削除呼び出しで 403 / 空の 200 / 削除されない状況をデバッグしている。

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

• ノードまたはリレーションシップを作成したい場合。代わりに indykite-ciq-create-node または indykite-ciq-create-relationship を使用してください。
• プロパティを設定したい場合。代わりに indykite-ciq-add-property または indykite-ciq-add-relationship-property を使用してください。
• データを読み取りたい場合。代わりに indykite-ciq-read を使用してください。
• 保護されたプロパティ（_service、create_time、external_id、id、type、update_time）を削除する必要がある場合。これらはプラットフォームによって管理されており、削除できません。

前提条件

• IndyKite のプロジェクト、AppAgent、および AppAgent の認証情報。
• Config API へのアクセス権を持つサービスアカウントトークンと、PROJECT_GID に設定されたプロジェクトの GID。どちらもポリシーと Knowledge Query の作成に使用します。
• 対象のノード、リレーションシップ、またはプロパティが、すでに IKG に存在していること。
• _Application 以外のサブジェクトについては、そのサブジェクトのノードもすでに IKG に存在していること。

不足しているものがあれば、作業を中止してユーザーに伝えてください。

手順

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 の例（たとえば、古くなった :PLAYED_AT エッジを削除する ETL ジョブ）では、subject.type、フィルター、実行時のヘッダーのみが異なります。

Cypher パターン - 削除する要素を MATCH し、変数にバインドする必要があります。ノードまたはそのプロパティを削除する場合は、ノードをマッチさせます。リレーションシップまたはそのプロパティを削除する場合は、リレーションシップをマッチさせます。プロジェクトの IKG にある正確なノードタイプ、リレーションシップタイプ、またはプロパティ名が不明な場合は、まず Data Schema API で確認してください（indykite-data-schema）。名前に誤りがあると何もマッチせず、パターンに一致するものがない削除は、200 を返すだけで何も行いません。

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

Person が自分の music_mood プロフィールプロパティをクリアします。

MATCH (subject:Person)

変数：subject。KQ はこれを delete_nodes で参照します。

2. allowed_deletes でポリシーを作成する

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

• meta.policy_version - 現在は 1.0-ciq です。
• subject.type - この例では Person です。
• condition.cypher と condition.filter - 要素を特定します。Person の場合は、subject.external_id = $token.sub でフィルターします。
• allowed_deletes - nodes または relationships の少なくとも一方を指定します。各エントリーには、要素全体を削除する場合は変数名のみを、プロパティのみを削除する場合は <var>.<property> または <var>.property.<name> を指定します。

このポリシーで削除のみを行う場合は、allowed_reads と allowed_upserts を省略します。

この例の削除専用ポリシーの全体は、assets/policy-delete-music-mood.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-delete/assets/policy-delete-music-mood.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 に設定されます。

4 種類の allowed_deletes モード、ワイルドカード形式（<var>.*）、および allowed_reads と allowed_upserts を省略する理由については、references/policy-reference.md を参照してください。

3. delete_nodes および／または delete_relationships を指定してナレッジクエリを作成する

ナレッジクエリではポリシーを参照します。削除する対象ごとに、次の項目に列挙します。

• delete_nodes - 変数名または <var>.property.<name> パスの配列です。ポリシーの allowed_deletes.nodes のエントリと一致する必要があります。
• delete_relationships - 変数名または <var>.<property> パスの配列です。ポリシーの allowed_deletes.relationships のエントリと一致する必要があります。

1 つの KQ で、1 回の実行で複数の対象を削除できます（例：複数のプロパティを一度に削除する、またはプロパティとリレーションシップを削除する）。各エントリはポリシーの許可リストによって制限されます。

実行中の例の完全なプロパティ削除用ナレッジクエリは、assets/knowledge-query-delete-music-mood.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-delete/assets/knowledge-query-delete-music-mood.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 つのモードすべてのスキーマの詳細は、references/knowledge-query-reference.md に記載されています。

4. 認証して実行する

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

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

実行中の Person サブジェクトの例における認証：

• X-IK-ClientKey: <AppAgent-credentials-token> - 必須です。
• Authorization: Bearer <user-access-token> - 必須です。トークンの sub クレームが $token.sub の値になります。

_Application サブジェクトの削除では、Bearer ヘッダーを省略します。

リクエスト：

{
  "id": "<knowledge_query_gid_or_name>",
  "input_params": {}
}

（実行中の例では、ID は Bearer トークンから取得されるため、input_params は空です。ほかの削除ポリシーでエンドポイントの固定に $param が必要な場合は、通常どおり指定してください。）

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

実行の完全なリファレンスは references/execution-reference.md です。

5. 応答を確認し、削除を確かめる

削除の実行が成功すると、data 配列は空、またはほぼ空になります。

{
  "data": [
    { "nodes": {} }
  ]
}

200 に到達すれば、削除は実行されています。確認するには：

1. 同じクエリを再実行します。 2 回目の呼び出しも 200 を返すはずです。削除はべき等です（すでに存在しないプロパティを削除してもエラーにはなりません）。
2. 対応する読み取りクエリを実行し、削除したプロパティ／要素を取得します。 プロパティは消えており（null／欠落）、または要素は消えています（data が空）。
3. ノードのプロパティを削除した場合は、ノードの update_time を確認します。 プラットフォームは、書き込みまたは削除のたびに値を更新します。

応答が期待したものと異なる場合は、次のリストを確認してください。

1. 変数が適切な allowed_deletes フィールドにあること。 ノードのプロパティパスは allowed_deletes.nodes（例："car.property.color"）に、リレーションシップのプロパティパスは allowed_deletes.relationships（例："r.status"）に指定します。
2. Cypher が対象の要素に一致していること。 Cypher が行を返さない場合、削除対象がないため、data が空の 200 が返されます。これはエラーではなく、削除が適用されなかっただけです。
3. プロパティ名が保護対象に含まれていないこと。 _service、create_time、external_id、id、type、update_time は削除できません。
4. external_id との混同がないこと。 ノードを削除するとノード全体が削除されます。これは保護フィールドのため、「external_id だけを削除」することはできません。

そのほかの失敗ケースについては、references/troubleshooting.md を参照してください。

結果

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

• 削除専用の CIQ ポリシーが存在します。このポリシーには、単一の subject.type、削除する要素を特定する Cypher パターン、任意の部分フィルター、および allowed_deletes の許可リストがあります。
• ナレッジクエリがそのポリシーを参照し、ポリシーの許可リストに一致する delete_nodes および／または delete_relationships のエントリを列挙しています。
• POST /contx-iq/v1/execute が 200 を返し、対象の要素および／またはプロパティが削除されています。
• 後続の読み取りで削除が確認できます。

このスキルのファイル

• references/policy-reference.md - allowed_deletes の詳細（4 つのモード）、ワイルドカード形式の <var>.*、その他のブロックを省略する理由。
• references/knowledge-query-reference.md - delete_nodes と delete_relationships のスキーマ、保護されたプロパティ名、複数削除のパターン。
• references/execution-reference.md - 削除用の POST /contx-iq/v1/execute、レスポンスの形式、冪等性。
• references/troubleshooting.md - 403／空の data／「削除されなかった」場合のパターン。
• assets/policy-delete-music-mood.json - 実行可能な、Person を対象とする「自身のプロパティを削除する」ポリシー。
• assets/knowledge-query-delete-music-mood.json - 対応する Knowledge Query。
• scripts/execute.sh - Bash ヘルパー。

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

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

参考資料

• ContX IQ ガイド（開発者ハブ） - allowed_deletes と delete_nodes／delete_relationships の完全なスキーマ。
• 音楽データセットのチュートリアル - 第 9 章「Knowledge Queries」 - kqc は、読み取り／書き込み／削除という命名規則における標準的な削除用バリアントです。
• 開発者ハブのリソース - CIQ の例 - policyDeleteProperty と Cars コレクションの削除パターン。
• Config API ドキュメント
• Cypher クエリ言語マニュアル（Neo4j、openCypher） - IndyKite Knowledge Graph に対する CIQ ポリシーおよび Knowledge Query 条件で使用されるグラフクエリ言語。
• IndyKite Terraform プロバイダー