Data Engine

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

Data Engine

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, then follow Your First Query through the Discussions table setup, connection configuration, and forum query. For organizing business rules, see Data Services.

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

Data Schemas

Describes the shape of the data queried or written.

Mapping Files

Describe entities, tables, fields, and relationships.

Connection Configuration

Configure data sources, read/write separation and drivers.

Data Access Interfaces

Execute queries, writes, aggregations and commands.

Conditions and Operands

Express filter conditions and field operations.

Queries and Navigation

Read the object graph using `schema`, paging and sorting.

Write Operations

Add, update, delete and upsert.

Drivers

Select, deploy and extend database drivers.

Choose a Starting Point

I want to query data

Let’s look at Data Schemas and Queries and Navigation first. These two pages explain how to represent fields, navigation properties, paging, and sorting.

I want to write data

Let’s look at Write Operations and Conditions and Operands first. These two pages explain add, update, delete, upsert, and field operations.

I want to access the database

Let’s look at Connection Configuration and Drivers first. These two pages explain connection names, read/write separation, driver plugins, and deployment checks.

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, SQL Server, PostgreSQL, SQLite, DuckDB, ClickHouse, TDengine or InfluxDB project page.

See Package and Module Index for the complete package name and Plugin Manifests and Loading for the deployment method.

Browse by Driver

Typical Usage

Source: src/Module.cs (excerpt; see source for context).

Module.cs

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

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 and Queries and Navigation.

Next Steps

Data SchemasData Access InterfacesWrite Operations

Related Resources

• Zongsoft.Data source code directory

• Zongsoft.Data Chinese README

• Zongsoft.Data English README

• Zongsoft.Data NuGet package