Native SQL
==========

With ``NativeQuery`` you can execute native SELECT SQL statements
and map the results to Doctrine entities or any other result format
supported by Doctrine.

In order to make this mapping possible, you need to describe
to Doctrine what columns in the result map to which entity property.
This description is represented by a ``ResultSetMapping`` object.

With this feature you can map arbitrary SQL code to objects, such as highly
vendor-optimized SQL or stored-procedures.

Writing ``ResultSetMapping`` from scratch is complex, but there is a convenience
wrapper around it called a ``ResultSetMappingBuilder``. It can generate
the mappings for you based on Entities and even generates the ``SELECT``
clause based on this information for you.

.. note::

    If you want to execute DELETE, UPDATE or INSERT statements
    the Native SQL API cannot be used and will probably throw errors.
    Use ``EntityManager#getConnection()`` to access the native database
    connection and call the ``executeUpdate()`` method for these
    queries.

The NativeQuery class
---------------------

To create a ``NativeQuery`` you use the method
``EntityManager#createNativeQuery($sql, $resultSetMapping)``. As you can see in
the signature of this method, it expects 2 ingredients: The SQL you want to
execute and the ``ResultSetMapping`` that describes how the results will be
mapped.

Once you obtained an instance of a ``NativeQuery``, you can bind parameters to
it with the same API that ``Query`` has and execute it.

.. code-block:: php

    <?php
    use Doctrine\ORM\Query\ResultSetMapping;

    $rsm = new ResultSetMapping();
    // build rsm here

    $query = $entityManager->createNativeQuery('SELECT id, name, discr FROM users WHERE name = ?', $rsm);
    $query->setParameter(1, 'romanb');

    $users = $query->getResult();

ResultSetMappingBuilder
-----------------------

An easy start into ResultSet mapping is the ``ResultSetMappingBuilder`` object.
This has several benefits:

- The builder takes care of automatically updating your ``ResultSetMapping``
  when the fields or associations change on the metadata of an entity.
- You can generate the required ``SELECT`` expression for a builder
  by converting it to a string.
- The API is much simpler than the usual ``ResultSetMapping`` API.

One downside is that the builder API does not yet support entities
with inheritance hierachies.

.. code-block:: php

    <?php

    use Doctrine\ORM\Query\ResultSetMappingBuilder;

    $sql = "SELECT u.id, u.name, a.id AS address_id, a.street, a.city " . 
           "FROM users u INNER JOIN address a ON u.address_id = a.id";

    $rsm = new ResultSetMappingBuilder($entityManager);
    $rsm->addRootEntityFromClassMetadata('MyProject\User', 'u');
    $rsm->addJoinedEntityFromClassMetadata('MyProject\Address', 'a', 'u', 'address', array('id' => 'address_id'));

The builder extends the ``ResultSetMapping`` class and as such has all the functionality of it as well.

..versionadded:: 2.4

Starting with Doctrine ORM 2.4 you can generate the ``SELECT`` clause
from a ``ResultSetMappingBuilder``. You can either cast the builder
object to ``(string)`` and the DQL aliases are used as SQL table aliases
or use the ``generateSelectClause($tableAliases)`` method and pass
a mapping from DQL alias (key) to SQL alias (value)

.. code-block:: php

    <?php

    $selectClause = $builder->generateSelectClause(array(
        'u' => 't1',
        'g' => 't2'
    ));
    $sql = "SELECT " . $selectClause . " FROM users t1 JOIN groups t2 ON t1.group_id = t2.id";


The ResultSetMapping
--------------------

Understanding the ``ResultSetMapping`` is the key to using a
``NativeQuery``. A Doctrine result can contain the following
components:


-  Entity results. These represent root result elements.
-  Joined entity results. These represent joined entities in
   associations of root entity results.
-  Field results. These represent a column in the result set that
   maps to a field of an entity. A field result always belongs to an
   entity result or joined entity result.
-  Scalar results. These represent scalar values in the result set
   that will appear in each result row. Adding scalar results to a
   ResultSetMapping can also cause the overall result to become
   **mixed** (see DQL - Doctrine Query Language) if the same
   ResultSetMapping also contains entity results.
