> 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/documentation/en/framework/data.md).

# Data Engine

Design goals, capabilities, and starting points for the Zongsoft.Data data engine.

![Data Engine](https://1509929121-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVtPQeWxVwz4p7FTcxkG8%2Fuploads%2Fgit-blob-4bba74b4b746d0421774fe57bfbad6ef4524fa51%2Fzongsoft-data-cover.png?alt=media)

[`Zongsoft.Data`](https://github.com/Zongsoft/framework/tree/main/Zongsoft.Data) is an ORM data access framework with a GraphQL-like style. Data schemas, mapping files, condition expressions, and database drivers describe the structure of data access, supporting complex queries, navigation, filtering, paging, grouping, aggregation, and writes without hand-written SQL.

Its design separates data access into four stable layers instead of replacing SQL with another SQL-like string language:

* Model layer: Business code uses POCO types or anonymous objects.
* Metadata layer: `.mapping` file describes entities, fields, inheritance and navigation relationships.
* Access layer: `IDataAccess` exposes unified query, write, aggregation, import and execution interfaces.
* Driver layer: Each database driver converts unified expressions into corresponding database syntax and executes them.

Start with [Object Relationships and Data Access](/documentation/en/framework/data/concepts.md), then follow [Your First Query](/documentation/en/framework/data/quickstart.md) through the Discussions table setup, connection configuration, and forum query. For organizing business rules, see [Data Services](/documentation/en/framework/data/services.md).

## Features

* Strict POCO objects are supported.
* Support read/write separation.
* Support table inheritance related operations.
* Supports isolation of mapping files by business module.
* Use a data schema to describe query and write shapes.
* Provides multiple database drivers.

## Core Concepts

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref">Page</th></tr></thead><tbody><tr><td><strong>Data Schemas</strong></td><td>Describes the shape of the data queried or written.</td><td><a href="/documentation/en/framework/data/schema.md">Data Schemas</a></td></tr><tr><td><strong>Mapping Files</strong></td><td>Describe entities, tables, fields, and relationships.</td><td><a href="/documentation/en/framework/data/mapping.md">Mapping Files</a></td></tr><tr><td><strong>Connection Configuration</strong></td><td>Configure data sources, read/write separation and drivers.</td><td><a href="/documentation/en/framework/data/connections.md">Connection Configuration</a></td></tr><tr><td><strong>Data Access Interfaces</strong></td><td>Execute queries, writes, aggregations and commands.</td><td><a href="/documentation/en/framework/data/data-access.md">Data Access Interfaces</a></td></tr><tr><td><strong>Conditions and Operands</strong></td><td>Express filter conditions and field operations.</td><td><a href="/documentation/en/framework/data/conditions-and-operands.md">Conditions and Operands</a></td></tr><tr><td><strong>Queries and Navigation</strong></td><td>Read the object graph using `schema`, paging and sorting.</td><td><a href="/documentation/en/framework/data/querying.md">Queries and Navigation</a></td></tr><tr><td><strong>Write Operations</strong></td><td>Add, update, delete and upsert.</td><td><a href="/documentation/en/framework/data/writing.md">Write Operations</a></td></tr><tr><td><strong>Drivers</strong></td><td>Select, deploy and extend database drivers.</td><td><a href="/documentation/en/framework/data/drivers.md">Browse by Driver</a></td></tr></tbody></table>

## Choose a Starting Point

{% tabs %}
{% tab title="I want to query data" %}
Let’s look at [Data Schemas](/documentation/en/framework/data/schema.md) and [Queries and Navigation](/documentation/en/framework/data/querying.md) first. These two pages explain how to represent fields, navigation properties, paging, and sorting.
{% endtab %}

{% tab title="I want to write data" %}
Let’s look at [Write Operations](/documentation/en/framework/data/writing.md) and [Conditions and Operands](/documentation/en/framework/data/conditions-and-operands.md) first. These two pages explain add, update, delete, upsert, and field operations.
{% endtab %}

{% tab title="I want to access the database" %}
Let’s look at [Connection Configuration](/documentation/en/framework/data/connections.md) and [Drivers](/documentation/en/framework/data/drivers.md) first. These two pages explain connection names, read/write separation, driver plugins, and deployment checks.
{% endtab %}
{% endtabs %}

## Browse by Driver

Common drivers include SQL Server, MySQL, SQLite, DuckDB, PostgreSQL, TDengine, ClickHouse, and InfluxDB. Drivers are usually deployed as independent plugins, and the data driver and connection settings driver are mounted to the plugin tree.

When a database has been selected, you can directly enter the [MySQL](/documentation/en/framework/data/drivers/mysql.md), [SQL Server](/documentation/en/framework/data/drivers/mssql.md), [PostgreSQL](/documentation/en/framework/data/drivers/postgres.md), [SQLite](/documentation/en/framework/data/drivers/sqlite.md), [DuckDB](/documentation/en/framework/data/drivers/duckdb.md), [ClickHouse](/documentation/en/framework/data/drivers/clickhouse.md), [TDengine](/documentation/en/framework/data/drivers/tdengine.md) or [InfluxDB](/documentation/en/framework/data/drivers/influx.md) project page.

See [Package and Module Index](/documentation/en/references/packages.md) for the complete package name and [Plugin Manifests and Loading](/documentation/en/framework/plugins/plugin-file.md) for the deployment method.

{% content-ref url="/pages/1bhQDOmKMbW073thPyN4" %}
[Browse by Driver](/documentation/en/framework/data/drivers.md)
{% endcontent-ref %}

## Typical Usage

Source: [src/Module.cs](https://github.com/Zongsoft/Zongsoft.Discussions/blob/main/src/Module.cs#L52) (excerpt; see source for context).

{% code title="Module.cs" %}

```csharp
public IDataAccess Accessor => _accessor ??= this.Services.ResolveRequired<IDataAccessProvider>().GetAccessor(this.Name);
```

{% endcode %}

In this call:

* `this.Services.ResolveRequired<IDataAccessProvider>()` resolves the data-access provider from the module’s services.
* `GetAccessor(this.Name)` obtains the accessor for the current module name; the shown source belongs to the Discussions module.
* `??=` caches the accessor for subsequent calls.

For query conditions, selected fields, navigation, sorting, and paging, continue with [Data Access Interfaces](/documentation/en/framework/data/data-access.md) and [Queries and Navigation](/documentation/en/framework/data/querying.md).

## Next Steps

{% content-ref url="/pages/9VXTSD3OjYdSWPUgEgYV" %}
[Data Schemas](/documentation/en/framework/data/schema.md)
{% endcontent-ref %}

{% content-ref url="/pages/xNT1H7DDNp23XqNWACzv" %}
[Data Access Interfaces](/documentation/en/framework/data/data-access.md)
{% endcontent-ref %}

{% content-ref url="/pages/8ud03SdBkO4M3qHaGQY0" %}
[Write Operations](/documentation/en/framework/data/writing.md)
{% endcontent-ref %}

## Related Resources

* [Zongsoft.Data source code directory](https://github.com/Zongsoft/framework/tree/main/Zongsoft.Data)
* [Zongsoft.Data Chinese README](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Data/README.zh-Hans.md)
* [Zongsoft.Data English README](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Data/README.md)
* [Zongsoft.Data NuGet package](https://www.nuget.org/packages/Zongsoft.Data)


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.zongsoft.com/documentation/en/framework/data.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.