Entities

数据库实体的配置设置。

Health

属性	描述
`entities.entity-name.health.enabled`	为实体启用健康检查（REST 和 GraphQL 端点）
`entities.entity-name.health.first`	健康检查查询返回的行数（范围：1-500）
`entities.entity-name.health.threshold-ms`	健康检查查询的最大持续时间（毫秒）（最小值：1）

Description

属性	描述
`entities.entity-name.description`	实体的人类可读描述

Fields

属性	描述
`entities.entity-name.fields[].name`	数据库字段名称（必需）
`entities.entity-name.fields[].alias`	API 公开名称（替代 mappings）
`entities.entity-name.fields[].description`	字段的人类可读描述
`entities.entity-name.fields[].primary-key`	将字段标记为主键（替代 key-fields）

Source

属性	描述
`entities.entity-name.source.type`	对象类型：`table`、`view` 或 `stored-procedure`
`entities.entity-name.source.object`	数据库对象的名称
`entities.entity-name.source.object-description`	数据库对象的人类可读描述
`entities.entity-name.source.parameters`	存储过程或函数的参数
`entities.entity-name.source.key-fields`	~~视图的主键字段列表~~（已弃用）
`entities.entity-name.mappings`	~~将 API 字段名映射到数据库列~~（已弃用）

REST

属性	描述
`entities.entity-name.rest.enabled`	为此实体启用 REST
`entities.entity-name.rest.path`	REST 端点的自定义路由
`entities.entity-name.rest.methods`	允许的 REST 方法：`get`、`post`、`put`、`patch`、`delete`

GraphQL

属性	描述
`entities.entity-name.graphql.type`	类型名称或包含 `singular` 和 `plural` 的对象
`entities.entity-name.graphql.operation`	操作类型：`query` 或 `mutation`
`entities.entity-name.graphql.enabled`	为此实体启用 GraphQL

Permissions

属性	描述
`entities.entity-name.permissions[].role`	角色名称字符串
`entities.entity-name.permissions[].actions`	一个或多个：`create`、`read`、`update`、`delete`、`execute`

Relationships

属性	描述
`entities.entity-name.relationships.relationship-name.cardinality`	`one` 或 `many`
`entities.entity-name.relationships.relationship-name.target.entity`	目标实体的名称
`entities.entity-name.relationships.relationship-name.source.fields`	关系中使用的源实体字段
`entities.entity-name.relationships.relationship-name.target.fields`	目标实体的字段
`entities.entity-name.relationships.relationship-name.linking.object`	用于多对多关系的联接对象
`entities.entity-name.relationships.relationship-name.linking.source.fields`	联接中使用的源实体字段
`entities.entity-name.relationships.relationship-name.linking.target.fields`	联接中使用的目标实体字段

Cache

属性	描述
`entities.entity-name.cache.enabled`	为实体启用响应缓存
`entities.entity-name.cache.ttl-seconds`	缓存生存时间（秒）
`entities.entity-name.cache.level`	缓存级别：`L1`（仅内存）或 `L1L2`（内存 + 分布式）

MCP

属性	描述
`entities.entity-name.mcp`	控制实体的 Model Context Protocol (MCP) 参与的对象
`entities.entity-name.mcp.dml-tools`	为实体启用或禁用数据操作语言 (DML) 工具
`entities.entity-name.mcp.custom-tool`	将存储过程注册为命名 MCP 工具（仅限存储过程实体）

格式概览

json

