indykite-ciq-delete

IndyKite ContX IQ - 删除节点、关系或属性

删除 IndyKite Graph（IKG）中的节点、关系或单个属性，由 ContX IQ policy + Knowledge Query 驱动，并通过 POST /contx-iq/v1/execute 执行。此操作由两个 policy 字段（allowed_deletes.nodes、allowed_deletes.relationships）和两个 Knowledge Query 数组（delete_nodes、delete_relationships）驱动：传入 policy 的 cypher 中的变量名即可删除整个元素；传入 <var>.<property>（节点也可传入 <var>.property.<name>）则只删除一个属性。三种模式共用同一组操作接口。

模式	Policy 字段	KQ 数组	KQ 条目格式
删除整个节点	allowed_deletes.nodes: ["car"]	delete_nodes	"car" - cypher 变量
删除单个节点属性	allowed_deletes.nodes: ["car.property.color"]	delete_nodes	"car.property.color" - 变量 + 属性路径
删除整个关系	allowed_deletes.relationships: ["r"]	delete_relationships	"r" - cypher 变量
删除单个关系属性	allowed_deletes.relationships: ["r.status"]	delete_relationships	"r.status" - 变量 + 属性名

此技能涵盖所有四种子情况。可运行示例聚焦于最常见的情况（删除调用者自己的 Person 节点上的属性）；其他模式则记录在参考资料和 policy 片段中。

有关创建，请参阅 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 但结果为空 / delete didn't happen 问题。

当用户有以下需求时，不要启用此技能：

• 想要创建节点或关系 - 使用 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 访问权限的 Service Account token，以及 PROJECT_GID 中的项目 GID - 两者用于创建 policy 和 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。

一个策略只能限定为单一主体类型——如果两种类型都应获准，请编写两个策略。下面的可运行示例使用 Person（用户清除自己的个人资料属性）；_Application 版本（例如，ETL 作业清理过时的 :PLAYED_AT 边）仅在 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 编写策略

使用以下四个区块构建策略 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。

关于 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 条目匹配。

单个 KQ 可以在一次执行中删除多个内容（例如，一次删除多个属性，或同时删除一个属性和一个关系）。每个条目都受策略白名单约束。

运行示例的完整属性删除知识查询：参见 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）。

四种模式的架构详情——包括不能删除的受保护属性名称和通配符语法——请参见 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": {}
}

（对于运行示例，身份来自 Bearer 令牌，因此 input_params 为空。其他删除策略可能需要用于端点固定的 $param——照常提供即可。）

可运行的 shell 辅助脚本：scripts/execute.sh。

完整的执行参考：references/execution-reference.md。

5. 验证响应并确认删除

成功执行删除操作后，会返回一个空或几乎为空的 data 数组：

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

如果返回 200，则表示已执行删除。要确认删除：

1. 重新运行相同的查询。 第二次调用也应返回 200——删除操作具有幂等性（删除已不存在的属性不会报错）。
2. 运行配对的读取查询，并投影已删除的属性／元素。属性应已删除（为 null／缺失），或元素应已删除（data 为空）。
3. 检查节点的 update_time（如果删除了节点属性）——平台每次写入或删除时都会更新该值。

如果响应与预期不符，请逐项检查：

1. 变量是否放在正确的 allowed_deletes 字段中。 节点下的属性路径应放在 allowed_deletes.nodes 中（例如 "car.property.color"）；关系下的路径应放在 allowed_deletes.relationships 中（例如 "r.status"）。
2. Cypher 是否匹配到元素。 如果 cypher 没有返回任何行，删除操作就没有目标——会返回 200 和空 data。这不是错误；删除操作只是没有生效。
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（四种模式）、通配符 <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 辅助脚本。

Agent 专属说明

此技能使用通用的 Markdown 说明，可用于 README 中列出的所有 Agent。Agent 需要能够发送 HTTP 请求。无需 Claude Code hooks、Cursor @ 提及或 Copilot 工作区上下文。

参考资料

• ContX IQ 指南（开发者中心） - allowed_deletes 和 delete_nodes / delete_relationships 的完整模式。
• 音乐数据集教程 - 第 9 章“Knowledge Queries” - 按照读/写/删命名惯例，kqc 是标准的删除变体。
• 开发者中心资源 - CIQ 示例 - policyDeleteProperty 和 Cars 集合的删除模式。
• Config API 文档
• Cypher 查询语言手册（Neo4j；openCypher） - CIQ 策略和 Knowledge Query 条件中使用的图查询语言，面向 IndyKite Knowledge Graph。
• IndyKite Terraform provider