indykite-ciq-create-relationship

IndyKite ContX IQ - 创建新关系

通过 ContX IQ 策略和知识查询，在 IndyKite Graph (IKG) 中的两个现有节点之间创建全新关系，并通过 POST /contx-iq/v1/execute 执行。策略会声明 allowed_upserts.relationships.relationship_types 白名单，其中包含 {type, source_node_label, target_node_label} 三元组，并在其 cypher 中匹配两个端点节点；知识查询的 upsert_relationships 数组会指定新关系，并将这两个 cypher 变量分别作为 source 和 target 引用。端点节点必须已存在——此操作只会创建关系。

本技能仅涵盖此场景——在两个预先存在的节点之间创建关系。其他路径明确不在范围内：

• 创建新节点使用 allowed_upserts.nodes.node_types 和 upsert_nodes——请参阅 indykite-ciq-create-node。
• 创建指向新节点的关系需要同时使用两者：为新节点添加 upsert_nodes 条目，再添加 upsert_relationships 条目，将其 source 或 target 指向新节点的 name。架构支持此操作；为清晰起见，本技能的示例仅涉及两个现有端点。请参阅文末的“为新端点进行调整”。
• 更新现有关系的属性使用 allowed_upserts.relationships.existing_relationships。
• 删除使用 allowed_deletes.relationships。

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

适用场景

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

• 想要用新关系连接两个现有节点（例如 Person -[:ACCEPTED]-> Contract、Track -[:PLAYED_AT]-> Venue、User -[:OWNS]-> Document）；
• 正在编写以 _Application 为主体的“目录连线”策略和知识查询，用于系统侧关系导入；
• 想要通过执行时的 input_params 参数化源节点／目标节点的 external_id，以及（可选的）新关系属性；
• 正在排查 POST /contx-iq/v1/execute 调用返回 403／422 的问题；该调用本应创建关系，但实际没有创建。

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

• 想要创建新节点（无论是否从其他节点创建关系）——请使用 indykite-ciq-create-node；
• 想要从 IKG 读取数据——请使用 indykite-ciq-read；
• 想要更新现有关系的属性——这需要使用不同的策略字段（existing_relationships）和 KQ 结构；
• 想要删除关系——这需要使用不同的策略字段（allowed_deletes.relationships）和 KQ 数组；
• 正在使用 Capture API（POST /capture/v1/relationships）或 Terraform 导入关系，而非使用 CIQ——这些属于独立的导入路径。

前提条件

• IndyKite 项目、AppAgent 及 AppAgent 凭据（执行时将 AppAgent 令牌传入 X-IK-ClientKey）。
• 具有 Config API 访问权限的 Service Account 令牌，以及 PROJECT_GID 中的项目 GID——两者都用于创建策略和知识查询。
• IKG 中两个端点节点都已存在，且具有稳定的 external_id。CIQ 不会创建这些节点；此策略用于授权连线两个现有节点。
• 关系标签（PLAYED_AT、ACCEPTED、OWNS 等）以及该关系连接的源节点和目标节点标签。两者都必须符合 IKG 架构已有的许可设置。
• 如果主体不是 _Application，则主体对应的节点也必须已存在于 IKG 中。

如果缺少任何一项，请停止并告知用户——先解决这些问题，远比排查含糊的 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。

策略仅限于一种主体类型——如果两种类型都应获准，请编写两个策略。下面的可运行示例使用 _Application（系统端配置）；Person 变体（例如用户接受 Contract）仅在 subject.type、筛选条件和执行请求头方面有所不同。

Cypher 模式——必须 MATCH 两个端点节点，以及主体。如果端点之间没有需要用到的其他路径，请使用彼此独立的 MATCH 子句（以空格分隔）。如果不确定项目 IKG 中的确切节点类型、关系类型或属性拼写，请先从 Data Schema API 中读取（indykite-data-schema）——名称拼写错误会静默地匹配不到任何内容，而模式匹配不到任何内容的写入操作虽然不起作用，仍会返回 200。

贯穿本技能的工作示例：

