indykite-ciq-create-node-with-link

IndyKite ContX IQ - 创建新节点并将其关联到现有节点

通过一次原子 POST /contx-iq/v1/execute 调用，在 IndyKite Graph（IKG）中创建全新节点，并将其连接到一个或多个现有节点。策略会将一个节点标签和一个或多个关系三元组列入允许列表，Knowledge Query 则同时包含 upsert_nodes（用于新节点）和 upsert_relationships（用于新关系边）；upsert_nodes 中新节点的变量 name 会在 upsert_relationships 中作为 source 或 target 引用。此模式结合了 indykite-ciq-create-node 和 indykite-ciq-create-relationship 中的模式。

这是**“将新实体摄取到图中”的标准模式**——用于 IndyKite 开发者中心资源中的保险合同示例（policyAllowWriteContract + knowledgeQueryAllowWriteContract）：一次 execute 调用会创建一个新的 Contract 节点，并通过两个关系将其连接起来（COVERS 关联到一个 Vehicle，ACCEPTED 由一个 Person 指向该节点）。

其他场景有意不在此范围内：

• 仅创建节点，不建立关联——使用 indykite-ciq-create-node。
• 仅关联两个现有节点——使用 indykite-ciq-create-relationship。
• 更新现有节点的属性或关系的属性——这是完全不同的操作。

适用场景

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

• 想通过 CIQ 在一次原子操作中摄取新实体（创建节点，并且建立它与现有节点之间的关系）；
• 正在实现标准的保险/合同模式：将一个新的 Contract 节点关联到一个现有的 Vehicle 和一个现有的 Person；
• 正在构建“向文档添加评论”的流程：将一个新的 Comment 节点关联到一个现有的 Document；
• 需要通过 input_params 将新节点的 external_id 和 source/target 端点都设为参数；
• 正在排查组合创建 execute 返回的 403 / 422 错误，而该操作本应将新节点关联起来。

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

• 只需创建节点——使用 indykite-ciq-create-node；
• 只需关联两个现有节点——使用 indykite-ciq-create-relationship；
• 需要写入现有元素的属性——使用属性写入技能。

前提条件

• 一个 IndyKite 项目、AppAgent 和 AppAgent 凭据。
• 一个具有 Config API 访问权限的服务账号令牌，以及项目的 GID，位于 PROJECT_GID 中——两者都用于创建策略和 Knowledge Query。
• 新节点将要关联的端点节点已存在于 IKG 中。
• 操作将使用的节点标签和关系标签已获项目数据模型允许。
• 已为新节点的 external_id 制定方案——通常通过 $param 设置参数。

步骤

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 变体（例如，用户发布一条关联到其拥有的现有 Document 的新 Comment）仅在 subject.type、过滤条件和执行请求头上有所不同。

Cypher 模式——必须 MATCH 主题以及新节点将要关联的每个现有端点。新节点本身不要匹配；它在 upsert_nodes 中声明。如果不确定项目 IKG 中确切的节点类型、关系类型或属性拼写，请先从数据架构 API 中读取（indykite-data-schema）——名称拼写错误会导致静默地匹配不到任何内容，而模式匹配不到任何内容的写入操作会变成空操作，但仍返回 200。

示例（本技能全文使用，原样摘自 developer-hub 的 policyAllowWriteContract 资源）：

一个 _Application 创建新的 Contract 节点，并通过 :COVERS 将其关联到现有的 Vehicle（该车辆由现有的 Company 所有），再通过 :ACCEPTED 从现有的 Person 关联到该节点。

MATCH (subject:_Application)-[r1:HAS_AGREEMENT_WITH]->(company:Company)-[r2:OWNS]->(vehicle:Vehicle)
MATCH (person:Person)

变量：subject、r1、company、r2、vehicle、person。新的 Contract 节点将在 upsert_nodes 中声明为一个全新的 name；两个新关系将引用 vehicle、person 和这个全新的 name 作为端点。

2. 同时使用 node_types 和 relationship_types 编写策略

使用以下五个部分构建策略 JSON：

• meta.policy_version——当前为 1.0-ciq。
• subject.type——本示例中为 _Application。
• condition.cypher 和 condition.filter——Cypher 匹配主题和现有端点；过滤条件通过 external_id 固定这些对象（$_appId 加上 $vehicleID、$personID）。
• allowed_upserts.nodes.node_types——新节点的标签（例如 ["Contract"]）。
• allowed_upserts.relationships.relationship_types——每个新关系对应一个三元组，方向和标签必须匹配。

本示例的完整组合创建策略：参见 assets/policy-create-contract.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-node-with-link/assets/policy-create-contract.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 和 relationship_types 如何交互、方向为何重要，以及 existing_nodes 会增加什么），请参见 references/policy-reference.md。

3. 同时使用 upsert_nodes 和 upsert_relationships 创建知识查询

知识查询包含两个写入数组：

upsert_nodes - 声明新节点。结构与 indykite-ciq-create-node 中相同：

• name - 新变量名（不在 cypher 中），例如 contract。
• type - 节点标签，必须与 allowed_upserts.nodes.node_types 匹配。
• external_id - 新节点必填；通常为 $param。
• is_identity - 可选布尔值。true 会将节点创建为身份节点——请参阅下方说明。
• labels - 可选的额外标签数组，与 type 一同附加。
• properties - 由 {type, value, metadata?} 项组成的数组。