{
  "entities": {
    "{entity-name}": {
      "description": <string>,
      "rest": {
        "enabled": <boolean> // default: true
        "path": <string> // default: "{entity-name}"
        "methods": ["GET", "POST"] // default: ["GET", "POST"]
      },
      "graphql": {
        "enabled": <boolean> // default: true
        "type": {
          "singular": <string>,
          "plural": <string>
        },
        "operation": "query" | "mutation" // default: "query"
      },
      "source": {
        "object": <string>,
        "object-description": <string>,
        "type": "view" | "stored-procedure" | "table",
        "key-fields": [<string>], // DEPRECATED: use fields[].primary-key
        "parameters": [ // array format (preferred)
          {
            "name": "<parameter-name>",
            "required": <boolean>,
            "default": <value>,
            "description": "<string>"
          }
        ]
      },
      "fields": [
        {
          "name": "<database-field-name>",
          "alias": "<api-exposed-name>",
          "description": "<string>",
          "primary-key": <boolean>
        }
      ],
      "mappings": { // DEPRECATED: use fields[].alias
        "<database-field-name>": <string>
      },
      "relationships": {
        "<relationship-name>": {
          "cardinality": "one" | "many",
          "target.entity": <string>,
          "source.fields": [<string>],
          "target.fields": [<string>],
          "linking.object": <string>,
          "linking.source.fields": [<string>],
          "linking.target.fields": [<string>]
        }
      },
      "permissions": [
        {
          "role": "anonymous" | "authenticated" | <custom-role>,
          "actions": ["create", "read", "update", "delete", "execute", "*"],
          "fields": {
            "include": [<string>],
            "exclude": [<string>]
          },
          "policy": {
            "database": <string>
          }
        }
      ],
      "cache": {
        "enabled": <boolean>,
        "ttl-seconds": <integer>,
        "level": "L1" | "L1L2" // default: "L1L2"
      },
      "mcp": {
        "dml-tools": <boolean>,       // default: true
        "custom-tool": <boolean>      // stored-procedure only; default: false
      }
    }
  }
}

Source（entity-name 实体）

父级	属性	类型	必需	默认值
`entities.{entity-name}`	`source`	对象	✔️ 是	无

实体的数据库源详细信息。

嵌套属性

父级	属性	类型	必需	默认值
`entities.{entity-name}.source`	`object`	字符串	✔️ 是	无
`entities.{entity-name}.source`	`object-description`	字符串	❌ 否	无
`entities.{entity-name}.source`	`type`	枚举（`table`、`view`、`stored-procedure`）	✔️ 是	无
`entities.{entity-name}.source`	`key-fields`	字符串数组	❌ 否*	无
`entities.{entity-name}.source`	`parameters`	数组或对象	❌ 否**	无

* key-fields 仅在 type 为 view 且未使用 fields 数组时必需。该值表示主键。

警告：key-fields 属性在数据墙DBW 2.0 中已弃用。请改用 fields 数组配合 primary-key: true。架构强制要求 fields 和 key-fields 不能在同一实体上共存。

** parameters 仅在 type 为 stored-procedure 时必需，且仅用于具有默认值的参数。参数的数据类型是推断的。没有默认值的参数可以省略。

object-description 是底层数据库对象的可选人类可读描述。此值在 MCP 工具发现期间显示，帮助 AI 代理理解实体的用途。

提示： 如果对象属于 dbo 架构，则指定架构是可选的。此外，当需要时可以在对象名称周围使用方括号（例如 dbo.Users 与 [dbo].[Users]）。

格式

json

{
  "entities": {
    "{entity-name}": {
      "source": {
        "object": <string>,
        "object-description": <string>,
        "type": <"view" | "stored-procedure" | "table">,
        "key-fields": [ <string> ], // DEPRECATED: use fields[].primary-key
        "parameters": [ // array format (preferred)
          {
            "name": "<parameter-name>",
            "required": <boolean>,
            "default": <value>,
            "description": "<string>"
          }
        ]
      }
    }
  }
}

Parameters 数组格式

在数据墙DBW 2.0 预览版中，parameters 支持具有更丰富元数据的结构化数组格式。每个参数是一个具有以下属性的对象：

属性	类型	必需	描述
`name`	字符串	✔️ 是	参数名称（不带 `@` 前缀）
`required`	布尔值	❌ 否	参数是否必需（`true`）或可选（`false`）
`default`	任意	❌ 否	未提供参数时使用的默认值
`description`	字符串	❌ 否	参数的人类可读描述

示例（数组格式 - 推荐）

json