音乐数据集领域：_Application 根据现有 Track 和现有 Venue 的 external_id，在两者之间添加 PLAYED_AT 关系。

MATCH (subject:_Application)
MATCH (track:Track)
MATCH (venue:Venue)

策略和 KQ 的其余部分将引用以下变量：subject、track、venue。新关系不会出现在 cypher 中——它是在 KQ 中声明的。

如果需要在添加新边之前约束端点必须通过现有路径可达，请改用相连模式——例如，可以要求 Track 和 Venue 共享现有的 :CATALOGED_BY 关系，才允许添加 PLAYED_AT 链接。此约束应在 cypher 中定义。

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

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

• meta.policy_version——当前为 1.0-ciq。
• subject.type——此示例使用 _Application。
• condition.cypher 和 condition.filter——锚定主体，并通过 external_id 固定端点。对于 _Application，筛选条件为 subject.external_id = $_appId（保留字段，自动填充）。对于每个端点，使用 $param 筛选其 external_id。
• allowed_upserts.relationships.relationship_types——包含 {type, source_node_label, target_node_label} 三元组的数组，供 Knowledge Query 创建新关系。

如果此策略只创建关系，请省略 allowed_reads、allowed_deletes 和 allowed_upserts 中的其他子字段。省略区块是禁止相应操作的受支持方式。

此示例的完整关系创建策略见 assets/policy-create-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-create-relationship/assets/policy-create-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 create 会将其注入 policy_id。

完整架构（relationship_types 三元组，以及省略 existing_relationships 和 node_types 的原因）请参阅 references/policy-reference.md。

3. 使用 upsert_relationships 创建知识查询

知识查询会引用策略并列出要写入的内容。upsert_relationships 中的每个条目都描述一个新的关系：

• name - 一个未在策略的 cypher 中使用过的唯一变量名。按照惯例，使用 new 作为前缀，或使用特定领域的名词。响应会使用此名称作为新关系标识符的键。
• source - 策略 cypher 中源端点的变量名。必须与 relationship_types[].source_node_label 声明的内容匹配。
• target - 策略 cypher 中目标端点的变量名。必须与 target_node_label 匹配。
• type - 关系标签。必须与策略中的 relationship_types[].type 相等。
• properties - 可选。由 {type, value} 项组成的数组；与节点属性不同，关系属性不接受 metadata（保存知识查询时，metadata 键会因属于未知字段而被拒绝）——参见 references/knowledge-query-reference.md。

在响应中回显新关系：将其变量名列在顶层的 relationships 数组中。

运行示例的完整知识查询：参见 assets/knowledge-query-create-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-create-relationship/assets/knowledge-query-create-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 时，会给出知识查询的 id（GID）。

4. 进行身份验证并执行

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

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

运行示例采用 _Application 作为主体时的身份验证：

• X-IK-ClientKey: <AppAgent-credentials-token> - 必填。
• Authorization: Bearer … - 对于 _Application，请省略。保留的 $_appId 会从应用程序的 external_id 自动填充。

对于 Person 主体关联流程，添加 Authorization: Bearer <user-access-token>，并使用策略中针对 subject.external_id = $token.sub 的筛选条件。

请求：

{
  "id": "<knowledge_query_gid_or_name>",
  "input_params": {
    "track_external_id": "track-99",
    "venue_external_id": "venue-1"
  }
}

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

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

5. 验证响应并确认新关系

成功执行创建关系操作后，会返回投影节点，以及一个以变量名为键、包含内部图标识符的 relationships 块：

{
  "data": [
    {
      "nodes": {
        "track.external_id": "track-99",
        "venue.external_id": "venue-1"
      },
      "relationships": {
        "newPlayedAt": {
          "Id": 1152932499723124700,
          "ElementId": "5:3a2b09d5-…:1152932499723124736",
          "StartId": 0,
          "StartElementId": "4:3a2b09d5-…:0",
          "EndId": 15
        }
      }
    }
  ]
}

Id / ElementId 是平台为新边分配的内部标识符；你不需要使用它们，但它们可以确认该边已写入。

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