-  Meta results. These represent columns that contain
   meta-information, such as foreign keys and discriminator columns.
   When querying for objects (``getResult()``), all meta columns of
   root entities or joined entities must be present in the SQL query
   and mapped accordingly using ``ResultSetMapping#addMetaResult``.

.. note::

    It might not surprise you that Doctrine uses
    ``ResultSetMapping`` internally when you create DQL queries. As
    the query gets parsed and transformed to SQL, Doctrine fills a
    ``ResultSetMapping`` that describes how the results should be
    processed by the hydration routines.


We will now look at each of the result types that can appear in a
ResultSetMapping in detail.

Entity results
~~~~~~~~~~~~~~

An entity result describes an entity type that appears as a root
element in the transformed result. You add an entity result through
``ResultSetMapping#addEntityResult()``. Let's take a look at the
method signature in detail:

.. code-block:: php

    <?php
    /**
     * Adds an entity result to this ResultSetMapping.
     *
     * @param string $class The class name of the entity.
     * @param string $alias The alias for the class. The alias must be unique among all entity
     *                      results or joined entity results within this ResultSetMapping.
     */
    public function addEntityResult($class, $alias)

The first parameter is the fully qualified name of the entity
class. The second parameter is some arbitrary alias for this entity
result that must be unique within a ``ResultSetMapping``. You use
this alias to attach field results to the entity result. It is very
similar to an identification variable that you use in DQL to alias
classes or relationships.

An entity result alone is not enough to form a valid
``ResultSetMapping``. An entity result or joined entity result
always needs a set of field results, which we will look at soon.

Joined entity results
~~~~~~~~~~~~~~~~~~~~~

A joined entity result describes an entity type that appears as a
joined relationship element in the transformed result, attached to
a (root) entity result. You add a joined entity result through
``ResultSetMapping#addJoinedEntityResult()``. Let's take a look at
the method signature in detail:

.. code-block:: php

    <?php
    /**
     * Adds a joined entity result.
     *
     * @param string $class The class name of the joined entity.
     * @param string $alias The unique alias to use for the joined entity.
     * @param string $parentAlias The alias of the entity result that is the parent of this joined result.
     * @param object $relation The association field that connects the parent entity result with the joined entity result.
     */
    public function addJoinedEntityResult($class, $alias, $parentAlias, $relation)

The first parameter is the class name of the joined entity. The
second parameter is an arbitrary alias for the joined entity that
must be unique within the ``ResultSetMapping``. You use this alias
to attach field results to the entity result. The third parameter
is the alias of the entity result that is the parent type of the
joined relationship. The fourth and last parameter is the name of
the field on the parent entity result that should contain the
joined entity result.

Field results
~~~~~~~~~~~~~

A field result describes the mapping of a single column in a SQL
result set to a field in an entity. As such, field results are
inherently bound to entity results. You add a field result through
``ResultSetMapping#addFieldResult()``. Again, let's examine the
method signature in detail:

.. code-block:: php

    <?php
    /**
     * Adds a field result that is part of an entity result or joined entity result.
     *
     * @param string $alias The alias of the entity result or joined entity result.
     * @param string $columnName The name of the column in the SQL result set.
     * @param string $fieldName The name of the field on the (joined) entity.
     */
    public function addFieldResult($alias, $columnName, $fieldName)

The first parameter is the alias of the entity result to which the
field result will belong. The second parameter is the name of the
column in the SQL result set. Note that this name is case
sensitive, i.e. if you use a native query against Oracle it must be
all uppercase. The third parameter is the name of the field on the
entity result identified by ``$alias`` into which the value of the
column should be set.

Scalar results
~~~~~~~~~~~~~~

A scalar result describes the mapping of a single column in a SQL
result set to a scalar value in the Doctrine result. Scalar results
are typically used for aggregate values but any column in the SQL
result set can be mapped as a scalar value. To add a scalar result
use ``ResultSetMapping#addScalarResult()``. The method signature in
detail:

.. code-block:: php

    <?php
    /**
     * Adds a scalar result mapping.
     *
     * @param string $columnName The name of the column in the SQL result set.
     * @param string $alias The result alias with which the scalar result should be placed in the result structure.
     */
    public function addScalarResult($columnName, $alias)

The first parameter is the name of the column in the SQL result set
and the second parameter is the result alias under which the value
of the column will be placed in the transformed Doctrine result.

