How to perform a join query using Symfony and Doctrine Query Builder

How to perform a join query using Symfony and Doctrine Query Builder

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

How to perform a join query using Symfony and Doctrine Query Builder

You cannot mix class names with DQL aliases in the same way you might in native SQL or Laravel Eloquent. The error in your snippet stems from trying to reference MyBundle:RelatedEntity as an alias while simultaneously defining the relationship via $em->getRepository. When you use leftJoin, the first argument is strictly the alias of the entity being joined, not a fully qualified class name.

To fix this, you must define the alias for your main entity and then navigate to the related entity through the mapping defined in your entities. Since you mentioned a 1:1 relationship where MyEntity has an association named idRelatedEntity, that field usually maps to a property on the MyEntity class (e.g., $relatedEntity) or a foreign key column.

Here is how to construct the correct DQL query using the Query Builder:

$repository = $em->getRepository('MyBundle:RelatedEntity');

$query = $repository->createQueryBuilder('r')
    ->leftJoin('r.relatedEntity', 'myEntity') // Adjust property name based on your mapping
    ->where('r.foo = :foo')
    ->setParameter('foo', 1)
    ->getQuery();

$results = $query->getResult();

In this example, we start the query on the RelatedEntity because that is where the filtering condition (r.foo) exists. We then use leftJoin to fetch the associated MyEntity instance. The critical detail here is r.relatedEntity. This assumes your RelatedEntity has a property named relatedEntity which holds the reference to MyEntity. If your mapping uses an inverse side or a specific column name, you must adjust the navigation path accordingly.

Understanding the Navigation Path

Doctrine relies on the relationship mappings defined in your entity classes to determine how to traverse from one object to another. In a 1:1 relationship, there is typically one side that owns the foreign key. If MyEntity owns the relationship (indicated by mappedBy on the RelatedEntity side), you can navigate from RelatedEntity to MyEntity if the owning side exposes it as a property or getter method.

However, often in 1:1 relationships, the "inverse" side does not have a direct property pointing back to the owner unless explicitly mapped with an inverse flag. If your MyEntity holds the foreign key column but you are querying from RelatedEntity, you might need to use the DQL path that reflects the actual column name or the relationship name defined in the MappedBy annotation.

For instance, if your RelatedEntity has @ManyToOne(targetEntity="MyEntity", mappedBy="relatedEntity"), then r.relatedEntity is the correct navigation path. If you are unsure of the property name, inspect your entity definitions to find the exact string used for the association.

Handling Many-to-One vs One-to-One Mapping

If your entities were actually configured as a standard Many-to-One or One-to-Many relationship rather than a 1:1, the syntax remains identical regarding the join, but the performance characteristics might differ slightly due to how Doctrine handles hydration. With 1:1 relationships specifically, ensure that the @OneToOne annotations are correctly placed. If you have mappedBy on the RelatedEntity, it implies MyEntity is the owner. In that case, navigating from r (the root of your query) to myEntity requires the inverse property name.

If your entities do not expose a direct property for the relationship on the side you are querying from, you can still join by referencing the column directly if DQL allows, though using the association path is preferred for clarity and maintainability:

->leftJoin('r.myEntity', 'e') // Assuming 'myEntity' is the property name or inverse mapping

Performance Considerations

When joining entities in Doctrine, be mindful of the data you are actually selecting. The example above returns an array of RelatedEntity objects, each containing a populated MyEntity object as a property. If you only need specific fields from MyEntity, you can map the selection to a DTO or use select('r.foo, e.someColumn'). However, if you select both classes without specifying how to handle the root entity, Doctrine will hydrate RelatedEntity as the root class.

Avoid selecting multiple root entities in a single query result unless necessary; this often leads to confusion during hydration. Stick to one root alias (e.g., 'r') and treat others ('e') as associated objects within that root instance.

Final Recommendation

Always verify the exact property names used for your associations by inspecting your entity annotations or docblocks. The Query Builder is a powerful tool, but it requires strict adherence to the DQL path definitions established in your ORM mapping configuration. Once the alias and navigation path are correct, the join behaves predictably regardless of whether you are filtering on a column in the joined table or the root table.

Our network