1. 两个端点都存在。 策略的 cypher 必须实际匹配到内容——如果未预置 track.external_id 或 venue.external_id，cypher 将不会返回任何行，upsert_relationships 也就没有可关联的对象。
2. 三元组匹配。 KQ 的 (source, target, type) 必须与策略的 relationship_types[] 三元组一致——标签（通过 cypher 变量）和 type 都必须相同。
3. 变量存在于 cypher 中。 source 和 target 是 cypher 变量名，不是标签。如果你写的是 "source": "Track"（标签），而不是 "source": "track"（变量），请求就会失败。
4. name 未被占用。 新关系的 name 不得与策略 cypher 中的现有变量冲突。
5. 该关系尚不存在。 使用相同的源/目标节点对重新运行时，会执行 upsert（匹配现有边），而不是创建重复项。

其他故障模式（身份验证格式错误、缺少 input_params、JSON 格式错误）参见 references/troubleshooting.md。

为新端点进行调整

如果需要在一次执行中创建目标节点和关系——例如，创建一个新的 Comment 并将其链接到现有的 Document——请将此技能的模式与 indykite-ciq-create-node 结合使用：

• 策略：同时包含 allowed_upserts.nodes.node_types（用于新节点标签）和 allowed_upserts.relationships.relationship_types（用于新边）。
• 知识查询：为新节点添加一个 upsert_nodes 条目，再添加一个 upsert_relationships 条目，其中 source 或 target 是新节点的 name。

这两项技能涵盖了各自的部分；组合起来只需在双方各自的 upsert_* 数组中额外添加一个条目。每项操作都必须在策略中列入白名单。

结果

成功应用此技能后：

• 关系创建 CIQ 策略已存在；它只有一个 subject.type，包含匹配两个端点节点的 Cypher 模式、通过 external_id 固定节点的部分过滤器，以及 allowed_upserts.relationships.relationship_types 白名单——不包含 node_types、existing_relationships、allowed_reads（除非有意添加）或 allowed_deletes。
• 知识查询引用该策略，并在 upsert_relationships 中恰好列出一个新关系，其 name 是全新的，源／目标变量来自 cypher，且 type 正确。
• POST /contx-iq/v1/execute 返回包含投影节点和新关系内部标识符的 data。
• 后续读取（例如通过 indykite-ciq-read）可在 IKG 中找到新边。

此技能中的文件

• references/policy-reference.md - 关系创建策略架构、{type, source_node_label, target_node_label} 三元组，以及省略其他区块的原因。
• references/knowledge-query-reference.md - upsert_relationships 架构、可选属性，以及如何返回新关系。
• references/execution-reference.md - 用于写入关系的 POST /contx-iq/v1/execute、身份验证组合，以及包含 Id／ElementId／StartId／EndId 的响应格式。
• references/troubleshooting.md - 针对 403／422／Cypher 无匹配／变量与标签混淆的症状 → 原因 → 修复表。
• assets/policy-create-played-at.json - 可运行的 _Application → (Track)-[:PLAYED_AT]->(Venue) 策略。
• assets/knowledge-query-create-played-at.json - 对应的知识查询。
• scripts/execute.sh - 使用正确标头向 /contx-iq/v1/execute 发送请求的 Bash 辅助脚本。

特定于 Agent 的说明

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

参考资料

• ContX IQ 指南（开发者中心）
• 音乐数据集教程 - 第 8 章“ContX IQ 策略”和第 9 章“知识查询” - 针对真实图谱的具体读取、写入和删除变体；kqb 模式是规范的关系创建变体。
• 开发者中心资源 - CIQ 示例 - 资源示例中可运行的 policyAllowUpsertRelationships / knowledgeQueryUpsertRelationships 配对。
• Config API 文档
• Cypher 查询语言手册（Neo4j；openCypher） - CIQ 策略和 Knowledge Query 条件中使用的图查询语言，适用于 IndyKite Knowledge Graph。
• IndyKite Terraform 提供程序 - indykite_authorization_policy 和 indykite_knowledge_query
• 凭据指南