Meta results
~~~~~~~~~~~~

A meta result describes a single column in a SQL result set that
is either a foreign key or a discriminator column. These columns
are essential for Doctrine to properly construct objects out of SQL
result sets. To add a column as a meta result use
``ResultSetMapping#addMetaResult()``. The method signature in
detail:

.. code-block:: php

    <?php
    /**
     * Adds a meta column (foreign key or discriminator column) to the result set.
     * 
     * @param string  $alias
     * @param string  $columnAlias
     * @param string  $columnName
     * @param boolean $isIdentifierColumn
     */
    public function addMetaResult($alias, $columnAlias, $columnName, $isIdentifierColumn = false)

The first parameter is the alias of the entity result to which the
meta column belongs. A meta result column (foreign key or
discriminator column) always belongs to an entity result. The
second parameter is the column alias/name of the column in the SQL
result set and the third parameter is the column name used in the
mapping.
The fourth parameter should be set to true in case the primary key
of the entity is the foreign key you're adding.

Discriminator Column
~~~~~~~~~~~~~~~~~~~~

When joining an inheritance tree you have to give Doctrine a hint
which meta-column is the discriminator column of this tree.

.. code-block:: php

    <?php
    /**
     * Sets a discriminator column for an entity result or joined entity result.
     * The discriminator column will be used to determine the concrete class name to
     * instantiate.
     *
     * @param string $alias The alias of the entity result or joined entity result the discriminator
     *                      column should be used for.
     * @param string $discrColumn The name of the discriminator column in the SQL result set.
     */
    public function setDiscriminatorColumn($alias, $discrColumn)

Examples
~~~~~~~~

Understanding a ResultSetMapping is probably easiest through
looking at some examples.

First a basic example that describes the mapping of a single
entity.

.. code-block:: php

    <?php
    // Equivalent DQL query: "select u from User u where u.name=?1"
    // User owns no associations.
    $rsm = new ResultSetMapping;
    $rsm->addEntityResult('User', 'u');
    $rsm->addFieldResult('u', 'id', 'id');
    $rsm->addFieldResult('u', 'name', 'name');
    
    $query = $this->_em->createNativeQuery('SELECT id, name FROM users WHERE name = ?', $rsm);
    $query->setParameter(1, 'romanb');
    
    $users = $query->getResult();

The result would look like this:

.. code-block:: php

    array(
        [0] => User (Object)
    )

Note that this would be a partial object if the entity has more
fields than just id and name. In the example above the column and
field names are identical but that is not necessary, of course.
Also note that the query string passed to createNativeQuery is
**real native SQL**. Doctrine does not touch this SQL in any way.

In the previous basic example, a User had no relations and the
table the class is mapped to owns no foreign keys. The next example
assumes User has a unidirectional or bidirectional one-to-one
association to a CmsAddress, where the User is the owning side and
thus owns the foreign key.

.. code-block:: php

    <?php
    // Equivalent DQL query: "select u from User u where u.name=?1"
    // User owns an association to an Address but the Address is not loaded in the query.
    $rsm = new ResultSetMapping;
    $rsm->addEntityResult('User', 'u');
    $rsm->addFieldResult('u', 'id', 'id');
    $rsm->addFieldResult('u', 'name', 'name');
    $rsm->addMetaResult('u', 'address_id', 'address_id');
    
    $query = $this->_em->createNativeQuery('SELECT id, name, address_id FROM users WHERE name = ?', $rsm);
    $query->setParameter(1, 'romanb');
    
    $users = $query->getResult();

Foreign keys are used by Doctrine for lazy-loading purposes when
querying for objects. In the previous example, each user object in
the result will have a proxy (a "ghost") in place of the address
that contains the address\_id. When the ghost proxy is accessed, it
loads itself based on this key.

Consequently, associations that are *fetch-joined* do not require
the foreign keys to be present in the SQL result set, only
associations that are lazy.

