> For the complete documentation index, see [llms.txt](https://docs.zongsoft.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zongsoft.com/framework/data/concepts.md).
# 对象关系与数据访问
理解对象关系映射、实体、导航、数据形状、访问器与数据库驱动的协作。
业务代码操作订单、客户和明细对象；关系数据库保存表、行、列和关联键。对象关系映射（ORM）负责连接这两种表达。[Zongsoft.Data](https://github.com/Zongsoft/framework/tree/main/Zongsoft.Data) 使用显式映射和数据模式，让业务描述“访问哪些实体、哪些字段和关系”，再由引擎与驱动执行。
## 四个层次
**模型**是代码中的对象类型，可以是普通属性类，也可以采用框架支持的模型机制。**映射**描述实体与表、属性与列、导航与关联键。**数据模式**描述某一次操作的成员范围。**驱动**将表达转换为目标数据库支持的命令。
以订单详情为例：映射声明订单的 `CustomerId` 关联客户的 `CustomerId`；一次详情查询使用 `OrderId, Amount, Customer{Name}, Lines:20{ProductId, Quantity}`；另一次列表查询只需要 `OrderId, Amount`。同一份映射可以支持不同形状，无需为每次查询重写关系。
## 实体与名称
映射中的 `container` 为实体和命令提供命名空间。例如 Discussions 映射中的 Discussions.Forum 是实体限定名，实体 alias 指向 Discussions\_Forum 物理表。访问器名、映射容器名和数据库名不是同一概念，即使项目常把它们命名为相同文本。
泛型查询需要根据模型定位实体；动态或跨模块场景可显式传实体限定名。先核对[映射](/framework/data/mapping.md)，再确认代码使用的模型和实体名称。
## 导航与关系基数
导航属性表达“沿关系访问另一个对象”。关系基数说明能关联多少对象：`?` 表示零或一个，`!` 表示必须有一个，`*` 表示集合。它们影响连接与对象装配方式，不能只根据 C# 属性名称猜测。
单值导航可通过连接读取，集合导航会形成独立的从查询，并在结果装配过程中填充。请求一个嵌套对象图不保证只执行一条 SQL；层次越深、集合越大，数据库往返和返回数据可能越多。应按页面实际需要选择字段与限量。
## 数据模式与数据库结构
这里的 Schema 指操作的数据形状，不是数据库建表脚本，也不是 GraphQL 服务端协议。它在语法上类似选择集，但有自己的解析规则。`.mapping` 则是稳定结构元数据，两者职责不同。
{% hint style="info" %}
💡 部署 `.mapping` 不会自动创建表、迁移数据库或灌入初始化数据。首次接入必须分别准备映射、连接、驱动和真实数据库结构；只验证装配时可使用[无表的常量查询](/framework/data/quickstart.md)。
{% endhint %}
## 条件与操作元
条件回答“哪些行参与操作”，操作元回答“表达式中的值如何计算”。例如 `Condition.Equal("OrderId", orderId)` 限定订单，`Operand.Field("Quantity") + 1` 表示数据库内的字段运算。
将条件值交给引擎绑定，有助于避免手工拼 SQL。字段名和可访问成员仍须由应用控制；参数化不等于自动实现字段权限或租户隔离。
## 访问器与数据服务
[访问器](/framework/data/data-access.md)提供通用数据操作。[数据服务](/framework/data/services.md)在其上组织模型相关的业务入口、可写能力、验证、授权与过滤。Web 控制器可以使用数据服务，而不必在每个端点重复定义相同的访问流程。
数据库事务处理同一事务范围内的提交与回滚，业务授权处理谁能操作哪些数据。这些职责不会因为引入 ORM 自动完成。特别是数据库写入与消息发送，不能仅用一个本地事务假定两者原子完成。
## 推荐学习顺序
先完成[首次查询](/framework/data/quickstart.md)，再学习[映射](/framework/data/mapping.md)和[数据模式](/framework/data/schema.md)，随后进入[查询](/framework/data/querying.md)、[写入](/framework/data/writing.md)、[事务](/framework/data/transactions.md)及[数据服务](/framework/data/services.md)。驱动差异集中见[驱动](/framework/data/drivers.md)。
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.zongsoft.com/framework/data/concepts.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.