diff --git a/en/reference/annotations-reference.rst b/en/reference/annotations-reference.rst index 1760ca731..0383831ef 100644 --- a/en/reference/annotations-reference.rst +++ b/en/reference/annotations-reference.rst @@ -8,10 +8,13 @@ Index ----- - :ref:`@Column ` +- :ref:`@ColumnResult ` - :ref:`@ChangeTrackingPolicy ` - :ref:`@DiscriminatorColumn ` - :ref:`@DiscriminatorMap ` - :ref:`@Entity ` +- :ref:`@EntityResult ` +- :ref:`@FieldResult ` - :ref:`@GeneratedValue ` - :ref:`@HasLifecycleCallbacks ` - :ref:`@Index ` @@ -22,6 +25,7 @@ Index - :ref:`@ManyToOne ` - :ref:`@ManyToMany ` - :ref:`@MappedSuperclass ` +- :ref:`@NamedNativeQuery ` - :ref:`@OneToOne ` - :ref:`@OneToMany ` - :ref:`@OrderBy ` @@ -33,6 +37,7 @@ Index - :ref:`@PreRemove ` - :ref:`@PreUpdate ` - :ref:`@SequenceGenerator ` +- :ref:`@SqlResultSetMapping ` - :ref:`@Table ` - :ref:`@UniqueConstraint ` - :ref:`@Version ` @@ -109,6 +114,17 @@ Examples: */ protected $height; +.. _annref_column_result: + +@ColumnResult +~~~~~~~~~~~~~~ +References name of a column in the SELECT clause of a SQL query. +Scalar result types can be included in the query result by specifying this annotation in the metadata. + +Required attributes: + +- **name**: The name of a column in the SELECT clause of a SQL query + .. _annref_changetrackingpolicy: @ChangeTrackingPolicy @@ -219,6 +235,39 @@ Example: //... } +.. _annref_entity_result: + +@EntityResult +~~~~~~~~~~~~~~ +References an entity in the SELECT clause of a SQL query. +If this annotation is used, the SQL statement should select all of the columns that are mapped to the entity object. +This should include foreign key columns to related entities. +The results obtained when insufficient data is available are undefined. + +Required attributes: + +- **entityClass**: The class of the result. + +Optional attributes: + +- **fields**: Array of @FieldResult, Maps the columns specified in the SELECT list of the query to the properties or fields of the entity class. +- **discriminatorColumn**: Specifies the column name of the column in the SELECT list that is used to determine the type of the entity instance. + +.. _annref_field_result: + +@FieldResult +~~~~~~~~~~~~~ +Is used to map the columns specified in the SELECT list of the query to the properties or fields of the entity class. + +Required attributes: + +- **name**: Name of the persistent field or property of the class. + + +Optional attributes: + +- **column**: Name of the column in the SELECT clause. + .. _annref_generatedvalue: @GeneratedValue @@ -597,6 +646,77 @@ Example: // ... fields and methods } +.. _annref_named_native_query: + +@NamedNativeQuery +~~~~~~~~~~~~~~~~~ +Is used to specify a native SQL named query. +The NamedNativeQuery annotation can be applied to an entity or mapped superclass. + +Required attributes: + +- **name**: The name used to refer to the query with the EntityManager methods that create query objects. +- **query**: The SQL query string. + + +Optional attributes: + +- **resultClass**: The class of the result. +- **sqlResultSetMapping**: The name of a SqlResultSetMapping, as defined in metadata. + + +Example: + +.. code-block:: php + + + + + + 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 + + + + + + + + + + + + + + + + + + + + .. 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 an 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 a 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 + + + + + + SELECT * FROM addresses + + + + + + + + + + .. 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 + + + + + + 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 = ? + + + + + + + + + + + + + + + + + + .. 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 + + + + + + SELECT * FROM addresses WHERE id = ? + + + + + .. 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 + + + + + SELECT COUNT(*) AS count FROM addresses + + + + + + + + + .. 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 \ No newline at end of file