.. code-block:: php

    <?php
    // Equivalent DQL query: "select u from User u join u.address a WHERE u.name = ?1"
    // User owns association to an Address and the Address is loaded in the query.
    $rsm = new ResultSetMapping;
    $rsm->addEntityResult('User', 'u');
    $rsm->addFieldResult('u', 'id', 'id');
    $rsm->addFieldResult('u', 'name', 'name');
    $rsm->addJoinedEntityResult('Address' , 'a', 'u', 'address');
    $rsm->addFieldResult('a', 'address_id', 'id');
    $rsm->addFieldResult('a', 'street', 'street');
    $rsm->addFieldResult('a', 'city', 'city');
    
    $sql = 'SELECT u.id, u.name, a.id AS address_id, a.street, a.city FROM users u ' .
           'INNER JOIN address a ON u.address_id = a.id WHERE u.name = ?';
    $query = $this->_em->createNativeQuery($sql, $rsm);
    $query->setParameter(1, 'romanb');
    
    $users = $query->getResult();

In this case the nested entity ``Address`` is registered with the
``ResultSetMapping#addJoinedEntityResult`` method, which notifies
Doctrine that this entity is not hydrated at the root level, but as
a joined entity somewhere inside the object graph. In this case we
specify the alias 'u' as third parameter and ``address`` as fourth
parameter, which means the ``Address`` is hydrated into the
``User::$address`` property.

If a fetched entity is part of a mapped hierarchy that requires a
discriminator column, this column must be present in the result set
as a meta column so that Doctrine can create the appropriate
concrete type. This is shown in the following example where we
assume that there are one or more subclasses that extend User and
either Class Table Inheritance or Single Table Inheritance is used
to map the hierarchy (both use a discriminator column).

.. code-block:: php

    <?php
    // Equivalent DQL query: "select u from User u where u.name=?1"
    // User is a mapped base class for other classes. User owns no associations.
    $rsm = new ResultSetMapping;
    $rsm->addEntityResult('User', 'u');
    $rsm->addFieldResult('u', 'id', 'id');
    $rsm->addFieldResult('u', 'name', 'name');
    $rsm->addMetaResult('u', 'discr', 'discr'); // discriminator column
    $rsm->setDiscriminatorColumn('u', 'discr');
    
    $query = $this->_em->createNativeQuery('SELECT id, name, discr FROM users WHERE name = ?', $rsm);
    $query->setParameter(1, 'romanb');
    
    $users = $query->getResult();

Note that in the case of Class Table Inheritance, an example as
above would result in partial objects if any objects in the result
are actually a subtype of User. When using DQL, Doctrine
automatically includes the necessary joins for this mapping
strategy but with native SQL it is your responsibility.

Named Native Query
------------------

You can also map a native query using a named native query mapping.

To achieve that, you must describe the SQL resultset structure
using named native query (and sql resultset mappings if is a several resultset mappings).

Like named query, a named native query can be defined at class level or in a XML or YAML file.


A resultSetMapping parameter is defined in @NamedNativeQuery,
it represents the name of a defined @SqlResultSetMapping.