{
  "entities": {
    "GetBookById": {
      "source": {
        "type": "stored-procedure",
        "object": "dbo.get_book_by_id",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "default": null,
            "description": "The unique identifier of the book"
          }
        ]
      }
    }
  }
}

警告：parameters 的字典格式（例如 { "id": 0 }）在数据墙DBW 2.0 中已弃用。请使用上述数组格式。旧格式仍被接受以保持向后兼容性，但将在未来版本中移除。

注意： 此功能为数据墙DBW 2.0 预览版。

Permissions（entity-name 实体）

父级	属性	类型	必需	默认值
`entities.permissions`	`role`	字符串	✔️ 是	无

指定权限应用的角色名称。使用系统角色（Anonymous、Authenticated）或在身份提供程序中定义的自定义角色。

提示： 有关角色评估、系统角色和 X-MS-API-ROLE 头的详细信息，请参阅授权概述。

格式

json

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "role": <"Anonymous" | "Authenticated" | "custom-role">,
          "actions": [ <string> ]
        }
      ]
    }
  }
}

示例

json

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "reader",
          "actions": ["read"]
        }
      ]
    }
  }
}

角色继承

数据墙DBW 2.0 为实体权限引入了角色继承。当未为实体显式配置角色时，它会使用以下链从更广泛的角色继承权限：

text

named-role → authenticated → anonymous

如果未为实体配置 authenticated，则从 anonymous 继承。
如果未配置命名角色，则从 authenticated 继承，如果 authenticated 也不存在，则从 anonymous 继承。

这意味着您可以在 anonymous 上定义一次权限，每个更广泛的角色都会自动获得相同的访问权限，无需重复配置。

注意： 此功能为数据墙DBW 2.0 预览版。

示例

json

{
  "entities": {
    "Book": {
      "source": "dbo.books",
      "permissions": [
        { "role": "anonymous", "actions": [ "read" ] }
      ]
    }
  }
}

使用此配置，anonymous、authenticated 和任何未配置的命名角色都可以读取 Book。使用 dab configure --show-effective-permissions 可查看继承应用后每个实体的解析权限。

Actions（字符串数组 Permissions entity-name 实体）

父级	属性	类型	必需	默认值
`entities.permissions`	`actions`	oneOf [string, array]	✔️ 是	无

详细说明关联角色允许哪些操作的字符串数组。

操作	SQL 操作
`*`	所有操作
`create`	插入一行或多行*
`read`	选择一行或多行
`update`	修改一行或多行*
`delete`	删除一行或多行*
`execute`	运行存储过程

* 多操作当前仅在 GraphQL 中支持。

注意： 对于存储过程，通配符（*）操作仅扩展为 execute 操作。对于表和视图，它扩展为 create、read、update 和 delete。

格式

json

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "actions": [ <string> ]
        }
      ]
    }
  }
}

示例

json

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "actions": [ "*" ] // equivalent to create, read, update, delete
        }
      ]
    }
  }
}

替代格式（仅字符串，当 `type=stored-procedure`）

json

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "actions": <string>
        }
      ]
    }
  }
}

示例

json

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "actions": "*" // equivalent to execute
        }
      ]
    }
  }
}

Actions（对象数组 Permissions entity-name 实体）

父级	属性	类型	必需	默认值
`entities.{entity-name}.permissions`	`actions`	字符串数组	✔️ 是	无

详细说明关联角色允许哪些操作的对象数组。

注意： 对于存储过程，通配符（*）操作仅扩展为 execute。对于表/视图，它扩展为 create、read、update 和 delete。

嵌套属性

父级	属性	类型	必需	默认值
`entities.{entity-name}.permissions.actions[]`	`action`	字符串	✔️ 是	无
`entities.{entity-name}.permissions.actions[]`	`fields`	对象	❌ 否	无
`entities.{entity-name}.permissions.actions[]`	`policy`	对象	❌ 否	无
`entities.{entity-name}.permissions.actions[].policy`	`database`	字符串	✔️ 是	无

格式

