class_ – The class to be mapped. When using Declarative,
this argument is automatically passed as the declared class
itself.
local_table – The Table or other selectable
to which the class is mapped. May be None if
this mapper inherits from another mapper using single-table
inheritance. When using Declarative, this argument is
automatically passed by the extension, based on what
is configured via the __table__ argument or via the
Table produced as a result of the __tablename__
and Column arguments present.
always_refresh – If True, all query operations for this mapped
class will overwrite all data within object instances that already
exist within the session, erasing any in-memory changes with
whatever information was loaded from the database. Usage of this
flag is highly discouraged; as an alternative, see the method
Query.populate_existing().
allow_partial_pks – Defaults to True. Indicates that a
composite primary key with some NULL values should be considered as
possibly existing within the database. This affects whether a
mapper will assign an incoming row to an existing identity, as well
as if Session.merge() will check the database first for a
particular primary key value. A “partial primary key” can occur if
one has mapped to an OUTER JOIN, for example.
batch – Defaults to True, indicating that save operations
of multiple entities can be batched together for efficiency.
Setting to False indicates
that an instance will be fully saved before saving the next
instance. This is used in the extremely rare case that a
MapperEvents listener requires being called
in between individual row persistence operations.
column_prefix –
A string which will be prepended
to the mapped attribute name when Column
objects are automatically assigned as attributes to the
mapped class. Does not affect explicitly specified
column-based properties.
See the section Naming All Columns with a Prefix for an example.
concrete –
If True, indicates this mapper should use concrete
table inheritance with its parent mapper.
See the section Concrete Table Inheritance for an example.
confirm_deleted_rows –
defaults to True; when a DELETE occurs
of one more rows based on specific primary keys, a warning is
emitted when the number of rows matched does not equal the number
of rows expected. This parameter may be set to False to handle the
case where database ON DELETE CASCADE rules may be deleting some of
those rows automatically. The warning may be changed to an
exception in a future release.
eager_defaults –
if True, the ORM will immediately fetch the
value of server-generated default values after an INSERT or UPDATE,
rather than leaving them as expired to be fetched on next access.
This can be used for event schemes where the server-generated values
are needed immediately before the flush completes. By default,
this scheme will emit an individual SELECT statement per row
inserted or updated, which note can add significant performance
overhead. However, if the
target database supports RETURNING, the default values will
be returned inline with the INSERT or UPDATE statement, which can
greatly enhance performance for an application that needs frequent
access to just-generated server defaults.
Changed in version 0.9.0: The eager_defaults option can now
make use of RETURNING for backends which support it.
exclude_properties –
A list or set of string column names to
be excluded from mapping.
See Mapping a Subset of Table Columns for an example.
extension –
A MapperExtension instance or
list of MapperExtension instances which will be applied
to all operations by this Mapper.
include_properties –
An inclusive list or set of string column
names to map.
See Mapping a Subset of Table Columns for an example.
inherits –
A mapped class or the corresponding Mapper
of one indicating a superclass to which this Mapper
should inherit from. The mapped class here must be a subclass
of the other mapper’s class. When using Declarative, this argument
is passed automatically as a result of the natural class
hierarchy of the declared classes.
inherit_condition – For joined table inheritance, a SQL
expression which will
define how the two tables are joined; defaults to a natural join
between the two tables.
inherit_foreign_keys – When inherit_condition is used and
the columns present are missing a ForeignKey
configuration, this parameter can be used to specify which columns
are “foreign”. In most cases can be left as None.
legacy_is_orphan –
Boolean, defaults to False.
When True, specifies that “legacy” orphan consideration
is to be applied to objects mapped by this mapper, which means
that a pending (that is, not persistent) object is auto-expunged
from an owning Session only when it is de-associated
from all parents that specify a delete-orphan cascade towards
this mapper. The new default behavior is that the object is
auto-expunged when it is de-associated with any of its parents
that specify delete-orphan cascade. This behavior is more
consistent with that of a persistent object, and allows behavior to
be consistent in more scenarios independently of whether or not an
orphanable object has been flushed yet or not.
See the change note and example at The consideration of a “pending” object as an “orphan” has been made more aggressive
for more detail on this change.
non_primary –
Specify that this Mapper is in addition
to the “primary” mapper, that is, the one used for persistence.
The Mapper created here may be used for ad-hoc
mapping of the class to an alternate selectable, for loading
only.
Deprecated since version 1.3: The mapper.non_primary parameter is deprecated, and will be removed in a future release. The functionality of non primary mappers is now better suited using the AliasedClass construct, which can also be used as the target of a relationship() in 1.3.
Mapper.non_primary is not an often used option, but
is useful in some specific relationship() cases.
See also
relationship_non_primary_mapper
order_by –
A single Column or list of Column
objects for which selection operations should use as the default
ordering for entities. By default mappers have no pre-defined
ordering.
Deprecated since version 1.1: The mapper.order_by parameter is deprecated, and will be removed in a future release. Use Query.order_by() to determine the ordering of a result set.
passive_deletes –
Indicates DELETE behavior of foreign key
columns when a joined-table inheritance entity is being deleted.
Defaults to False for a base mapper; for an inheriting mapper,
defaults to False unless the value is set to True
on the superclass mapper.
When True, it is assumed that ON DELETE CASCADE is configured
on the foreign key relationships that link this mapper’s table
to its superclass table, so that when the unit of work attempts
to delete the entity, it need only emit a DELETE statement for the
superclass table, and not this table.
When False, a DELETE statement is emitted for this mapper’s
table individually. If the primary key attributes local to this
table are unloaded, then a SELECT must be emitted in order to
validate these attributes; note that the primary key columns
of a joined-table subclass are not part of the “primary key” of
the object as a whole.
Note that a value of True is always forced onto the
subclass mappers; that is, it’s not possible for a superclass
to specify passive_deletes without this taking effect for
all subclass mappers.
passive_updates –
Indicates UPDATE behavior of foreign key
columns when a primary key column changes on a joined-table
inheritance mapping. Defaults to True.
When True, it is assumed that ON UPDATE CASCADE is configured on
the foreign key in the database, and that the database will handle
propagation of an UPDATE from a source column to dependent columns
on joined-table rows.
When False, it is assumed that the database does not enforce
referential integrity and will not be issuing its own CASCADE
operation for an update. The unit of work process will
emit an UPDATE statement for the dependent columns during a
primary key change.
polymorphic_load –
- Specifies “polymorphic loading” behavior
for a subclass in an inheritance hierarchy (joined and single
table inheritance only). Valid values are:
“‘inline’” - specifies this class should be part of the
“with_polymorphic” mappers, e.g. its columns will be included
in a SELECT query against the base.
“‘selectin’” - specifies that when instances of this class
are loaded, an additional SELECT will be emitted to retrieve
the columns specific to this subclass. The SELECT uses
IN to fetch multiple subclasses at once.
polymorphic_on –
Specifies the column, attribute, or
SQL expression used to determine the target class for an
incoming row, when inheriting classes are present.
This value is commonly a Column object that’s
present in the mapped Table:
class Employee(Base):
__tablename__ = 'employee'
id = Column(Integer, primary_key=True)
discriminator = Column(String(50))
__mapper_args__ = {
"polymorphic_on":discriminator,
"polymorphic_identity":"employee"
}
It may also be specified
as a SQL expression, as in this example where we
use the case() construct to provide a conditional
approach:
class Employee(Base):
__tablename__ = 'employee'
id = Column(Integer, primary_key=True)
discriminator = Column(String(50))
__mapper_args__ = {
"polymorphic_on":case([
(discriminator == "EN", "engineer"),
(discriminator == "MA", "manager"),
], else_="employee"),
"polymorphic_identity":"employee"
}
It may also refer to any attribute
configured with column_property(), or to the
string name of one:
class Employee(Base):
__tablename__ = 'employee'
id = Column(Integer, primary_key=True)
discriminator = Column(String(50))
employee_type = column_property(
case([
(discriminator == "EN", "engineer"),
(discriminator == "MA", "manager"),
], else_="employee")
)
__mapper_args__ = {
"polymorphic_on":employee_type,
"polymorphic_identity":"employee"
}
When setting polymorphic_on to reference an
attribute or expression that’s not present in the
locally mapped Table, yet the value
of the discriminator should be persisted to the database,
the value of the
discriminator is not automatically set on new
instances; this must be handled by the user,
either through manual means or via event listeners.
A typical approach to establishing such a listener
looks like:
from sqlalchemy import event
from sqlalchemy.orm import object_mapper
@event.listens_for(Employee, "init", propagate=True)
def set_identity(instance, *arg, **kw):
mapper = object_mapper(instance)
instance.discriminator = mapper.polymorphic_identity
Where above, we assign the value of polymorphic_identity
for the mapped class to the discriminator attribute,
thus persisting the value to the discriminator column
in the database.
Warning
Currently, only one discriminator column may be set, typically
on the base-most class in the hierarchy. “Cascading” polymorphic
columns are not yet supported.
polymorphic_identity – Specifies the value which
identifies this particular class as returned by the
column expression referred to by the polymorphic_on
setting. As rows are received, the value corresponding
to the polymorphic_on column expression is compared
to this value, indicating which subclass should
be used for the newly reconstructed object.
properties – A dictionary mapping the string names of object
attributes to MapperProperty instances, which define the
persistence behavior of that attribute. Note that Column
objects present in
the mapped Table are automatically placed into
ColumnProperty instances upon mapping, unless overridden.
When using Declarative, this argument is passed automatically,
based on all those MapperProperty instances declared
in the declared class body.
primary_key – A list of Column objects which define
the primary key to be used against this mapper’s selectable unit.
This is normally simply the primary key of the local_table, but
can be overridden here.
version_id_col –
A Column
that will be used to keep a running version id of rows
in the table. This is used to detect concurrent updates or
the presence of stale data in a flush. The methodology is to
detect if an UPDATE statement does not match the last known
version id, a
StaleDataError exception is
thrown.
By default, the column must be of Integer type,
unless version_id_generator specifies an alternative version
generator.
version_id_generator –
Define how new version ids should
be generated. Defaults to None, which indicates that
a simple integer counting scheme be employed. To provide a custom
versioning scheme, provide a callable function of the form:
def generate_version(version):
return next_version
Alternatively, server-side versioning functions such as triggers,
or programmatic versioning schemes outside of the version id
generator may be used, by specifying the value False.
Please see Server Side Version Counters for a discussion
of important points when using this option.
New in version 0.9.0: version_id_generator supports
server-side version number generation.
with_polymorphic –
A tuple in the form (<classes>,
<selectable>) indicating the default style of “polymorphic”
loading, that is, which tables are queried at once. <classes> is
any single or list of mappers and/or classes indicating the
inherited classes that should be loaded at once. The special value
'*' may be used to indicate all descending classes should be
loaded immediately. The second tuple argument <selectable>
indicates a selectable that will be used to query for multiple
classes.