---
title: Understanding the Data Abstraction Layer | Shopware Community Hub
description: >-
Learn what the Data Abstraction Layer (DAL) in Shopware is and how it fits
into the platform architecture.
canonical_url: 'https://hub.shopware.com/learn/unit/understanding-the-data-abstraction-layer'
---
# Understanding the Data Abstraction Layer
- Understand what the Data Abstraction Layer (DAL) is and why Shopware uses it.
- Identify the core building blocks of the DAL.
- Understand how data is read and written through repositories.
# Understanding the Data Abstraction Layer
Before creating entities, it helps to understand the bigger picture: What is the Data Abstraction Layer (DAL)? What problems does it solve? How do its building blocks work together?
This learning unit provides a conceptual overview of the DAL and prepares you for practical implementation in the following units.
## What is the Data Abstraction Layer?
The [DAL](https://developer.shopware.com/docs/concepts/framework/data-abstraction-layer.html) is Shopware's powerful abstraction system that provides a unified way to access and manage data.
Instead of writing SQL queries directly, you work with structured PHP objects that describe:
- How data is structured
- How entities are related
- How data can be queried or modified
This abstraction allows you to work with PHP objects instead of database tables and keeps your code consistent, maintainable, and extensible.
## Why Does Shopware Use the DAL?
The DAL provides a shared foundation for all data access in Shopware.
It consists of Entity Definitions that define your data structure and Repositories that handle CRUD operations, allowing you to work with PHP objects instead of database tables.
The DAL automatically handles database queries, relationships, translations, and caching, making your code more maintainable and database-agnostic while providing built-in features like filtering, sorting, and pagination.
In practice, this means:
- You work with PHP objects instead of SQL
- Data access follows a consistent pattern
- Common features like filtering and pagination are handled centrally
You can still use raw SQL queries when needed. But the DAL is the default and recommended approach.
You can think of the DAL as a bridge between your PHP code and your database within Shopware.
## Core Building Blocks
The DAL is built around a small set of core concepts that always work together.
### Entities
An **Entity** represents a single record of a data model, such as a product, a customer, or an order.
In your PHP code, entities are the objects you work with in your business logic. They have typed properties and can reference related entities via **associations**.
For example, an order entity typically references both product and customer entities via associations. This allows you to work with all related data as part of a single business process.
### EntityDefinition
The **EntityDefinition** describes the **structure** of an entity:
- Fields (types, required flags, primary keys)
- Associations to other entities (one-to-one, one-to-many, many-to-many)
- Metadata (entity name, classes)
Think of it as the **source of truth** for how Shopware understands and manages your entity.
### Repository
A **repository** is the primary entry point for reading and writing entity data via DAL. It provides CRUD operations throughout the DAL system. So you are able to:
- Read data (e.g., `product`) from the database through the repository
- Create, update, and delete entities (and therefore data from the database)
- Search for entities or IDs from related data based on criteria
Every entity in Shopware has a corresponding repository.
#### Common Repository Operations
Using DAL repositories, the following operations are the most common:
- `search()` to load entities based on criteria.
- `searchIds()` to load IDs based on criteria.
- `create()` to create new entities.
- `update()` to update existing entities.
- `upsert()` to create or update entities – useful when you don't know if an entity already exists
- `delete()` to delete entities
The difference between `update()` and `upsert()` is that `upsert()` will create a new entity if it doesn't exist yet **or** update it if it already exists.
The `update()` method can only be used if the entity already exists.
To explore all available methods, feel free to explore the implementation in the [Shopware core](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/EntityRepository.php)
### Criteria
A **criteria** is an object that describes **what you want to load** from the database via DAL. It can be used to:
- Filter
- Sorting
- Pagination
- Associations (e.g., `addAssociation('product')`)
Only what you request in the criteria is returned. The DAL handles how the underlying database query is executed.
## The DAL Is Not An ORM
Although the DAL works with entities, it is not a classic ORM like Doctrine. Nothing is loaded implicitly. Which fields and associations are available always depends on what is defined in the criteria object.
This design gives developers full control over performance and data loading behavior.
## How the Pieces Fit Together
At a higher level, data access in Shopware allows this flow:
1. You define a `Criteria` object describing what you want to load
2. You call a repository method with that criteria
3. The DAL validates the request using the entity definition
4. Data is fetched from the database
5. Results are returned as entities or entity collections
This same pattern applies consistently across all entities in Shopware.
## Summary
In this learning unit, you learned:
- What the DAL is and why Shopware uses it
- The role of entities, entity definitions, repositories, and criteria in the DAL
- How data access in Shopware follows a consistent, criteria-driven pattern
- Why the DAL is not a traditional ORM and how it gives you control over performance
With this conceptual foundation, you are now ready to work with the DAL in practice.