json

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "role": <string>,
          "actions": [
            {
              "action": <string>,
              "fields": <array of strings>,
              "policy": <object>
            }
          ]
        }
      ]
    }
  }

示例

这授予 auditor 对 User 实体的 read 权限，具有字段和策略限制。

json

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "auditor",
          "actions": [
            {
              "action": "read",
              "fields": {
                "include": ["*"],
                "exclude": ["last_login"]
              },
              "policy": {
                "database": "@item.IsAdmin eq false"
              }
            }
          ]
        }
      ]
    }
  }
}

策略说明

数据库策略使用 OData 风格的谓词过滤查询结果。使用 @item.<field> 引用实体字段，使用 @claims.<type> 注入已认证的用户声明。

方面	详细信息
语法	OData 谓词（`eq`、`ne`、`and`、`or`、`gt`、`lt`）
字段引用	`@item.<field>`（如果适用，使用映射名称）
声明引用	`@claims.<claimType>`
支持的操作	`read`、`update`、`delete`
不支持	`create`、`execute`

提示： 有关数据库策略的全面指导，包括声明替换和故障排除，请参阅配置数据库策略。

Type（GraphQL entity-name 实体）

父级	属性	类型	必需	默认值
`entities.{entity-name}.graphql`	`type`	对象	❌ 否

设置 GraphQL 架构中实体的命名约定。

格式

json

{
  "entities": {
    "{entity-name}": {
      "graphql": {
        "type": {
          "singular": "<string>",
          "plural": "<string>"
        }
      }
    }
  }
}

嵌套属性

父级	属性	必需	类型	默认值
`entities.{entity-name}.graphql.type`	`singular`	✔️ 是*	字符串	无
`entities.{entity-name}.graphql.type`	`plural`	❌ 否	字符串	N/A（默认为 singular 值）

* 当 type 指定为对象时，singular 是必需的。当 type 是普通字符串时，该字符串用作单数名称。

示例

配置

json

{
  "entities": {
    "User": {
      "graphql": {
        "type": {
          "singular": "User",
          "plural": "Users"
        }
      }
    }
  }
}

GraphQL 查询

graphql

{
  Users {
    items {
      id
      name
      age
      isAdmin
    }
  }
}

GraphQL 响应

json

{
  "data": {
    "Users": {
      "items": [
        {
          "id": 1,
          "name": "Alice",
          "age": 30,
          "isAdmin": true
        },
        {
          "id": 2,
          "name": "Bob",
          "age": 25,
          "isAdmin": false
        }
        // ...
      ]
    }
  }
}

Operation（GraphQL entity-name 实体）

父级	属性	类型	必需	默认值
`entities.{entity-name}.graphql`	`operation`	枚举字符串	❌ 否	mutation

指定 stored-procedure 操作出现在 Query 还是 Mutation 下。

注意： 当 {entity-name}.type 设置为 stored-procedure 时，会自动创建一个新的 GraphQL 类型 executeXXX。此 operation 属性控制此类型在 GraphQL 架构中的位置。没有功能影响，只是架构整洁性。

格式

json

{
  "entities": {
    "{entity-name}": {
      "graphql": {
        "operation": "query" | "mutation"
      }
    }
  }
}

示例：operation

当 operation 设置为 query

graphql

type Query {
  executeGetUserDetails(userId: Int!): GetUserDetailsResponse
}

当 operation 设置为 mutation

graphql

type Mutation {
  executeGetUserDetails(userId: Int!): GetUserDetailsResponse
}

Enabled（GraphQL entity-name 实体）

父级	属性	类型	必需	默认值
`entities.{entity-name}.graphql`	`enabled`	布尔值	❌ 否	True

允许开发者选择性地将实体包含在 GraphQL 架构中。

格式

json

{
  "entities": {
    "{entity-name}": {
      "graphql": {
        "enabled": <true> (default) | <false>
      }
    }
  }
}

REST（entity-name 实体）

