indykite-ciq-add-property

IndyKite ContX IQ - 为现有节点添加属性

通过 ContX IQ 策略和知识查询，为 IndyKite Graph（IKG）中已存在的节点设置或覆盖一个或多个属性，并通过 POST /contx-iq/v1/execute 执行。策略通过 allowed_upserts.nodes.existing_nodes 白名单限制可由 cypher 匹配并允许修改的节点；知识查询的 upsert_nodes 引用这些变量（节点已存在，因此不需要 external_id），并列出要设置的属性，也可以包含元数据。IKG 将此视为一次 upsert：添加全新属性和覆盖现有属性是同一种操作；平台不会加以区分。

本技能仅涵盖这一场景：为现有节点写入属性。其他场景有意不在本技能范围内：

• 创建全新节点需使用 allowed_upserts.nodes.node_types，并在知识查询的 upsert_nodes 条目中使用全新的 name 和 external_id；请参阅 indykite-ciq-create-node。
• 创建新关系需使用 allowed_upserts.relationships.relationship_types；请参阅 indykite-ciq-create-relationship。
• 更新关系属性需使用 allowed_upserts.relationships.existing_relationships。
• 删除属性需使用 allowed_deletes.nodes 和 <var>.property.<name> 路径。

如需读取数据，请参阅 indykite-ciq-read。

适用场景

用户出现以下需求时，启用本技能：

• 想要为 IKG 中已存在的节点设置属性（例如，更新某个 Person 的 music_mood、设置某个 LicenseNumber 的 status，或为已验证的属性附加 assurance_level 元数据）；
• 正在编写以 Person 为主体的“更新自己的数据”策略（典型模式：MATCH (subject:Person) + subject.external_id = $token.sub + existing_nodes: ["subject"]）；
• 正在编写以 _Application 为主体的“系统侧属性写入”策略，用于更新可从 AppAgent 访问的节点；
• 需要写入属性元数据（source、assurance_level、自定义元数据字段）；
• 正在排查本应成功的属性写入执行为何返回 403 / 422。

用户出现以下需求时，不要启用本技能：

• 想要创建全新节点——使用 indykite-ciq-create-node；
• 想要用新关系连接两个现有节点——使用 indykite-ciq-create-relationship；
• 想要更新关系属性——这需要使用不同的策略字段（existing_relationships），不在本技能范围内；
• 想要删除属性或节点——这需要使用不同的策略字段（allowed_deletes）；
• 想要读取数据——使用 indykite-ciq-read；
• 正在使用 Capture API 导入数据——这属于不同的数据导入途径。

前提条件

• IndyKite 项目、AppAgent 和 AppAgent 凭据（执行时，AppAgent 令牌需放入 X-IK-ClientKey）。
• 拥有 Config API 访问权限的 Service Account 令牌，以及存放在 PROJECT_GID 中的项目 GID——两者都用于创建策略和知识查询。
• 目标节点已存在于 IKG 中——CIQ 不会创建该节点；此策略会授权修改其属性。
• 明确列出策略/知识查询要写入的属性名称。属性名称必须在知识查询中硬编码；只有值和元数据可以使用 $param。
• 对于非 _Application 主体，主体节点也必须已存在于 IKG 中。

如果缺少任何一项，请停止并告知用户——先补齐这些条件，远比排查含糊的 403 或空结果要省事。

步骤

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 变体（例如，回填 imported_at 时间戳的 ETL 作业）仅在 subject.type、过滤条件和执行请求头方面有所不同。

Cypher 模式——用于解析要更新的节点的 MATCH 子句。在此处使用的变量名将由 existing_nodes 和 upsert_nodes[].name 引用。最简单的情况是 MATCH (subject:Person)（主体节点本身）；更一般的情况是沿路径查找相关节点，例如 MATCH (subject:Person)-[:OWNS]->(car:Car)-[:HAS]->(ln:LicenseNumber)。如果不确定项目 IKG 中的确切节点类型、关系类型或属性拼写，请先通过 Data Schema API 查看（indykite-data-schema）——拼写错误的名称会静默地匹配不到任何内容，而模式匹配不到任何内容的写入操作会成为空操作，但仍返回 200。

