nocobase-data-modeling

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Goal

目标

Use NocoBase MCP tools to inspect and change collections, fields, relations, and view-backed schemas.

使用NocoBase MCP工具查看和修改集合、字段、关系以及基于视图的架构。

Prerequisite

前提条件

NocoBase MCP must already be authenticated before running modeling actions.
If MCP tools return authentication errors such as
```
Auth required
```
, do not try to sign in automatically through ad hoc requests.
Instead, stop and ask the user to complete MCP authentication or refresh the MCP connection, then continue with the modeling workflow.

Useful references:

MCP setup and token configuration:
```
nocobase-mcp-setup
```
Data modeling overview: https://docs.nocobase.com/data-sources/data-modeling
Collection overview and collection types: https://docs.nocobase.com/data-sources/data-modeling/collection
Collection options reference: https://docs.nocobase.com/plugin-development/server/collection-options
Collection field overview: https://docs.nocobase.com/data-sources/data-modeling/collection-fields

Canonical create payload examples by collection type:

```
references/collection-types/general.md
```
```
references/collection-types/file.md
```
```
references/collection-types/tree.md
```

在执行建模操作前，必须已完成NocoBase MCP的身份验证。
如果MCP工具返回
```
Auth required
```
等身份验证错误，请勿通过临时请求自动尝试登录。
应停止操作并告知用户完成MCP身份验证或刷新MCP连接，之后再继续建模工作流。

实用参考资料：

MCP设置与令牌配置：
```
nocobase-mcp-setup
```
数据建模概述：https://docs.nocobase.com/data-sources/data-modeling
集合概述与集合类型：https://docs.nocobase.com/data-sources/data-modeling/collection
集合选项参考：https://docs.nocobase.com/plugin-development/server/collection-options
集合字段概述：https://docs.nocobase.com/data-sources/data-modeling/collection-fields

按集合类型划分的标准创建负载示例：

```
references/collection-types/general.md
```
```
references/collection-types/file.md
```
```
references/collection-types/tree.md
```

Preferred order

优先顺序

Inspect first.
- Prefer
```
collections:listMeta
```
  when available because it includes loaded collection options and field definitions.
- Otherwise use
```
collections:list
```
  ,
```
collections:get
```
  , and
```
collections/{collectionName}/fields:list
```
  .
Make the smallest safe change.
- Create collections first, then add or edit fields incrementally.
Use bulk sync only when appropriate.
- Use
```
collections:setFields
```
  only when replacing the full field set is intentional.
Verify after each modeling step.
- Re-read the collection and field metadata.
- Check collection titles on the collection itself, but check field labels in
```
uiSchema.title
```
  .
- For relation fields, verify the declared field and any generated foreign key or reverse field.

先查看。
- 优先使用
```
collections:listMeta
```
  （如果可用），因为它包含已加载的集合选项和字段定义。
- 否则使用
```
collections:list
```
  、
```
collections:get
```
  和
```
collections/{collectionName}/fields:list
```
  。
做出最小的安全变更。
- 先创建集合，再逐步添加或编辑字段。
仅在合适时使用批量同步。
- 仅当有意替换完整字段集时，才使用
```
collections:setFields
```
  。
每个建模步骤后进行验证。
- 重新读取集合和字段元数据。
- 在集合本身查看集合标题，但在
```
uiSchema.title
```
  中查看字段标签。
- 对于关系字段，验证声明的字段以及任何生成的外键或反向字段。

Operational guidance

操作指南

Choose the collection type before designing fields. Do not default to
```
general
```
until you have checked whether the business object is actually hierarchical, calendar-oriented, file-oriented, SQL-backed, or view-backed.
Common collection-type selection rules:
- ```
general
```
  : ordinary transactional or master-data tables with custom business fields and relations.
- ```
tree
```
  : hierarchical data such as departments, categories, region trees, or any structure where parent/child semantics are core to the model.
- ```
calendar
```
  : date-centric business objects that are primarily scheduled or displayed on calendars.
- ```
file
```
  : attachment, upload, document, image, scan, or archive records where the file itself is a first-class object.
- ```
sql
```
  : SQL-defined collections whose schema/query logic is intentionally driven by SQL rather than ordinary field-by-field modeling.