父级	属性	类型	必需	默认值
`entities.{entity-name}.rest`	`enabled`	布尔值	❌ 否	True
`entities.rest`	`path`	字符串	❌ 否	`/{entity-name}`
`entities.{entity-name}.rest`	`methods`	字符串数组	❌ 否*	`POST`

* methods 属性仅用于 stored-procedure 端点。

注意： 此功能为数据墙DBW 2.0 预览版。

格式

json

{
  "entities": {
    "{entity-name}": {
      "rest": {
        "enabled": <true> (default) | <false>,
        "path": <string; default: "{entity-name}">
      }
    }
  }
}

Description（entity-name 实体）

父级	属性	类型	必需	默认值
`entities.{entity-name}`	`description`	字符串	❌ 否	无

实体的可选人类可读描述。此值在生成的 API 文档和 GraphQL 架构中作为注释显示。

注意： 此功能为数据墙DBW 2.0 预览版。

格式

json

{
  "entities": {
    "{entity-name}": {
      "description": "<string>"
    }
  }
}

示例

json

{
  "entities": {
    "Book": {
      "description": "Represents a book in the catalog with title, author, and pricing information.",
      "source": {
        "object": "dbo.books",
        "type": "table"
      }
    }
  }
}

Fields（entity-name 实体）

父级	属性	类型	必需	默认值
`entities.{entity-name}`	`fields`	数组	❌ 否	无

定义单个数据库字段的元数据，包括别名、描述和主键指定。fields 数组通过单一统一结构替代了 mappings（通过 alias 属性）和 source.key-fields（通过 primary-key 属性）。

注意： 此功能为数据墙DBW 2.0 预览版。

嵌套属性

父级	属性	类型	必需	默认值
`entities.{entity-name}.fields[]`	`name`	字符串	✔️ 是	无
`entities.{entity-name}.fields[]`	`alias`	字符串	❌ 否	无
`entities.{entity-name}.fields[]`	`description`	字符串	❌ 否	无
`entities.{entity-name}.fields[]`	`primary-key`	布尔值	❌ 否	`false`

格式

json

{
  "entities": {
    "{entity-name}": {
      "fields": [
        {
          "name": "<database-field-name>",
          "alias": "<api-exposed-name>",
          "description": "<string>",
          "primary-key": <boolean>
        }
      ]
    }
  }
}

示例

json

{
  "entities": {
    "Book": {
      "source": {
        "object": "dbo.books",
        "type": "table"
      },
      "fields": [
        {
          "name": "id",
          "description": "Unique book identifier",
          "primary-key": true
        },
        {
          "name": "sku_title",
          "alias": "title",
          "description": "The display title of the book"
        },
        {
          "name": "sku_status",
          "alias": "status"
        }
      ]
    }
  }
}

在此示例中，id 被指定为主键（替代了 source.key-fields 的需求），而 sku_title 和 sku_status 被别名为 title 和 status（替代了 mappings 的需求）。

重要： 架构强制要求 fields 不能与 mappings 或 source.key-fields 在同一实体上共存。请迁移到 fields 并删除已弃用的属性。

Mappings（entity-name 实体）

警告：mappings 属性在数据墙DBW 2.0 中已弃用。请改用 fields 数组配合 alias 属性。架构强制要求 fields 和 mappings 不能在同一实体上共存。

父级	属性	类型	必需	默认值
`entities.{entity-name}`	`mappings`	对象	❌ 否	无

为数据库对象字段启用自定义别名或公开名称。

重要： 对于启用了 GraphQL 的实体，配置的公开名称必须满足 GraphQL 名称要求。

格式

json

{
  "entities": {
    "{entity-name}": {
      "mappings": {
        "<field-1-name>": "<field-1-alias>",
        "<field-2-name>": "<field-2-alias>",
        "<field-3-name>": "<field-3-alias>"
      }
    }
  }
}

示例

数据库表

SQL

CREATE TABLE Books
(
  id INT,
  sku_title VARCHAR(50),
  sku_status VARCHAR(50),
)

配置

json