身份节点。 在 upsert_nodes 条目上设置 "is_identity": true——与 Capture API 中的标志相同。它会添加 DigitalTwin 标签，这是 IKG 标记身份节点的方式。"labels": ["DigitalTwin"] 也能达到相同效果，但建议使用该标志：保存知识查询时，拼写错误的键会被拒绝，而拼写错误的标签只会被静默存储为另一个标签。这两者都不需要加入策略的 node_types 白名单，因为该白名单只检查 type。如果节点必须作为 2.0-kbac 主体，就应将其创建为身份节点：非身份主体会导致每个 2.0-kbac 决策都静默返回 false（3.0-kbac 不要求如此）。要确认标签已生效，请使用新节点作为主体运行 2.0-kbac 评估。

upsert_relationships - 声明每个新关系。结构与 indykite-ciq-create-relationship 中相同，但有一处重要区别：

• name - 每个新关系使用的新变量名（例如 r3、r4）。
• source - 变量名。可以是 cypher 变量（现有节点），也可以是某个 upsert_nodes 条目的 name（刚创建的节点）。
• target - 同样可以是 cypher 变量或 upsert_nodes 的 name。
• type - 必须与策略的 relationship_types 匹配。

正是 source/target 的这种灵活性让组合操作得以实现：r3 将刚创建的 contract 与现有的 vehicle 连接起来；r4 将现有的 person 与刚创建的 contract 连接起来。

运行示例的完整组合创建知识查询见 assets/knowledge-query-create-contract.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-node-with-link/assets/knowledge-query-create-contract.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

对于 _Application 主体：

• X-IK-ClientKey: <AppAgent-credentials-token> - 必填。
• Authorization: Bearer … - 省略。

请求：

{
  "id": "<knowledge_query_gid_or_name>",
  "input_params": {
    "vehicleID": "car2",
    "personID":  "ryan",
    "contract_external_id": "ct853",
    "contractNumber":       "rbjh853"
  }
}

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

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

5. 验证响应并确认关联

成功执行组合创建后，会返回新节点的投影以及新关系的标识符：

{
  "data": [
    {
      "nodes": {
        "contract.external_id":     "ct853",
        "contract.property.number": "rbjh853"
      },
      "relationships": {
        "r3": { "Id": …, "ElementId": "…", "StartId": …, "EndId": … },
        "r4": { "Id": …, "ElementId": "…", "StartId": …, "EndId": … }
      }
    }
  ]
}

如果响应并非预期结果，请逐项检查：

1. 两项白名单均存在。 KQ 的 upsert_nodes[].type 必须位于 allowed_upserts.nodes.node_types 中，并且每个 upsert_relationships[] 三元组都必须位于 allowed_upserts.relationships.relationship_types 中。任一项不匹配 → 403。
2. 端点存在。 关系引用的每个 Cypher 变量（vehicle、person）都必须解析为真实节点。如果 MATCH 未找到任何行，该操作就没有可关联的内容 - 返回 200，且 data 为空。
3. 交叉引用匹配。 upsert_nodes 中新节点的 name（例如 contract）必须与 upsert_relationships[].source 或 target 中使用的字符串完全相同。此处的拼写错误会导致关联失败，且不会明确提示。
4. 方向匹配。 关系三元组会编码方向。(Contract)-[:COVERS]->(Vehicle) 与 (Vehicle)-[:COVERS]->(Contract) 不同。
5. 所有 $param 均已提供。 contract_external_id、contractNumber、vehicleID、personID 都必须位于 input_params 中。

其他故障模式请参阅 references/troubleshooting.md。

结果

成功应用此技能后：

• 存在一项组合创建 CIQ 策略；它具有单个 subject.type、匹配主体和现有端点节点的 Cypher 模式、部分筛选条件，并且已填充 allowed_upserts.nodes.node_types 和 allowed_upserts.relationships.relationship_types。
• 一个 Knowledge Query 引用了该策略，并在 upsert_nodes 中列出新节点，在 upsert_relationships 中列出一个或多个新关系（其中新节点的 name 被用作 source 或 target）。
• 一次 POST /contx-iq/v1/execute 调用会返回新节点的投影以及新关系的标识符。
• 后续读取确认新实体已关联到图中。

此技能中的文件

• references/policy-reference.md - 组合使用 node_types 和 relationship_types，以及混合创建与更新流程中的可选 existing_nodes。
• references/knowledge-query-reference.md - upsert_nodes 与 upsert_relationships 的交互、source/target 交叉引用、通过 labels 指定的身份节点、多关系模式。
• references/execution-reference.md - 请求/响应、原子性保证、重新运行时的幂等性。
• references/troubleshooting.md - 403 / 空数据 / 关联不匹配 / 交叉引用模式。
• assets/policy-create-contract.json - 标准的保险 Contract 示例，取自开发者中心资源中的 policyAllowWriteContract。
• assets/knowledge-query-create-contract.json - 对应的 Knowledge Query。
• scripts/execute.sh - Bash 辅助脚本。

Agent 专属说明

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

参考资料

• ContX IQ 指南（开发者中心） - 完整架构，包括 upsert_nodes 和 upsert_relationships 如何相互引用。
• 开发者中心资源 - policyAllowWriteContract 和 knowledgeQueryAllowWriteContract - 本技能基于的标准保险合同示例。
• 音乐数据集教程 - 第 9 章“知识查询” - 用于上下文感知数据导入模式的 kqb 写入变体。
• Config API 文档
• Cypher 查询语言手册（Neo4j；openCypher） - CIQ 策略和 Knowledge Query 条件中使用的图查询语言，适用于 IndyKite Knowledge Graph。
• IndyKite Terraform 提供程序