GraphQL 变更参考

数据墙DBW 为每个实体自动生成变更（Mutation）操作。本文档完整描述 create、update、delete 和存储过程执行的语法和参数。

变更类型

每个实体自动生成三种变更操作：

变更	命名规则	示例	支持的操作
创建	create{Entity}	createBook	插入新记录
更新	update{Entity}	updateBook	按主键修改记录
删除	delete{Entity}	deleteBook	按主键删除记录

create — 创建记录

mutation {
  createBook(item: { id: 100, title: "新书", year: 2024, pages: 280 }) {
    id
    title
    year
  }
}

item 参数为输入对象，包含要插入的字段和值。返回创建的记录。

使用变量

mutation CreateBook($item: CreateBookInput!) {
  createBook(item: $item) { id title year }
}

变量：

{ "item": { "id": 100, "title": "新书", "year": 2024, "pages": 280 } }

update — 更新记录

mutation {
  updateBook(id: 1, item: { title: "更新后的书名" }) {
    id
    title
  }
}

参数	说明
id（或对应主键名）	要更新的记录主键值
item	包含要更新字段的对象，只传需要修改的字段

delete — 删除记录

mutation {
  deleteBook(id: 999) {
    id
    title
  }
}

按主键删除记录。删除的记录不存在时返回错误。

多重变更

可以在一个 mutation 中组合多个操作：

同一请求不同实体

mutation {
  createBook(item: { id: 200, title: "新书" }) { id title }
  updateAuthor(id: 10, item: { name: "更新名称" }) { id name }
  deleteBook(id: 99) { id }
}

多个操作按顺序依次执行。不支持事务——某个操作失败时已执行的操作不会回滚。

同一实体的多个操作（使用别名）

mutation {
  book1: createBook(item: { id: 301, title: "第一本" }) { id title }
  book2: createBook(item: { id: 302, title: "第二本" }) { id title }
  book3: updateBook(id: 300, item: { title: "更新的书名" }) { id title }
}

别名是必需的——同名字段在 GraphQL 中必须用别名区分。

多重创建

默认禁用，需要在运行时中启用：

{
  "runtime": {
    "graphql": {
      "multiple-mutations": {
        "create": {
          "enabled": true
        }
      }
    }
  }
}

启用后，create 的 item 参数变为 items（复数），接受对象数组：

mutation {
  createBooks(items: [
    { id: 101, title: "第一本", year: 2024, pages: 280 }
    { id: 102, title: "第二本", year: 2024, pages: 320 }
  ]) {
    items { id title }
  }
}

IMPORTANT

多重创建仅 SQL Server 支持。需要数据库连接字符串启用 MultipleActiveResultSets=True。

存储过程执行

存储过程在 GraphQL 中自动以 execute 前缀命名：

{
  executeGetBookById(id: 1) {
    id
    title
  }
}

mutation {
  executeUpdateInventory(productId: 42, quantity: 10) {
    productId
    newQuantity
  }
}

存储过程的参数直接作为 GraphQL 字段参数传递。只返回第一个结果集。

部分成功处理

多重变更中某个操作失败时：

{
  "data": {
    "createBook": { "id": 101, "title": "第一本" },
    "deleteBook": null
  },
  "errors": [
    {
      "message": "Could not find item with the given key.",
      "path": ["deleteBook"]
    }
  ]
}

客户端需要同时检查 data 和 errors 来确认每个操作的结果。

数据库要求

• SQL Server 用户使用多重变更时需要 MultipleActiveResultSets=True。
• 连接池配置 Pooling=False 可能导致变更操作失败。
• 变更操作需要对应实体的权限配置中有 create、update、delete 或 execute 操作。

变更操作支持矩阵

操作	表	视图	存储过程
create	✓	若可更新	—
update	✓	若可更新	—
delete	✓	若可更新	—
execute	—	—	✓
多重创建	✓（MSSQL only）	—	—

下一步

• GraphQL 查询 — 查询语法和参数完全参考。
• GraphQL 聚合 — 聚合函数和分组查询。
• GraphQL 端点 — 端点配置。