{
  "entities": {
    "Books": {
      ...
      "mappings": {
        "sku_title": "title",
        "sku_status": "status"
      }
    }
  }
}

Cache（entity-name 实体）

父级	属性	类型	必需	默认值
`entities.{entity-name}`	`cache`	对象	❌ 否	无

为实体启用和配置缓存。

嵌套属性

父级	属性	类型	必需	默认值
`entities.{entity-name}.cache`	`enabled`	布尔值	❌ 否	False
`entities.{entity-name}.cache`	`ttl-seconds`	整数	❌ 否	-
`entities.{entity-name}.cache`	`level`	枚举（`L1` \| `L1L2`）	❌ 否	`L1L2`

格式

json

{
  "entities": {
    "{entity-name}": {
      "cache": {
        "enabled": <true> (default) | <false>,
        "ttl-seconds": <integer; default: 5>,
        "level": <"L1" | "L1L2"> (default: "L1L2")
      }
    }
  }
}

level 属性控制使用哪些缓存层：

值	描述
`L1`	仅内存缓存。最快，但不在实例间共享。
`L1L2`	内存缓存加分布式（Redis）缓存。在扩展实例间共享。默认。

注意： 此功能为数据墙DBW 2.0 预览版。

注意： 未指定时，ttl-seconds 继承 runtime.cache 下设置的全局值。

示例

json

{
  "entities": {
    "Author": {
      "cache": {
        "enabled": true,
        "ttl-seconds": 30,
        "level": "L1"
      }
    }
  }
}

Relationships（entity-name 实体）

父级	属性	类型	必需	默认值
`entities.{entity-name}`	`relationships`	对象	❌ 否	无

配置 GraphQL 实体与其他公开实体的关系。更多信息请参阅数据墙DBW 关系分解。

注意： 每个关系的 relationship-name 在该实体的所有关系中必须唯一。

嵌套属性

这些属性根据关系基数以不同组合使用。

父级	属性	类型	必需	默认值
`entities.{entity-name}.relationships`	`cardinality`	字符串	✔️ 是	无
`entities.{entity-name}.relationships`	`target.entity`	字符串	✔️ 是	无
`entities.{entity-name}.relationships`	`target.fields`	字符串数组	❌ 否	无
`entities.{entity-name}.relationships`	`source.fields`	字符串数组	❌ 否	无
`entities.{entity-name}.relationships`	`linking.object`	字符串	❌ 否	无
`entities.{entity-name}.relationships`	`linking.source.fields`	字符串数组	❌ 否	无
`entities.{entity-name}.relationships`	`linking.target.fields`	字符串数组	❌ 否	无

格式

json

{
  "entities": {
    "{entity-name}": {
      "relationships": {
        "<relationship-name>": {
          "cardinality": "one" | "many",
          "target.entity": "<string>",
          "source.fields": ["<string>"],
          "target.fields": ["<string>"],
          "linking.object": "<string>",
          "linking.source.fields": ["<string>"],
          "linking.target.fields": ["<string>"]
        }
      }
    }
  }
}

关系	基数	示例
一对多	`many`	一个分类实体可以关联多个待办事项实体
多对一	`one`	多个待办事项实体可以关联一个分类实体
多对多	`many`	一个待办事项实体可以关联多个用户实体，一个用户实体可以关联多个待办事项实体

示例：一对一基数

每个 Profile 恰好关联一个 User，每个 User 恰好关联一个 Profile。

json

{
  "entities": {
    "User": {
      "relationships": {
        "user_profile": {
          "cardinality": "one",
          "target.entity": "Profile",
          "source.fields": [ "id" ],
          "target.fields": [ "user_id" ]
        }
      }
    },
    "Profile": {
      ...
    }
  }
}

GraphQL 架构

graphql

type User
{
  id: Int!
  ...
  profile: Profile
}

命令行

bash

dab update User \
  --relationship profile \
  --target.entity Profile \
  --cardinality one \
  --relationship.fields "id:user_id"

示例：一对多基数

一个 Category 可以有一个或多个关联的 Book 实体，而每个 Book 可以有一个关联的 Category。