.. configuration-block::

    .. code-block:: php

        <?php
        namespace MyProject\Model;
        /**
         * @NamedNativeQueries({
         *      @NamedNativeQuery(
         *          name            = "fetchMultipleJoinsEntityResults",
         *          resultSetMapping= "mappingMultipleJoinsEntityResults",
         *          query           = "SELECT u.id AS u_id, u.name AS u_name, u.status AS u_status, a.id AS a_id, a.zip AS a_zip, a.country AS a_country, COUNT(p.phonenumber) AS numphones FROM users u INNER JOIN addresses a ON u.id = a.user_id INNER JOIN phonenumbers p ON u.id = p.user_id GROUP BY u.id, u.name, u.status, u.username, a.id, a.zip, a.country ORDER BY u.username"
         *      ),
         * })
         * @SqlResultSetMappings({
         *      @SqlResultSetMapping(
         *          name    = "mappingMultipleJoinsEntityResults",
         *          entities= {
         *              @EntityResult(
         *                  entityClass = "__CLASS__",
         *                  fields      = {
         *                      @FieldResult(name = "id",       column="u_id"),
         *                      @FieldResult(name = "name",     column="u_name"),
         *                      @FieldResult(name = "status",   column="u_status"),
         *                  }
         *              ),
         *              @EntityResult(
         *                  entityClass = "Address",
         *                  fields      = {
         *                      @FieldResult(name = "id",       column="a_id"),
         *                      @FieldResult(name = "zip",      column="a_zip"),
         *                      @FieldResult(name = "country",  column="a_country"),
         *                  }
         *              )
         *          },
         *          columns = {
         *              @ColumnResult("numphones")
         *          }
         *      )
         *})
         */
         class User
        {
            /** @Id @Column(type="integer") @GeneratedValue */
            public $id;

            /** @Column(type="string", length=50, nullable=true) */
            public $status;

            /** @Column(type="string", length=255, unique=true) */
            public $username;

            /** @Column(type="string", length=255) */
            public $name;

            /** @OneToMany(targetEntity="Phonenumber") */
            public $phonenumbers;

            /** @OneToOne(targetEntity="Address") */
            public $address;

            // ....
        }

    .. code-block:: xml

        <doctrine-mapping>
            <entity name="MyProject\Model\User">
                <named-native-queries>
                    <named-native-query name="fetchMultipleJoinsEntityResults" result-set-mapping="mappingMultipleJoinsEntityResults">
                        <query>SELECT u.id AS u_id, u.name AS u_name, u.status AS u_status, a.id AS a_id, a.zip AS a_zip, a.country AS a_country, COUNT(p.phonenumber) AS numphones FROM users u INNER JOIN addresses a ON u.id = a.user_id INNER JOIN phonenumbers p ON u.id = p.user_id GROUP BY u.id, u.name, u.status, u.username, a.id, a.zip, a.country ORDER BY u.username</query>
                    </named-native-query>
                </named-native-queries>
                <sql-result-set-mappings>
                    <sql-result-set-mapping name="mappingMultipleJoinsEntityResults">
                        <entity-result entity-class="__CLASS__">
                            <field-result name="id" column="u_id"/>
                            <field-result name="name" column="u_name"/>
                            <field-result name="status" column="u_status"/>
                        </entity-result>
                        <entity-result entity-class="Address">
                            <field-result name="id" column="a_id"/>
                            <field-result name="zip" column="a_zip"/>
                            <field-result name="country" column="a_country"/>
                        </entity-result>
                        <column-result name="numphones"/>
                    </sql-result-set-mapping>
                </sql-result-set-mappings>
            </entity>
        </doctrine-mapping>
    .. code-block:: yaml

        MyProject\Model\User:
          type: entity
          namedNativeQueries:
            fetchMultipleJoinsEntityResults:
              name: fetchMultipleJoinsEntityResults
              resultSetMapping: mappingMultipleJoinsEntityResults
              query: SELECT u.id AS u_id, u.name AS u_name, u.status AS u_status, a.id AS a_id, a.zip AS a_zip, a.country AS a_country, COUNT(p.phonenumber) AS numphones FROM users u INNER JOIN addresses a ON u.id = a.user_id INNER JOIN phonenumbers p ON u.id = p.user_id GROUP BY u.id, u.name, u.status, u.username, a.id, a.zip, a.country ORDER BY u.username
          sqlResultSetMappings:
            mappingMultipleJoinsEntityResults:
              name: mappingMultipleJoinsEntityResults
              columnResult:
                0:
                  name: numphones
              entityResult:
                0:
                  entityClass: __CLASS__
                  fieldResult:
                    0:
                      name: id
                      column: u_id
                    1:
                      name: name
                      column: u_name
                    2:
                      name: status
                      column: u_status
                1:
                  entityClass: Address
                  fieldResult:
                    0:
                      name: id
                      column: a_id
                    1:
                      name: zip
                      column: a_zip
                    2:
                      name: country
                      column: a_country


Things to note:
    - The resultset mapping declares the entities retrieved by this native query.
    - Each field of the entity is bound to a SQL alias (or column name).
    - All fields of the entity including the ones of subclasses
      and the foreign key columns of related entities have to be present in the SQL query.
    - Field definitions are optional provided that they map to the same
      column name as the one declared on the class property.
    - ``__CLASS__`` is an alias for the mapped class


In the above example,
the ``fetchJoinedAddress`` named query use the joinMapping result set mapping.
This mapping returns 2 entities, User and Address, each property is declared and associated to a column name,
actually the column name retrieved by the query.

Let's now see an implicit declaration of the property / column.