- ```
view
```
  : database-view-backed read models or reporting/query projections that should sync from an existing database view.
For attachments, scans, certificates files, photos, contracts, and similar file-centric records, prefer a
```
file
```
collection instead of modeling them as a
```
general
```
collection unless the user explicitly wants to decouple metadata from the file storage object.
A
```
general
```
collection with
```
fileName
```
,
```
fileUrl
```
, or
```
storageName
```
fields can be acceptable only when the design intentionally stores external file metadata rather than using NocoBase's file collection semantics. Treat this as an explicit design choice, not the default.
A reliable file-collection create shape should mirror the real collection-manager request body instead of assuming
```
template: "file"
```
will always inject every expected field automatically.
Preset fields such as
```
id
```
,
```
createdAt
```
,
```
createdBy
```
,
```
updatedAt
```
, and
```
updatedBy
```
should follow the same request shape used by the real collection manager flow when the task is meant to validate realistic modeling or ACL behavior.
Unless the user explicitly asks for a different primary-key strategy or the table truly has unusual requirements, you must create
```
id
```
explicitly as a preset field instead of relying on implicit/default id generation.
Treat explicit preset
```
id
```
as the default rule, not an optional improvement.
For ordinary business tables,
```
createdAt
```
,
```
createdBy
```
,
```
updatedAt
```
, and
```
updatedBy
```
are usually needed and should normally be created explicitly as preset fields too.
A reliable general create shape for such tables is:
- ```
template: "general"
```
- ```
logging: true
```
  when record history matters
- ```
autoGenId: false
```
- explicit preset fields in
```
fields
```
  :
```
id
```
  ,
```
createdAt
```
  ,
```
createdBy
```
  ,
```
updatedAt
```
  ,
```
updatedBy
```
Append business fields after these preset fields unless the user explicitly wants a different layout.
When the task is validating realistic file modeling, start from this file-collection baseline and append business-specific relation or classification fields after the built-in file fields.
Keep large canonical payloads in the
```
references/collection-types/
```
folder.
```
SKILL.md
```
should explain selection and rules; the reference files should hold reusable request bodies for each collection type.
For
```
id
```
, follow the actual request shape used by collection manager flows, including interfaces such as
```
snowflakeId
```
,
```
uuid
```
, or
```
nanoid
```
.

collections:create

collections:update

, and

collections/{collectionName}/fields:update

use direct request bodies. Do not add an extra

values

wrapper.

If a collection uses a custom primary key strategy, disable
```
autoGenId
```
, create the primary key field explicitly, and verify that the resulting collection metadata has the expected
```
filterTargetKey
```
.
Do not treat collection-level convenience flags as a substitute for the real preset-field payload when the goal is to mirror an actual business collection definition.
If the created collection does not expose the expected explicit preset
```
id
```
field after re-reading metadata, treat that as a modeling failure and correct it before continuing with downstream ACL or workflow setup.
Prefer explicit relation payloads when relation behavior matters. Generated defaults are fine for ad hoc modeling, but they are harder to verify and reuse in automation.
If reverse behavior matters, pass
```
reverseField
```
explicitly instead of assuming the server will infer the right alias or UI schema.
On
```
collections:*
```
,
```
filterByTk
```
usually means collection name. On
```
collections/{collectionName}/fields:*
```
, it usually means the field name inside that collection. If names are unstable, use
```
filter
```
with the field
```
key
```
.
For local option fields such as
```
select
```
,
```
multipleSelect
```
,
```
radioGroup
```
, and
```
checkboxGroup
```
, follow the collection manager request shape and put structured options in
```
uiSchema.enum
```
, usually with items like
```
{ value, label }
```
.
If record pickers or workflow selectors show raw IDs instead of readable names, check the collection
```
titleField
```
.

Common minimal shapes:

Collection:
```
{ name, title, fields }
```
Field update:
```
{ description, uiSchema, enum, ... }
```

Local select field:

{ name, type: "string", interface: "select", uiSchema: { "x-component": "Select", enum: [{ value, label }] } }

