indykite-ciq-create-node

IndyKite ContX IQ - 创建新节点

通过 ContX IQ 策略和知识查询在 IndyKite Graph（IKG）中创建全新节点，并通过 POST /contx-iq/v1/execute 执行。策略声明一个 allowed_upserts.nodes.node_types 白名单，其中列出允许创建的节点标签；知识查询的 upsert_nodes 数组指定节点名称、设置其 external_id，并列出要写入的属性。（CIQ 写入使用与读取相同的策略和知识查询结构。）

此技能仅涵盖节点创建。其他写入路径有意不在范围内：

• 更新现有节点的属性使用 allowed_upserts.nodes.existing_nodes，并在知识查询的 upsert_nodes 条目中引用策略 cypher 里的变量（不使用 external_id）。字段不同，KQ 结构也不同。
• 创建关系使用 allowed_upserts.relationships.relationship_types（{type, source_node_label, target_node_label} 三元组），以及知识查询的 upsert_relationships 数组。
• 删除使用 allowed_deletes 和 delete_nodes / delete_relationships。

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

适用场景

在以下情况下启用此技能：

• 用户想通过 CIQ 在 IKG 中创建新节点（例如，摄取新的 Track、Document、Account 或其他实体）；
• 用户正在编写以 _Application 为主体的“目录写入”策略和知识查询——这是 ETL / 系统端摄取的常见模式；
• 用户要通过执行时的 input_params 参数化新节点的 external_id 和属性；
• 用户正在排查本应创建节点却未成功的 POST /contx-iq/v1/execute 调用所返回的 403 / 422 错误。

在以下情况下不要启用此技能：

• 用户想从 IKG 读取数据——请使用 indykite-ciq-read；
• 用户想更新现有节点的属性——策略字段（existing_nodes）和 KQ 结构均不同；
• 用户想创建节点之间的关系——策略字段（relationship_types）和 KQ 数组（upsert_relationships）均不同；
• 用户想删除内容——策略字段（allowed_deletes）和 KQ 数组均不同；
• 用户使用 Capture API（POST /capture/v1/nodes）或 Terraform 而非 CIQ 来摄取数据——这些是独立的摄取路径。

前提条件

• IndyKite 项目、AppAgent 和 AppAgent 凭据（执行时，AppAgent 令牌需传入 X-IK-ClientKey）。
• 具有 Config API 访问权限的 Service Account 令牌，以及项目在 PROJECT_GID 中的 GID——这两者用于创建策略和知识查询。
• 新节点将使用的节点标签（Track、Document、Customer 等）——该标签应已属于项目的数据模型。
• 对于非 _Application 主体，其主体节点必须已存在于 IKG 中（CIQ 不会创建主体，只会针对主体进行授权）。
• external_id 的规划——这是新节点的稳定标识符。调用方每次都必须二选一：在策略/KQ 中将其硬编码（较少见），或在执行时将其作为 $param 提供（较常见）。

如果缺少其中任何一项，请停止并告知用户——先解决这些问题，远比排查含糊的 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 变体 - 例如，用户创建自己的 Playlist - 只在 subject.type、过滤条件和执行请求头上有所不同。

Cypher 锚点 - 即使策略仅用于写入，也需要一个 MATCH 子句锚定主体。新节点不会在 cypher 中匹配；它通过 Knowledge Query 的 upsert_nodes 声明。

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

系统端目录导入：_Application 在执行时提供 external_id、title 和 loudness，以创建新的 Track 节点。

MATCH (subject:_Application)

这就是完整的 cypher - 仅需足以识别主体。这里不会出现 Track。

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

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

• meta.policy_version - 当前为 1.0-ciq。
• subject.type - 在运行示例中为 _Application。
• condition.cypher 和 condition.filter - 锚定主体。对于 _Application，过滤条件为 subject.external_id = $_appId（这是一个保留值，执行时会从 AppAgent 自动填入）。
• allowed_upserts.nodes.node_types - Knowledge Query 可以作为新节点创建的节点标签数组。

如果此策略仅创建节点，请省略 allowed_reads、allowed_deletes 和其他 allowed_upserts 子字段。省略这些字段是禁止相应操作的受支持方式。

运行示例的完整仅创建策略：参见 assets/policy-create-track.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/assets/policy-create-track.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。

完整架构（运算符、属性约定，以及省略 existing_nodes 和 allowed_reads 的原因）请参见 references/policy-reference.md。

3. 使用 upsert_nodes 创建知识查询

知识查询引用策略并列出要写入的内容。upsert_nodes 中的每个条目都描述要创建的一个节点：

• name - 一个独特的变量名，不能与策略的 cypher 中使用的变量名重复。其他数组（nodes、relationships）会引用此变量。
• type - 节点标签。必须包含在策略的 allowed_upserts.nodes.node_types 中。
• external_id - 新节点必填。一次性写入时可使用硬编码值；更常见的做法是使用 $param，由调用方在执行时提供。
• is_identity - 可选的布尔值。设为 true 会将节点创建为身份节点——请参阅下方说明。
• labels - 可选的额外标签数组，与 type 一同附加。
• properties - {type, value, metadata?} 项组成的数组。type（属性名）必须硬编码；value 可以硬编码，也可以使用 $param。

