indykite-ciq-add-relationship-property

IndyKite ContX IQ - 为现有关系添加属性

通过 ContX IQ 策略和 Knowledge Query 设置或覆盖 IndyKite Graph（IKG）中现有关系的一个或多个属性，并通过 POST /contx-iq/v1/execute 运行。策略会通过 allowed_upserts.relationships.existing_relationships 将允许修改的关系限定为由 cypher 匹配到的关系；Knowledge Query 的 upsert_relationships 会引用这些变量（由于关系已存在，因此不包含 source/target/type），并列出要设置的属性。添加全新属性和覆盖现有属性是同一操作——平台不会区分两者。

此技能是 indykite-ciq-add-property 的关系对应版本，后者用于设置现有节点的属性。结构是对称的，字段名称不同。

其他操作路径不在本技能范围内：

• 创建全新关系使用 allowed_upserts.relationships.relationship_types，并在 Knowledge Query 的 upsert_relationships 条目中使用新的 name 和 source/target/type——参见 indykite-ciq-create-relationship。
• 设置节点属性使用 allowed_upserts.nodes.existing_nodes——参见 indykite-ciq-add-property。
• 删除关系属性使用 allowed_deletes.relationships，并提供 <var>.<property> 路径——参见 indykite-ciq-delete。

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

适用场景

当用户遇到以下情况时，启用此技能：

• 想要在 IKG 中现有关系上设置属性（例如，在现有 :PLAYED_AT 上添加 verified: true，在现有 :LIKES 上设置 weight，或在现有 :OWNS 边上设置 confidence）；
• 事后以普通属性的形式为现有关系添加来源、信任评分或审计字段；
• 正在排查本应成功的关系属性写入执行请求返回的 403 / 422 错误。

当用户遇到以下情况时，不要启用此技能：

• 想要在两个现有节点之间创建新关系——使用 indykite-ciq-create-relationship；
• 想要设置节点属性——使用 indykite-ciq-add-property；
• 想要附加属性元数据（source、assurance_level 等）——关系属性不支持元数据；请使用 indykite-ciq-add-property 将其添加到节点属性；
• 想要删除属性——使用 indykite-ciq-delete；
• 想要读取数据——使用 indykite-ciq-read；
• 正在使用 Capture API 摄取数据——这是不同的数据摄取路径。

前提条件

• IndyKite 项目、AppAgent 和 AppAgent 凭据（执行时将 AppAgent 令牌传入 X-IK-ClientKey）。
• 拥有 Config API 访问权限的 Service Account token，以及 PROJECT_GID 中的项目 GID——两者用于创建策略和 Knowledge Query。
• IKG 中已存在目标关系及其两个端点节点。
• 明确列出策略/KQ 将写入的属性名称。属性名称必须在 KQ 中硬编码；只有值可以使用 $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。

策略仅限于单一主体类型；若两种类型都应获准，请编写两条策略。下面的可运行示例使用 _Application（对现有边进行系统侧标注）；Person 变体（例如，用户将自己的 :LIKES 边标记为 priority）仅在 subject.type、筛选条件和执行请求头方面有所不同。

Cypher 模式 - 必须 MATCH 现有关系并将其绑定到变量。existing_relationships 和 upsert_relationships[].name 引用的就是这个变量名。在筛选条件中通过 external_id 固定两个端点，以唯一标识该关系。如果不清楚项目 IKG 中确切的节点类型、关系类型或属性拼写，请先从 Data Schema API 读取（indykite-data-schema）——拼写错误的名称不会报错，只会匹配不到任何内容；模式匹配不到任何内容的写入操作是空操作，但仍会返回 200。

示例（本技能中均使用此示例）：

_Application 为现有的 (:Track)-[:PLAYED_AT]->(:Venue) 关系添加标注，设置 verified 标志和 first_played_at 时间戳。

MATCH (subject:_Application)
MATCH (track:Track)-[r:PLAYED_AT]->(venue:Venue)

变量：subject、track、r、venue。要更新的关系变量是 r。

2. 使用 allowed_upserts.relationships.existing_relationships 编写策略

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

• meta.policy_version - 当前为 1.0-ciq。
• subject.type - 在运行示例中为 _Application。
• condition.cypher 和 condition.filter - cypher 匹配现有关系；筛选条件固定 subject.external_id = $_appId（保留值），并通过 external_id 固定源端点和目标端点。
• allowed_upserts.relationships.existing_relationships - cypher 中允许 Knowledge Query 写入其属性的关系变量数组。Knowledge Query 的 upsert_relationships[].name 必须包含在此列表中。

如果此策略仅写入关系属性，请省略 allowed_reads、allowed_deletes 以及其他 allowed_upserts 子字段。

运行示例的完整只写策略：参见 assets/policy-annotate-played-at.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-relationship-property/assets/policy-annotate-played-at.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。

完整架构（为何省略 relationship_types、Person 变体、受保护的属性名称）请参见 references/policy-reference.md。

3. 使用 upsert_relationships 创建 Knowledge Query

Knowledge Query 引用该策略。upsert_relationships 中的每个条目都描述一次关系更新：

