数据模型与项目元素

项目中的表经常共享列名，例如 Period、Org、Account。项目元素为整个项目一次性描述其中一个列名。之后，每个包含该名称的列的表都会显示相同的说明、掩码和维度，无需在几十张表上重复输入同一条备注。

项目主页上的数据模型页面列出项目的元素，显示每个元素由哪些表共享，并标出表之间不一致的地方。

元素包含的内容

设置	作用
名称	元素所描述的列名，与各列中的写法完全一致。
说明	该列保存的内容。没有自己备注的列会显示此说明。
类型	项目期望此列使用的数据类型。仅作检查，不会应用。请参阅类型冲突。
掩码	数字掩码。没有自己掩码的列会使用此掩码。
维度	该列的值所来自的维度。没有自己维度的列会使用此维度。
别名	含义相同的其他列名。

列如何关联到元素

当列 ID 与元素的名称或其某个别名相同时，该列即绑定到该元素。匹配是精确的：period 和 Period 是不同的名称，因此如果两者都要匹配，请将 period 添加为 Period 的别名。

添加或删除元素后，所有匹配的列都会随之变化。

列从元素获得什么

已绑定的列在自身值为空时，会采用元素的说明、掩码和维度。在列上自行设置的值始终优先。元素绝不会更改表上存储的内容：删除元素后，每一列都会恢复为原来的内容。

类型不会从元素获取。

打开数据模型页面

打开项目，然后在项目主页的导轨中选择数据模型。导轨上的徽章显示项目有多少个元素。也可以从列打开该页面：

在表资源管理器中，打开列属性并选择一列。元素行会显示该列的元素；如果该列没有元素且您可以编辑项目，则显示将其设为元素。单击它即可在数据模型页面中打开该元素，或打开一个以该列自身说明、掩码和维度为起点的新元素。
在维度的使用位置列表中，名为项目元素的行会打开数据模型页面。

能打开项目的每个人都可以查看该页面。创建、更改或删除元素需要项目的写入权限，且项目不能处于锁定状态。否则页面会显示“您可以在此查看数据模型，但无法更改。”

创建元素

在数据模型页面上，单击新建元素。
输入名称。根据需要填写说明、类型、掩码和维度。将类型保留为任意类型表示接受任何类型。
在别名中输入含义相同的其他列名，每行一个。
单击保存。

元素不能使用其他元素已有的名称或别名。要更改元素，请单击其旁边的铅笔图标（编辑元素）。如果重命名元素，旧名称会保留为别名，因此其列仍然属于该元素。

要删除元素，请打开它并单击删除，然后用删除元素确认。确认框会显示有多少张表绑定到它。这些表上存储的内容不会有任何更改。

建议的元素

在建议下，页面会列出值得转为元素的列名：

尚不是元素或别名、出现在两张或更多表中、且该列的类型可以作为连接键（未知类型也算）的名称，显示为“name 位于 n个表”。单击创建元素即可创建它。
忽略大小写和下划线后与某个元素的名称或别名相匹配的名称，即使只出现在一张表中，也显示为“name 看起来像 element（n个表）”。单击添加别名即可将其列绑定到该元素。

读取数据模型

画布上方的图和矩阵开关以两种方式显示相同的表和元素。

图。每个元素是一个中心节点，每张表是一张卡片，与其具有对应列的元素相连。线上的 1 表示该列是该表的唯一键。具有多列组合键的表不会标出。页面打开时显示一个元素及其表。单击元素可聚焦到该元素，单击表可聚焦到该表，双击表可打开它。隐藏元素旁边的标签用于隐藏或显示不想在图中出现的元素。
矩阵。 每张表一行，每个元素一列。使用按表名筛选缩小行的范围。

类型冲突

如果某张表的列类型与其余表不同，会在元素下被标出：“column 在 table 中为 type，与其他表不同。”类型按族比较，因此整数和小数不冲突。如果元素设置了类型，则其他列与其所属的族比较；如果没有，则与大多数列使用的族比较，两个族并列时使用按字母顺序排在前面的那个。冲突只是警告，不会更改任何内容。

无法读取的表会被排除，并在页面上计数，而不会使页面停止工作。

在哪里看到元素

元素显示为带有元素名称的标签：

表资源管理器。 列列表中有一个标记列，其中显示该标签，位于维度和行访问标签旁边。将鼠标悬停在标签上可查看元素、其说明及其维度。
列属性。 元素行会打开该元素。当说明、掩码或维度为空时，该字段会以提示形式显示“来自元素 name：value”。该提示不会随列保存。
步骤的 Data Mapping 选项卡。 属于某个元素的源列和目标列会在列名后显示其标签。

通过 REST API 和 MCP 使用元素

REST API 通过 /rest/v1/analyze/projects/{project_id}/elements 读取和更改元素：

请求	作用
`GET`	返回 `elements` 和 `index`，后者将每个已绑定的列名映射到其元素的名称。
`PUT`	根据 `name`、`memo`、`dtype`、`mask`、`dimension` 和 `aliases` 创建或替换元素。添加 `rename_from` 可重命名元素。
带 `?name=` 的 `DELETE`	删除指定名称的元素。
`GET` `/graph`	返回数据模型页面显示的内容：每个元素及其表数量和类型冲突、每张表的已绑定列，以及建议。

表元数据返回的是每列上存储的值，而不是它从元素获得的值。要查明某列从哪个元素获取值，请在 GET elements 返回的 index 中查找其名称。

通过 MCP 连接的助手使用 element_find、element_upsert 和 element_delete。其表描述会显示每列的备注，并在该列没有备注的地方填入元素的值。