.. configuration-block::

    .. code-block:: php

        <?php
        namespace MyProject\Model;
            /**
             * @NamedNativeQueries({
             *      @NamedNativeQuery(
             *          name                = "findAll",
             *          resultSetMapping    = "mappingFindAll",
             *          query               = "SELECT * FROM addresses"
             *      ),
             * })
             * @SqlResultSetMappings({
             *      @SqlResultSetMapping(
             *          name    = "mappingFindAll",
             *          entities= {
             *              @EntityResult(
             *                  entityClass = "Address"
             *              )
             *          }
             *      )
             * })
             */
           class Address
           {
                /**  @Id @Column(type="integer") @GeneratedValue */
                public $id;

                /** @Column() */
                public $country;

                /** @Column() */
                public $zip;

                /** @Column()*/
                public $city;

                // ....
            }

    .. code-block:: xml

        <doctrine-mapping>
            <entity name="MyProject\Model\Address">
                <named-native-queries>
                    <named-native-query name="findAll" result-set-mapping="mappingFindAll">
                        <query>SELECT * FROM addresses</query>
                    </named-native-query>
                </named-native-queries>
                <sql-result-set-mappings>
                    <sql-result-set-mapping name="mappingFindAll">
                        <entity-result entity-class="Address"/>
                    </sql-result-set-mapping>
                </sql-result-set-mappings>
            </entity>
        </doctrine-mapping>
    .. code-block:: yaml

        MyProject\Model\Address:
          type: entity
          namedNativeQueries:
            findAll:
              resultSetMapping: mappingFindAll
              query: SELECT * FROM addresses
          sqlResultSetMappings:
            mappingFindAll:
              name: mappingFindAll
              entityResult:
                address:
                  entityClass: Address


In this example, we only describe the entity member of the result set mapping.
The property / column mappings is done using the entity mapping values.
In this case the model property is bound to the model_txt column.
If the association to a related entity involve a composite primary key,
a @FieldResult element should be used for each foreign key column.
The @FieldResult name is composed of the property name for the relationship,
followed by a dot ("."), followed by the name or the field or property of the primary key.


.. configuration-block::

    .. code-block:: php

        <?php
        namespace MyProject\Model;
            /**
             * @NamedNativeQueries({
             *      @NamedNativeQuery(
             *          name            = "fetchJoinedAddress",
             *          resultSetMapping= "mappingJoinedAddress",
             *          query           = "SELECT u.id, u.name, u.status, a.id AS a_id, a.country AS a_country, a.zip AS a_zip, a.city AS a_city FROM users u INNER JOIN addresses a ON u.id = a.user_id WHERE u.username = ?"
             *      ),
             * })
             * @SqlResultSetMappings({
             *      @SqlResultSetMapping(
             *          name    = "mappingJoinedAddress",
             *          entities= {
             *              @EntityResult(
             *                  entityClass = "__CLASS__",
             *                  fields      = {
             *                      @FieldResult(name = "id"),
             *                      @FieldResult(name = "name"),
             *                      @FieldResult(name = "status"),
             *                      @FieldResult(name = "address.id", column = "a_id"),
             *                      @FieldResult(name = "address.zip", column = "a_zip"),
             *                      @FieldResult(name = "address.city", column = "a_city"),
             *                      @FieldResult(name = "address.country", column = "a_country"),
             *                  }
             *              )
             *          }
             *      )
             * })
             */
            class User
            {
                /** @Id @Column(type="integer") @GeneratedValue */
                public $id;

                /** @Column(type="string", length=50, nullable=true) */
                public $status;

                /** @Column(type="string", length=255, unique=true) */
                public $username;

                /** @Column(type="string", length=255) */
                public $name;

                /** @OneToOne(targetEntity="Address") */
                public $address;

                // ....
            }

    .. code-block:: xml

        <doctrine-mapping>
            <entity name="MyProject\Model\User">
                <named-native-queries>
                    <named-native-query name="fetchJoinedAddress" result-set-mapping="mappingJoinedAddress">
                        <query>SELECT u.id, u.name, u.status, a.id AS a_id, a.country AS a_country, a.zip AS a_zip, a.city AS a_city FROM users u INNER JOIN addresses a ON u.id = a.user_id WHERE u.username = ?</query>
                    </named-native-query>
                </named-native-queries>
                <sql-result-set-mappings>
                    <sql-result-set-mapping name="mappingJoinedAddress">
                        <entity-result entity-class="__CLASS__">
                            <field-result name="id"/>
                            <field-result name="name"/>
                            <field-result name="status"/>
                            <field-result name="address.id" column="a_id"/>
                            <field-result name="address.zip"  column="a_zip"/>
                            <field-result name="address.city"  column="a_city"/>
                            <field-result name="address.country" column="a_country"/>
                        </entity-result>
                    </sql-result-set-mapping>
                </sql-result-set-mappings>
            </entity>
        </doctrine-mapping>
    .. code-block:: yaml

        MyProject\Model\User:
          type: entity
          namedNativeQueries:
            fetchJoinedAddress:
              name: fetchJoinedAddress
              resultSetMapping: mappingJoinedAddress
              query: SELECT u.id, u.name, u.status, a.id AS a_id, a.country AS a_country, a.zip AS a_zip, a.city AS a_city FROM users u INNER JOIN addresses a ON u.id = a.user_id WHERE u.username = ?
          sqlResultSetMappings:
            mappingJoinedAddress:
              entityResult:
                0:
                  entityClass: __CLASS__
                  fieldResult:
                    0:
                      name: id
                    1:
                      name: name
                    2:
                      name: status
                    3:
                      name: address.id
                      column: a_id
                    4:
                      name: address.zip
                      column: a_zip
                    5:
                      name: address.city
                      column: a_city
                    6:
                      name: address.country
                      column: a_country
                    