json

{
  "entities": {
    "Book": {
      ...
    },
    "Category": {
      "relationships": {
        "category_books": {
          "cardinality": "many",
          "target.entity": "Book",
          "source.fields": [ "id" ],
          "target.fields": [ "category_id" ]
        }
      }
    }
  }
}

GraphQL 架构

graphql

type Category
{
  id: Int!
  ...
  books: [BookConnection]!
}

命令行

bash

dab update Category \
  --relationship category_books \
  --target.entity Book \
  --cardinality many \
  --relationship.fields "id:category_id"

示例：多对一基数

多个 Book 实体可以有一个关联的 Category，而 Category 可以有一个或多个关联的 Book 条目。

json

{
  "entities": {
    "Book": {
      "relationships": {
        "books_category": {
          "cardinality": "one",
          "target.entity": "Category",
          "source.fields": [ "category_id" ],
          "target.fields": [ "id" ]
        }
      },
      "Category": {
        ...
      }
    }
  }
}

GraphQL 架构

graphql

type Book
{
  id: Int!
  ...
  category: Category
}

命令行

bash

dab update Book \
  --relationship books_category \
  --target.entity "Category" \
  --cardinality one \
  --relationship.fields "category_id:id"

示例：多对多基数

多个 Book 实体可以有多个关联的 Author 实体，而多个 Author 实体可以有多个关联的 Book 条目。

注意： 此关系通过第三个表 dbo.books_authors 实现，我们称之为联接对象。

json

{
  "entities": {
    "Book": {
      "relationships": {
        ...,
        "books_authors": {
          "cardinality": "many",
          "target.entity": "Author",
          "source.fields": [ "id" ],
          "target.fields": [ "id" ],
          "linking.object": "dbo.books_authors",
          "linking.source.fields": [ "book_id" ],
          "linking.target.fields": [ "author_id" ]
        }
      },
      "Category": {
        ...
      },
      "Author": {
        ...
      }
    }
  }
}

GraphQL 架构

graphql

type Book
{
  id: Int!
  ...
  authors: [AuthorConnection]!
}

type Author
{
  id: Int!
  ...
  books: [BookConnection]!
}

命令行

bash

dab update Book \
  --relationship books_authors \
  --target.entity "Author" \
  --cardinality many \
  --relationship.fields "id:id" \
  --linking.object "dbo.books_authors" \
  --linking.source.fields "book_id" \
  --linking.target.fields "author_id"

Health（entity-name 实体）

父级	属性	类型	必需	默认值
`entities.{entity-name}`	`health`	对象	❌ 否	无

为实体启用和配置健康检查。

嵌套属性

父级	属性	类型	必需	默认值
`entities.{entity-name}.health`	`enabled`	布尔值	❌ 否	`true`
`entities.{entity-name}.health`	`first`	整数	❌ 否	`100`
`entities.{entity-name}.health`	`threshold-ms`	整数	❌ 否	`1000`

示例

json

{
  "entities": {
    "Book": {
      "health": {
        "enabled": true,
        "first": 3,
        "threshold-ms": 500
      }
    }
  }
}

注意：first 值必须小于或等于 runtime.pagination.max-page-size 设置。较小的值有助于健康检查更快完成。

重要： 存储过程自动从实体健康检查中排除，因为它们需要参数且可能不是确定性的。

MCP（entity-name 实体）

父级	属性	类型	必需	默认值
`entities.{entity-name}`	`mcp`	对象	❌ 否	省略时默认启用

控制实体的 MCP 参与。当全局启用 MCP 时，实体默认参与。使用此属性可选择退出或为存储过程实体启用自定义 MCP 工具。

注意： 此功能为数据墙DBW 2.0 预览版。

对象格式

使用对象格式进行细粒度控制：

父级	属性	类型	必需	默认值
`entities.{entity-name}.mcp`	`dml-tools`	布尔值	❌ 否	`true`
`entities.{entity-name}.mcp`	`custom-tool`	布尔值	❌ 否	`false`