工作示例（贯穿此技能使用，参考音乐数据集第 8 章的 ciqpolicy4 建模）：

Person 更新自己的个人资料属性（例如 music_mood、dance_skill）。

MATCH (subject:Person)

变量：subject。KQ 将在 upsert_nodes 中引用此名称。

2. 使用 allowed_upserts.nodes.existing_nodes 编写策略

使用以下四个区块构建策略 JSON：

• meta.policy_version——当前为 1.0-ciq。
• subject.type——运行示例使用 Person。
• condition.cypher 和 condition.filter——锚定要更新的节点。对于 Person，过滤条件为 subject.external_id = $token.sub。
• allowed_upserts.nodes.existing_nodes——包含来自 cypher 的变量的数组，这些变量的属性可由 Knowledge Query 写入。Knowledge Query 的 upsert_nodes[].name 必须在此列表中。

如果此策略只写入属性，请省略 allowed_reads、allowed_deletes 和其他 allowed_upserts 子字段。实际中常将 allowed_reads 组合使用（读取并更新自己的个人资料模式），但为清晰起见，此处不作讨论。

运行示例的完整只写策略：参见 assets/policy-update-own-profile.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-add-property/assets/policy-update-own-profile.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。

完整架构（为何省略 node_types、_Application 变体，以及来自 policyMetaData 的元数据变体）请参见 references/policy-reference.md。

3. 使用 upsert_nodes 创建知识查询

知识查询会引用策略。upsert_nodes 中的每个条目都描述一次节点更新：

• name - 必须与策略 cypher 中的变量匹配（例如 subject、car、ln）。这与创建节点技能在结构上的区别就在于此；如果在这里使用新名称，则表示要创建节点。
• type - 更新现有节点时省略。（创建节点时，此项用于指定新节点的标签；更新节点时，标签由匹配到的现有节点决定。）
• external_id - 省略。仅创建节点时必填。
• properties - 由 {type, value, metadata?} 项组成的数组。type（属性名称）是硬编码的；value 可以是硬编码值，也可以是 $param；metadata 为可选项，并遵循相同规则。

在顶层 nodes 数组中列出要投影的属性，并在响应中回显结果，例如 subject.property.music_mood。这可以确认写入的值。

运行示例的完整知识查询见 assets/knowledge-query-update-own-profile.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-add-property/assets/knowledge-query-update-own-profile.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）。

Schema 详细信息——包括不能设置的受保护属性名称（_service、create_time、external_id、id、type、update_time）、metadata 子数组，以及使用 $token.iss 替换的完整 knowledgeQueryMetaData 示例——请参阅 references/knowledge-query-reference.md。

4. 身份验证并执行

执行端点与读取、创建节点和创建关系时使用的端点相同：

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

运行中的 Person 主体示例的身份验证方式：

• X-IK-ClientKey: <AppAgent-credentials-token> - 必填。
• Authorization: Bearer <user-access-token> - 必填。令牌的 sub 声明会为策略筛选器提供 $token.sub，将 cypher 锚点限定为该用户。

对于 _Application 主体的属性写入，请省略 Bearer 标头；保留值 $_appId 会从 AppAgent 自动填充。

请求：

{
  "id": "<knowledge_query_gid_or_name>",
  "input_params": {
    "new_music_mood":  "Acoustic Sadness",
    "new_dance_skill": 0.67
  }
}

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

完整的执行参考（身份验证组合、响应格式、错误语义）：references/execution-reference.md。

5. 验证响应并确认属性写入

属性写入执行成功后，会回显你在 KQ 的 nodes 数组中列出的投影：

{
  "data": [
    {
      "nodes": {
        "subject.property.music_mood":  "Acoustic Sadness",
        "subject.property.dance_skill": 0.67
      }
    }
  ]
}

如果响应不符合预期，请先按以下列表逐项检查，再更改策略或 KQ：