• name - 必须与策略 cypher 中的关系变量匹配（例如 r）。这是它在结构上与创建关系技能的不同之处；在此处使用新名称意味着创建关系。
• source / target / type - 更新现有关系时应省略。端点和标签来自匹配到的边；指定它们并无必要，还可能使平台产生困惑。
• properties - {type, value} 项组成的数组。与节点属性不同，关系属性不接受 metadata：保存 Knowledge Query 时，metadata 键会因属于未知字段而被拒绝。

在响应中回显结果，在顶层的 relationships 和／或 nodes 数组中列出要投影的属性。

运行示例的完整 Knowledge Query：参见 assets/knowledge-query-annotate-played-at.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-relationship-property/assets/knowledge-query-annotate-played-at.json \
  | curl -X POST "$API_URL/configs/v1/knowledge-queries" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $SERVICE_ACCOUNT_TOKEN" \
      -d @-

成功时返回 201 Created，其中包含 Knowledge Query 的 id（GID）。

架构详情——包括不可设置的受保护属性名称（_service、create_time、id、type、update_time），以及关系属性不带元数据的原因——参见 references/knowledge-query-reference.md。

4. 进行身份验证并执行

执行端点与读取、节点属性写入和创建技能使用的端点相同：

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

运行示例（主体为 _Application）的身份验证：

• X-IK-ClientKey: <AppAgent-credentials-token> - 必填。
• Authorization: Bearer … - _Application 使用时应省略。

对于主体为 Person 的关系属性写入，请添加 Authorization: Bearer <user-access-token>。

请求：

{
  "id": "<knowledge_query_gid_or_name>",
  "input_params": {
    "track_external_id": "track-99",
    "venue_external_id": "venue-1",
    "first_played_at":   "2026-04-22T19:00:00Z"
  }
}

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

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

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

关系属性写入成功时，会返回你请求的投影：

{
  "data": [
    {
      "relationships": {
        "r": {
          "Id": 1152932499723124700,
          "ElementId": "5:3a2b09d5-…:1152932499723124736",
          "Props": {
            "verified":         true,
            "first_played_at":  "2026-04-22T19:00:00Z"
          }
        }
      }
    }
  ]
}

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

1. existing_relationships 中的变量。 KQ 的 upsert_relationships[].name 必须在策略的 existing_relationships 列表中。不匹配 → 403。
2. Cypher 匹配到了关系。 如果 cypher 未返回任何行（例如，源或目标的 external_id 尚未植入，或者 :PLAYED_AT 边不存在），upsert 就没有可附加的目标 → 200，但 data 为空。
3. name 与 cypher 变量匹配。 使用新名称意味着创建关系；除非同时声明了 relationship_types，否则请求会被拒绝。
4. upsert_relationships 条目中没有 source / target / type。 包含其中任一项都会将操作切换为“创建”语义。
5. 属性名称未受保护。 _service、create_time、id、type、update_time 不能设置为关系属性。

其他失败情况参见 references/troubleshooting.md。

结果

成功应用此技能后：

• 存在关系属性写入 CIQ 策略；该策略只有一个 subject.type，包含匹配待更新关系的 Cypher 模式、通过 external_id 固定端点的部分筛选条件，以及 allowed_upserts.relationships.existing_relationships 白名单。
• Knowledge Query 引用该策略，并列出 upsert_relationships 条目；这些条目复用 cypher 变量名称、省略 source / target / type，并声明要设置的属性。
• POST /contx-iq/v1/execute 返回投影的属性值，确认写入成功。
• 后续读取（例如通过 indykite-ciq-read）可在该关系上找到新属性值。

此技能中的文件

• references/policy-reference.md - 策略架构、existing_relationships 深入说明，以及省略其他区块的原因。
• references/knowledge-query-reference.md - 用于更新的 upsert_relationships（变量来自 cypher，不含 source/target/type）、属性（无 metadata）和受保护名称。
• references/execution-reference.md - 用于写入关系属性的 POST /contx-iq/v1/execute，以及包含关系 Props 区块的响应结构。
• references/troubleshooting.md - 症状 → 修复对照表。
• assets/policy-annotate-played-at.json - 可运行的 _Application 注释 :PLAYED_AT 策略。
• assets/knowledge-query-annotate-played-at.json - 对应的 Knowledge Query。
• scripts/execute.sh - Bash 辅助脚本。

Agent 专属说明

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

参考资料

• ContX IQ 指南（开发者中心） - 完整架构，包括 allowed_upserts.relationships.existing_relationships。
• 音乐数据集教程 - 第 8 章“ContX IQ 策略”和第 9 章“Knowledge Queries” - 读／写／删变体的命名约定。
• 开发者中心资源 - CIQ 示例 - policyMetaData / knowledgeQueryMetaData 组合展示了类似的节点属性写入；此技能将同一模式应用于关系变量。
• Config API 文档
• Cypher 查询语言手册（Neo4j；openCypher） - CIQ 策略和 Knowledge Query 条件中使用的图查询语言，可查询 IndyKite Knowledge Graph。
• IndyKite Terraform provider