在顶层 nodes 数组中列出新节点的变量名，即可在响应中返回该节点。

身份节点。 在 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 评估。

运行示例的完整知识查询：请参阅 assets/knowledge-query-create-track.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/assets/knowledge-query-create-track.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）——execute 和 MCP ciq_execute 工具会引用此 ID。

所有知识查询字段的架构详情（包括无法设置的受保护属性名称）：references/knowledge-query-reference.md。

4. 进行身份验证并执行

执行端点与读取操作相同：

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

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

• X-IK-ClientKey: <AppAgent-credentials-token> - 必填。
• Authorization: Bearer … - 对于 _Application 主体，省略此项。AppAgent 本身会对主体进行身份验证，且 $_appId 会从应用的 external_id 自动填入。

对于以 Person 为主体的创建流程，请添加 Authorization: Bearer <user-access-token>，策略中针对 subject.external_id = $token.sub 的筛选条件会将 cypher 锚定到该用户。

请求正文：

{
  "id": "<knowledge_query_gid_or_name>",
  "input_params": {
    "track_external_id": "track-99",
    "track_title": "New Hot Track",
    "track_loudness": -7.5
  }
}

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

完整的执行参考（身份验证组合、响应结构、错误代码）：references/execution-reference.md。

5. 验证响应并确认新节点

创建执行成功后，会返回新节点的投影：

{
  "data": [
    {
      "nodes": {
        "newTrack.external_id": "track-99",
        "newTrack.property.title": "New Hot Track",
        "newTrack.property.loudness": -7.5
      }
    }
  ]
}

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

1. 标签在白名单中。 知识查询的 upsert_nodes[].type 必须包含在策略的 allowed_upserts.nodes.node_types 中。不匹配 → 403。
2. 已设置 external_id。 创建新节点时必须设置。如果通过参数传入（"$track_external_id"），调用方必须在 input_params 中提供该值。缺失 → 422 invalid_argument: missing or wrong input params。
3. name 不与 cypher 变量冲突。 upsert_nodes[].name 中的变量名应当是全新的，不能是在策略的 cypher 中已经出现的名称。如果发生冲突，策略会认为你要更新现有匹配项，而不是创建新节点。
4. 属性名称不属于受保护集合。 _service、create_time、external_id、id、type、update_time 不能作为属性设置，因为它们由平台管理。
5. 该节点之前不存在。 使用相同的 external_id 重新运行会执行 upsert（更新），而不是创建；响应看起来会类似，但不会添加新节点。

其他故障情况（身份验证格式错误、JSON 格式错误、主体筛选条件不匹配），请参阅 references/troubleshooting.md。

结果

成功应用此技能后：

• 项目中存在一个仅用于创建的 CIQ 策略；它只有一个 subject.type、一个锚定到主体的 Cypher 模式、可选的部分筛选条件，以及一个 allowed_upserts.nodes.node_types 白名单——不包含 allowed_reads、allowed_deletes 或 existing_nodes。
• 一个知识查询引用该策略，并在 upsert_nodes 中恰好列出一个新节点，该节点具有不同的 name、正确的 type、一个 external_id 和要设置的属性。
• POST /contx-iq/v1/execute（或 MCP ciq_execute 工具）成功时会返回新节点的投影。
• 后续读取查询（例如通过 indykite-ciq-read）会在 IKG 中找到新节点。

此技能中的文件

• references/policy-reference.md - 面向写入的策略架构、allowed_upserts.nodes 深入说明（existing 与 node_types 的区别），以及省略其他块的原因。
• references/knowledge-query-reference.md - upsert_nodes 架构、属性与元数据、通过 labels 创建身份节点、受保护的属性名称，以及返回新节点的方式。
• references/execution-reference.md - 用于写入的 POST /contx-iq/v1/execute、包括 _Application 保留参数 $_appId 在内的身份验证组合，以及响应格式。
• references/troubleshooting.md - 403 / 422 / 重复的 external_id / 缺少属性等问题模式。
• assets/policy-create-track.json - _Application → 新建 Track 示例的可运行仅创建策略。
• assets/knowledge-query-create-track.json - 对应的知识查询。
• 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 指南（开发者中心）
• 音乐数据集教程 - 第 8 章“ContX IQ 策略”和第 9 章“知识查询” - 使用真实图谱演示具体的读取、写入和删除变体。
• Config API 文档
• Cypher 查询语言手册（Neo4j；openCypher） - 在 IndyKite 知识图谱上，CIQ 策略和知识查询条件使用的图查询语言。
• IndyKite Terraform 提供程序 - indykite_authorization_policy 和 indykite_knowledge_query
• 凭据指南