Use
```
dbViews:list
```
or
```
dbViews:get
```
before touching a view-backed collection. Treat
```
collections:setFields
```
as replacement, not patching.
Use collection-type-specific docs before modeling non-general collections such as inheritance, tree, calendar, SQL, file, or view collections.
For inheritance collections, keep shared fields on the parent and only child-specific fields on derived collections. Re-check query scope and selector behavior after changes because inheritance increases query complexity.
For tree collections, treat the hierarchy as first-class structure rather than emulating it with ad hoc self-relations in a general collection.
For file collections, model the uploaded file as the primary record. Add business relations around that file record instead of replacing the file collection with a plain general table unless the business requirement clearly calls for metadata-only storage.

在设计字段前先选择集合类型。在确认业务对象是否为层级、日历导向、文件导向、SQL驱动或基于视图的结构前，请勿默认使用
```
general
```
类型。
常见集合类型选择规则：
- ```
general
```
  ：包含自定义业务字段和关系的普通事务或主数据表。
- ```
tree
```
  ：层级数据，如部门、分类、区域树等，这类结构的核心语义是父/子关系。
- ```
calendar
```
  ：以日期为中心的业务对象，主要用于日程安排或在日历上展示。
- ```
file
```
  ：附件、上传文件、文档、图片、扫描件或归档记录，这类记录中文件本身是一等对象。
- ```
sql
```
  ：由SQL定义的集合，其架构/查询逻辑由SQL驱动，而非普通的逐字段建模。
- ```
view
```
  ：基于数据库视图的只读模型或报表/查询投影，需与现有数据库视图同步。
对于附件、扫描件、证书、照片、合同等以文件为核心的记录，优先使用
```
file
```
集合，而非
```
general
```
集合，除非用户明确希望将元数据与文件存储对象解耦。
仅当设计意图是存储外部文件元数据而非使用NocoBase的文件集合语义时，包含
```
fileName
```
、
```
fileUrl
```
或
```
storageName
```
字段的
```
general
```
集合才是可接受的。请将此视为明确的设计选择，而非默认方案。
可靠的文件集合创建结构应镜像真实集合管理器的请求体，而非假设
```
template: "file"
```
会自动注入所有预期字段。
当任务旨在验证真实建模或ACL行为时，
```
id
```
、
```
createdAt
```
、
```
createdBy
```
、
```
updatedAt
```
和
```
updatedBy
```
等预设字段应遵循真实集合管理器流程使用的请求结构。
除非用户明确要求不同的主键策略，或表确实有特殊需求，否则必须显式创建
```
id
```
作为预设字段，而非依赖隐式/默认的ID生成。
将显式预设
```
id
```
视为默认规则，而非可选优化。
对于普通业务表，通常需要
```
createdAt
```
、
```
createdBy
```
、
```
updatedAt
```
和
```
updatedBy
```
，且通常也应显式创建为预设字段。
此类表的可靠通用创建结构为：
- ```
template: "general"
```
- 当记录历史重要时设置
```
logging: true
```
- ```
autoGenId: false
```
- 在
```
fields
```
  中显式设置预设字段：
```
id
```
  、
```
createdAt
```
  、
```
createdBy
```
  、
```
updatedAt
```
  、
```
updatedBy
```
除非用户明确要求不同的布局，否则在这些预设字段后添加业务字段。
当任务旨在验证真实文件建模时，从该文件集合基线开始，在内置文件字段后添加业务特定的关系或分类字段。
将大型标准负载保存在
```
references/collection-types/
```
文件夹中。
```
SKILL.md
```
应解释选择规则，参考文件应包含各集合类型的可复用请求体。
对于
```
id
```
字段，遵循集合管理器流程使用的实际请求结构，包括
```
snowflakeId
```
、
```
uuid
```
或
```
nanoid
```
等接口。

collections:create

、

collections:update

和

collections/{collectionName}/fields:update

使用直接请求体，请勿添加额外的

values

包装器。