1. existing_nodes 中的变量。 KQ 的 upsert_nodes[].name 必须包含在策略的 allowed_upserts.nodes.existing_nodes 中。不匹配 → 403。
2. Cypher 匹配到了节点。 如果 cypher 未返回任何行（例如，用户的 external_id 未作为 Person 预置），upsert 就没有可关联的节点 → 返回 200，且 data 为空。
3. name 与 cypher 变量匹配。 使用新名称（cypher 中不存在的名称）会让平台将该条目视为创建操作；由于通常没有相应的 node_types 白名单，因此会被拒绝。
4. upsert_nodes 条目中没有 external_id。 包含 external_id 会将操作切换为“创建”语义。要写入现有匹配节点的属性，请省略此项。
5. 属性名称未受保护。 _service、create_time、external_id、id、type、update_time 不能设置为属性；它们由平台管理。
6. 属性值类型与 IKG Schema 匹配。 对数值属性传入 "-7.5"（字符串）会被拒绝。

其他失败情况（身份验证格式错误、缺少 input_params、metadata 异常）请参阅 references/troubleshooting.md。

结果

成功应用此技能后：

• 存在一项属性写入 CIQ 策略；它只有一个 subject.type、一个用于解析待更新节点的 Cypher 模式、可选的部分筛选条件，以及一个 allowed_upserts.nodes.existing_nodes 白名单——不包含 node_types、allowed_reads 或 allowed_deletes。
• 知识查询引用该策略，并列出复用 Cypher 变量名的 upsert_nodes 条目、省略 external_id，并声明要设置的属性（以及可选的元数据）。
• POST /contx-iq/v1/execute 返回投影后的属性值，确认写入成功。
• 后续读取查询（例如通过 indykite-ciq-read）能在该节点上找到新的属性值。

此技能中的文件

• references/policy-reference.md - 面向写入的策略架构、existing_nodes 详解、Person 和 _Application 模式，以及省略其他区块的原因。
• references/knowledge-query-reference.md - 用于更新的 upsert_nodes（变量来自 Cypher，不含 external_id）、属性与元数据、knowledgeQueryMetaData 丰富示例，以及受保护的属性名称。
• references/execution-reference.md - 用于属性写入的 POST /contx-iq/v1/execute、身份验证组合、包含丰富 Props 区块的响应结构。
• references/troubleshooting.md - 403、data 为空、类型不匹配和元数据相关模式。
• assets/policy-update-own-profile.json - 可运行的 Person 主体“更新个人资料”策略，参照 music-dataset 第 8 章的 ciqpolicy4 编写。
• assets/knowledge-query-update-own-profile.json - 配套的知识查询（设置 music_mood 和 dance_skill）。
• scripts/execute.sh - Bash 辅助脚本，使用正确的标头向 /contx-iq/v1/execute 发送请求。

Agent 专属说明

此技能使用通用的 Markdown 指令，适用于 README 中列出的所有 Agent。Agent 需要能够发送 HTTP 请求（使用 curl、HTTP 客户端或 IndyKite Terraform provider）。无需 Claude Code hooks、Cursor @ 提及或 Copilot 工作区上下文。

参考资料

• ContX IQ 指南（开发者中心） - 完整架构，包括 allowed_upserts.nodes.existing_nodes 以及 properties / metadata 数组。
• Music dataset 教程 - 第 8 章“ContX IQ 策略” - ciqpolicy4 是 Person 主体“更新自己的数据”的标准模式；kq4b 是其写入变体。
• Music dataset 教程 - 第 9 章“知识查询” - 读取 / 写入 / 删除变体的命名约定（kq / kqb / kqc）。
• 开发者中心资源 - CIQ 示例 - policyMetaData + knowledgeQueryMetaData 展示了更丰富的属性写入模式，其中使用了 $token.iss 替换和逐属性元数据。
• Config API 文档
• Cypher 查询语言手册（Neo4j；openCypher） - CIQ 策略和知识查询中用于 IndyKite Knowledge Graph 条件的图查询语言。
• IndyKite Terraform provider
• 凭据指南