If you retrieve a single entity and if you use the default mapping,
you can use the resultClass attribute instead of resultSetMapping:

.. configuration-block::

    .. code-block:: php

        <?php
        namespace MyProject\Model;
            /**
             * @NamedNativeQueries({
             *      @NamedNativeQuery(
             *          name           = "find-by-id",
             *          resultClass    = "Address",
             *          query          = "SELECT * FROM addresses"
             *      ),
             * })
             */
           class Address
           {
                // ....
           }

    .. code-block:: xml

        <doctrine-mapping>
            <entity name="MyProject\Model\Address">
                <named-native-queries>
                    <named-native-query name="find-by-id" result-class="Address">
                        <query>SELECT * FROM addresses WHERE id = ?</query>
                    </named-native-query>
                </named-native-queries>
            </entity>
        </doctrine-mapping>
    .. code-block:: yaml

        MyProject\Model\Address:
          type: entity
          namedNativeQueries:
            findAll:
              name: findAll
              resultClass: Address
              query: SELECT * FROM addresses


In some of your native queries, you'll have to return scalar values,
for example when building report queries.
You can map them in the @SqlResultsetMapping through @ColumnResult.
You actually can even mix, entities and scalar returns in the same native query (this is probably not that common though).

.. configuration-block::

    .. code-block:: php

        <?php
        namespace MyProject\Model;
            /**
             * @NamedNativeQueries({
             *      @NamedNativeQuery(
             *          name            = "count",
             *          resultSetMapping= "mappingCount",
             *          query           = "SELECT COUNT(*) AS count FROM addresses"
             *      )
             * })
             * @SqlResultSetMappings({
             *      @SqlResultSetMapping(
             *          name    = "mappingCount",
             *          columns = {
             *              @ColumnResult(
             *                  name = "count"
             *              )
             *          }
             *      )
             * })
             */
           class Address
           {
                // ....
           }

    .. code-block:: xml

        <doctrine-mapping>
            <entity name="MyProject\Model\Address">
                <named-native-query name="count" result-set-mapping="mappingCount">
                    <query>SELECT COUNT(*) AS count FROM addresses</query>
                </named-native-query>
                <sql-result-set-mappings>
                    <sql-result-set-mapping name="mappingCount">
                        <column-result name="count"/>
                    </sql-result-set-mapping>
                </sql-result-set-mappings>
            </entity>
        </doctrine-mapping>
    .. code-block:: yaml

        MyProject\Model\Address:
          type: entity
          namedNativeQueries:
            count:
              name: count
              resultSetMapping: mappingCount
              query: SELECT COUNT(*) AS count FROM addresses
          sqlResultSetMappings:
            mappingCount:
              name: mappingCount
              columnResult:
                count:
                  name: count