如果集合使用自定义主键策略，请禁用
```
autoGenId
```
，显式创建主键字段，并验证生成的集合元数据是否具有预期的
```
filterTargetKey
```
。
当目标是镜像实际业务集合定义时，请勿将集合级别的便捷标志视为真实预设字段负载的替代品。
如果重新读取元数据后，创建的集合未暴露预期的显式预设
```
id
```
字段，请将其视为建模失败，并在继续下游ACL或工作流设置前修正该问题。
当关系行为重要时，优先使用显式关系负载。生成的默认值适用于临时建模，但在自动化中更难验证和复用。
如果反向行为重要，请显式传递
```
reverseField
```
，而非假设服务器会推断正确的别名或UI架构。
在
```
collections:*
```
操作中，
```
filterByTk
```
通常指集合名称。在
```
collections/{collectionName}/fields:*
```
操作中，它通常指该集合内的字段名称。如果名称不稳定，请使用包含字段
```
key
```
的
```
filter
```
参数。
对于
```
select
```
、
```
multipleSelect
```
、
```
radioGroup
```
和
```
checkboxGroup
```
等本地选项字段，遵循集合管理器的请求结构，将结构化选项放在
```
uiSchema.enum
```
中，通常格式为
```
{ value, label }
```
。
如果记录选择器或工作流选择器显示原始ID而非可读名称，请检查集合的
```
titleField
```
。

常见最小结构：

集合：
```
{ name, title, fields }
```
字段更新：
```
{ description, uiSchema, enum, ... }
```

本地选择字段：

{ name, type: "string", interface: "select", uiSchema: { "x-component": "Select", enum: [{ value, label }] } }

在处理基于视图的集合前，使用
```
dbViews:list
```
或
```
dbViews:get
```
。请将
```
collections:setFields
```
视为替换操作，而非补丁操作。
在建模非通用集合（如继承、tree、calendar、SQL、file或view集合）前，参考特定集合类型的文档。
对于继承集合，将共享字段放在父集合中，仅将子集合特有的字段放在派生集合中。修改后重新检查查询范围和选择器行为，因为继承会增加查询复杂度。
对于tree集合，将层级视为一等结构，而非在通用集合中通过临时自关系模拟。
对于file集合，以上传文件作为主记录。在该文件记录周围添加业务关系，而非用普通通用表替换file集合，除非业务需求明确要求仅存储元数据。

Common pitfalls

常见陷阱

Do not treat MCP authentication failures as normal API failures. Resolve authentication first.
Do not use
```
collections:setFields
```
for small edits on ordinary collections; it can remove fields omitted from the payload.
When changing relation fields, re-check the target collection because foreign keys and reverse fields may be created or removed as side effects.
Deleting a relation field may leave reverse fields or foreign-key fields behind. Re-read both collections and clean up leftovers explicitly if the model should be fully removed.

请勿将MCP身份验证失败视为普通API失败。请先解决身份验证问题。
请勿对普通集合使用
```
collections:setFields
```
进行小修改；该操作会移除负载中未包含的字段。
修改关系字段时，请重新检查目标集合，因为外键和反向字段可能会作为副作用被创建或删除。
删除关系字段后，可能会留下反向字段或外键字段。如果需要完全移除模型，请重新读取两个集合并显式清理残留内容。

Verification checklist

验证清单

Collection exists and has expected options.
The collection uses an explicit preset
```
id
```
field unless the user explicitly requested a different primary-key strategy.
Preset audit fields are added where the business model actually needs them, and the primary-key strategy matches the intended creation flow.
```
filterTargetKey
```
and
```
titleField
```
match how the collection should be referenced in MCP queries and selectors.
Field exists with expected
```
type
```
,
```
interface
```
, and
```
uiSchema.title
```
.
Local option fields expose the expected labels and values in
```
uiSchema.enum
```
, not only a bare string array.
Relation field created the expected
```
foreignKey
```
,
```
through
```
, or
```
reverseField
```
.
View collections still match
```
dbViews:get
```
output after synchronization.

集合已存在且具有预期选项。
除非用户明确要求不同的主键策略，否则集合使用显式预设的
```
id
```
字段。
预设审计字段已添加到业务模型需要的位置，且主键策略与预期的创建流程匹配。
```
filterTargetKey
```
和
```
titleField
```
与MCP查询和选择器中引用集合的方式一致。
字段已存在且具有预期的
```
type
```
、
```
interface
```
和
```
uiSchema.title
```
。
本地选项字段在
```
uiSchema.enum
```
中暴露了预期的标签和值，而非仅为纯字符串数组。
关系字段已创建预期的
```
foreignKey
```
、
```
through
```
或
```
reverseField
```
。
同步后，视图集合仍与
```
dbViews:get
```
的输出一致。