class Athena::ORM::Query::ResultSetMapping
inherits Reference
#
Describes how the columns of a native SQL query's result map to entities, for use with AORM::NativeQuery.
Each entity in the result is registered under an alias with #add_entity_result.
Its columns are then mapped to fields of that entity with #add_field_result.
A column is referenced by its name in the result, which is its alias if the SQL gives it one.
rsm = AORM::Query::ResultSetMapping.new
rsm.add_entity_result User, "u"
rsm.add_field_result "u", "id", "id"
rsm.add_field_result "u", "user_name", "username"
em.create_native_query "SELECT u.id, u.username AS user_name FROM users u", rsm
Columns of the result that aren't mapped are ignored.
Warning
Entities are instantiated without calling their constructor, so map a column for every field the entity needs. A field without a column in the result keeps its instance variable's default value, or is left uninitialized if it has none, in which case reading it is unsafe unless it's nilable.
Associations#
The owning side of a ToOne association is hydrated from its foreign key column.
Map it with #add_meta_result, using the join column's name as the field name:
rsm.add_meta_result "u", "avatar_id", "avatar_id"
The related entity is then resolved as it is when loaded through the entity manager: taken from the identity map, wrapped in an unloaded AORM::Proxy for proxy-typed fields, or otherwise loaded once the result has been hydrated.
Without its foreign key column, the association is left nil.
The inverse side of a ToOne association, and collections, don't need any columns. Inverse ToOne associations are loaded once the result has been hydrated, and collections are loaded lazily when first used.
Todo
Only a single entity result is supported so far.
Executing a query whose mapping has more than one entity result, or any #add_joined_entity_result or #add_scalar_result, raises.
Methods#
#add_entity_result(entity_class : AORM::Entity.class, alias_name : String, result_alias : String | Nil = nil) : self#
Adds an entity result of entity_class, referenced by alias_name in the rest of the mapping.
Todo
result_alias names the entity within a result that mixes entities and scalar values, which isn't supported yet.
#add_field_result(alias_name : String, column_name : String, field_name : String, declaring_class : AORM::Entity.class | Nil = nil) : self#
Maps the result column column_name to the field field_name of the entity under alias_name.
The value is read through the field's AORM::Types::Type, as it is when loaded through the entity manager.
declaring_class is the entity class declaring the field, which defaults to the class registered under alias_name.
#add_index_by(alias_name : String, field_name : String) : self#
Indexes the results of the entity under alias_name by its field field_name, which must already be mapped with #add_field_result.
Todo
Indexing results isn't supported yet; the configured index has no effect.
#add_index_by_column(alias_name : String, column_name : String) : self#
Indexes the results of the entity under alias_name by the result column column_name.
Todo
Indexing results isn't supported yet; the configured index has no effect.
#add_joined_entity_result(entity_class : AORM::Entity.class, alias_name : String, parent_alias : String, relation : String) : self#
Adds an entity result of entity_class, hydrated from the same rows as the entity under parent_alias, and assigned to its relation association.
Todo
Joined entity results aren't supported yet; executing a query with one raises.
#add_meta_result(alias_name : String, column_name : String, field_name : String, is_identifier : Bool = false, type : String | Nil = nil) : self#
Maps the result column column_name to the meta field field_name of the entity under alias_name.
Meta fields are columns of the entity's table that aren't mapped to a field, such as the foreign key column of a ToOne association, whose field_name is the join column's name.
is_identifier marks a column that is part of the entity's identifier, and type names the AORM::Types::Type to read the value through, which is otherwise read as returned by the driver.
#add_scalar_result(column_name : String, result_alias : String | Int32, type : String = "string") : self#
Maps the result column column_name to a scalar value named result_alias, read through the AORM::Types::Type named type.
Scalar results are columns that aren't entity fields, such as aggregates like COUNT(*).
Todo
Scalar results aren't supported yet; executing a query with one raises.