json

{
  "entities": {
    "Book": {
      "mcp": {
        "dml-tools": true
      }
    }
  }
}

Custom tool（仅限存储过程）

对于存储过程实体，将 custom-tool 设置为 true 可将过程注册为命名 MCP 工具：

json

{
  "entities": {
    "GetBookById": {
      "source": {
        "type": "stored-procedure",
        "object": "dbo.get_book_by_id"
      },
      "mcp": {
        "custom-tool": true
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["execute"]
        }
      ]
    }
  }
}

重要：custom-tool 属性仅对存储过程实体有效。在表或视图实体上设置会导致配置错误。

CLI 示例

bash

dab add Book --source books --permissions "anonymous:*" --mcp.dml-tools true

bash

dab add GetBookById --source dbo.get_book_by_id --source.type stored-procedure --permissions "anonymous:execute" --mcp.custom-tool true

Entities ​

Health ​

Description ​

Fields ​

Source ​

REST ​

GraphQL ​

Permissions ​

Relationships ​

Cache ​

MCP ​

格式概览 ​

Source（entity-name 实体） ​

嵌套属性 ​

格式 ​

Parameters 数组格式 ​

示例（数组格式 - 推荐） ​

Permissions（entity-name 实体） ​

格式 ​

示例 ​

角色继承 ​

示例 ​

Actions（字符串数组 Permissions entity-name 实体） ​

格式 ​

示例 ​

替代格式（仅字符串，当 type=stored-procedure） ​

示例 ​

Actions（对象数组 Permissions entity-name 实体） ​

嵌套属性 ​

格式 ​

示例 ​

策略说明 ​

Type（GraphQL entity-name 实体） ​

格式 ​

嵌套属性 ​

示例 ​

Operation（GraphQL entity-name 实体） ​

格式 ​

示例：operation ​

Enabled（GraphQL entity-name 实体） ​

格式 ​

REST（entity-name 实体） ​

格式 ​

Description（entity-name 实体） ​

格式 ​

示例 ​

Fields（entity-name 实体） ​

嵌套属性 ​

格式 ​

示例 ​

Mappings（entity-name 实体） ​

格式 ​

示例 ​

Cache（entity-name 实体） ​

嵌套属性 ​

格式 ​

示例 ​

Relationships（entity-name 实体） ​

嵌套属性 ​

格式 ​

示例：一对一基数 ​

示例：一对多基数 ​

示例：多对一基数 ​

示例：多对多基数 ​

Health（entity-name 实体） ​

嵌套属性 ​

示例 ​

MCP（entity-name 实体） ​

对象格式 ​

Custom tool（仅限存储过程） ​

CLI 示例 ​

Entities

Health

Description

Fields

Source

REST

GraphQL

Permissions

Relationships

Cache

MCP

格式概览

Source（entity-name 实体）

嵌套属性

格式

Parameters 数组格式

示例（数组格式 - 推荐）

Permissions（entity-name 实体）

格式

示例

角色继承

示例

Actions（字符串数组 Permissions entity-name 实体）

格式

示例

替代格式（仅字符串，当 `type=stored-procedure`）

示例

Actions（对象数组 Permissions entity-name 实体）

嵌套属性

格式

示例

策略说明

Type（GraphQL entity-name 实体）

格式

嵌套属性

示例

Operation（GraphQL entity-name 实体）

格式

示例：operation

Enabled（GraphQL entity-name 实体）

格式

REST（entity-name 实体）

格式

Description（entity-name 实体）

格式

示例

Fields（entity-name 实体）

嵌套属性

格式

示例

Mappings（entity-name 实体）

格式

示例

Cache（entity-name 实体）

嵌套属性

格式

示例

Relationships（entity-name 实体）

嵌套属性

格式

示例：一对一基数

示例：一对多基数

示例：多对一基数

示例：多对多基数

Health（entity-name 实体）

嵌套属性

示例

MCP（entity-name 实体）

对象格式

Custom tool（仅限存储过程）

CLI 示例