SQLAlchemy 1.4 Documentation
SQLAlchemy ORM
- ORM Quick Start
- Object Relational Tutorial (1.x API)
- ORM Mapped Class Configuration
- ORM Mapped Class Overview¶
- Mapping Classes with Declarative
- Integration with dataclasses and attrs
- Mapping Columns and Expressions
- Mapping Class Inheritance Hierarchies
- Non-Traditional Mappings
- Configuring a Version Counter
- Class Mapping API
- Relationship Configuration
- Querying Data, Loading Objects
- Using the Session
- Events and Internals
- ORM Extensions
- ORM Examples
Project Versions
ORM Mapped Class Overview¶
Overview of ORM class mapping configuration.
For readers new to the SQLAlchemy ORM and/or new to Python in general, it’s recommended to browse through the ORM Quick Start and preferably to work through the SQLAlchemy 1.4 / 2.0 Tutorial, where ORM configuration is first introduced at Defining Table Metadata with the ORM.
ORM Mapping Styles¶
SQLAlchemy features two distinct styles of mapper configuration, which then feature further sub-options for how they are set up. The variability in mapper styles is present to suit a varied list of developer preferences, including the degree of abstraction of a user-defined class from how it is to be mapped to relational schema tables and columns, what kinds of class hierarchies are in use, including whether or not custom metaclass schemes are present, and finally if there are other class-instrumentation approaches present such as if Python dataclasses are in use simultaneously.
In modern SQLAlchemy, the difference between these styles is mostly
superficial; when a particular SQLAlchemy configurational style is used to
express the intent to map a class, the internal process of mapping the class
proceeds in mostly the same way for each, where the end result is always a
user-defined class that has a Mapper
configured against a
selectable unit, typically represented by a Table
object, and
the class itself has been instrumented to include behaviors linked to
relational operations both at the level of the class as well as on instances of
that class. As the process is basically the same in all cases, classes mapped
from different styles are always fully interoperable with each other.
The original mapping API is commonly referred to as “classical” style, whereas the more automated style of mapping is known as “declarative” style. SQLAlchemy now refers to these two mapping styles as imperative mapping and declarative mapping.
Regardless of what style of mapping used, all ORM mappings as of SQLAlchemy 1.4
originate from a single object known as registry
, which is a
registry of mapped classes. Using this registry, a set of mapper configurations
can be finalized as a group, and classes within a particular registry may refer
to each other by name within the configurational process.
Changed in version 1.4: Declarative and classical mapping are now referred
to as “declarative” and “imperative” mapping, and are unified internally,
all originating from the registry
construct that represents
a collection of related mappings.
Declarative Mapping¶
The Declarative Mapping is the typical way that
mappings are constructed in modern SQLAlchemy. The most common pattern
is to first construct a base class using the declarative_base()
function, which will apply the declarative mapping process to all subclasses
that derive from it. Below features a declarative base which is then
used in a declarative table mapping:
from sqlalchemy import Column, Integer, String, ForeignKey
from sqlalchemy.orm import declarative_base
# declarative base class
Base = declarative_base()
# an example mapping using the base
class User(Base):
__tablename__ = "user"
id = Column(Integer, primary_key=True)
name = Column(String)
fullname = Column(String)
nickname = Column(String)
Above, the declarative_base()
callable returns a new base class from
which new classes to be mapped may inherit from, as above a new mapped
class User
is constructed.
The base class refers to a registry
object that maintains a
collection of related mapped classes. The declarative_base()
function is in fact shorthand for first creating the registry with the
registry
constructor, and then generating a base class using the
registry.generate_base()
method:
from sqlalchemy.orm import registry
# equivalent to Base = declarative_base()
mapper_registry = registry()
Base = mapper_registry.generate_base()
The major Declarative mapping styles are further detailed in the following sections:
Using a Generated Base Class - declarative mapping using a base class generated by the
registry
object.Declarative Mapping using a Decorator (no declarative base) - declarative mapping using a decorator, rather than a base class.
Within the scope of a Declarative mapped class, there are also two varieties
of how the Table
metadata may be declared. These include:
Declarative Table - individual
Column
definitions are combined with a table name and additional arguments, where the Declarative mapping process will construct aTable
object to be mapped.Declarative with Imperative Table (a.k.a. Hybrid Declarative) - Instead of specifying table name and attributes separately, an explicitly constructed
Table
object is associated with a class that is otherwise mapped declaratively. This style of mapping is a hybrid of “declarative” and “imperative” mapping.
Documentation for Declarative mapping continues at Mapping Classes with Declarative.
Imperative Mapping¶
An imperative or classical mapping refers to the configuration of a
mapped class using the registry.map_imperatively()
method,
where the target class does not include any declarative class attributes.
The “map imperative” style has historically been achieved using the
mapper()
function directly, however this function now expects
that a sqlalchemy.orm.registry()
is present.
Deprecated since version 1.4: Using the mapper()
function directly to
achieve a classical mapping directly is deprecated. The
registry.map_imperatively()
method retains the identical
functionality while also allowing for string-based resolution of
other mapped classes from within the registry.
In “classical” form, the table metadata is created separately with the
Table
construct, then associated with the User
class via
the registry.map_imperatively()
method:
from sqlalchemy import Table, Column, Integer, String, ForeignKey
from sqlalchemy.orm import registry
mapper_registry = registry()
user_table = Table(
"user",
mapper_registry.metadata,
Column("id", Integer, primary_key=True),
Column("name", String(50)),
Column("fullname", String(50)),
Column("nickname", String(12)),
)
class User:
pass
mapper_registry.map_imperatively(User, user_table)
Information about mapped attributes, such as relationships to other classes, are provided
via the properties
dictionary. The example below illustrates a second Table
object, mapped to a class called Address
, then linked to User
via relationship()
:
address = Table(
"address",
metadata_obj,
Column("id", Integer, primary_key=True),
Column("user_id", Integer, ForeignKey("user.id")),
Column("email_address", String(50)),
)
mapper_registry.map_imperatively(
User,
user,
properties={
"addresses": relationship(Address, backref="user", order_by=address.c.id)
},
)
mapper_registry.map_imperatively(Address, address)
When using classical mappings, classes must be provided directly without the benefit
of the “string lookup” system provided by Declarative. SQL expressions are typically
specified in terms of the Table
objects, i.e. address.c.id
above
for the Address
relationship, and not Address.id
, as Address
may not
yet be linked to table metadata, nor can we specify a string here.
Some examples in the documentation still use the classical approach, but note that
the classical as well as Declarative approaches are fully interchangeable. Both
systems ultimately create the same configuration, consisting of a Table
,
user-defined class, linked together with a mapper()
. When we talk about
“the behavior of mapper()
”, this includes when using the Declarative system
as well - it’s still used, just behind the scenes.
Mapped Class Essential Components¶
With all mapping forms, the mapping of the class can be
configured in many ways by passing construction arguments that become
part of the Mapper
object. The function which ultimately
receives these arguments is the mapper()
function, which are delivered
to it originating from one of the front-facing mapping functions defined
on the registry
object.
There are four general classes of configuration information that the
mapper()
function looks for:
The class to be mapped¶
This is a class that we construct in our application.
There are generally no restrictions on the structure of this class. [1]
When a Python class is mapped, there can only be one Mapper
object for the class. [2]
When mapping with the declarative mapping
style, the class to be mapped is either a subclass of the declarative base class,
or is handled by a decorator or function such as registry.mapped()
.
When mapping with the imperative style, the
class is passed directly as the
map_imperatively.class_
argument.
The table, or other from clause object¶
In the vast majority of common cases this is an instance of
Table
. For more advanced use cases, it may also refer
to any kind of FromClause
object, the most common
alternative objects being the Subquery
and Join
object.
When mapping with the declarative mapping
style, the subject table is either generated by the declarative system based
on the __tablename__
attribute and the Column
objects
presented, or it is established via the __table__
attribute. These
two styles of configuration are presented at
Declarative Table and Declarative with Imperative Table (a.k.a. Hybrid Declarative).
When mapping with the imperative style, the
subject table is passed positionally as the
map_imperatively.local_table
argument.
In contrast to the “one mapper per class” requirement of a mapped class,
the Table
or other FromClause
object that
is the subject of the mapping may be associated with any number of mappings.
The Mapper
applies modifications directly to the user-defined
class, but does not modify the given Table
or other
FromClause
in any way.
The properties dictionary¶
This is a dictionary of all of the attributes
that will be associated with the mapped class. By default, the
Mapper
generates entries for this dictionary derived from the
given Table
, in the form of ColumnProperty
objects which each refer to an individual Column
of the
mapped table. The properties dictionary will also contain all the other
kinds of MapperProperty
objects to be configured, most
commonly instances generated by the relationship()
construct.
When mapping with the declarative mapping style, the properties dictionary is generated by the declarative system by scanning the class to be mapped for appropriate attributes. See the section Defining Mapped Properties with Declarative for notes on this process.
When mapping with the imperative style, the
properties dictionary is passed directly as the properties
argument
to registry.map_imperatively()
, which will pass it along to the
mapper.properties
parameter.
Other mapper configuration parameters¶
When mapping with the declarative mapping
style, additional mapper configuration arguments are configured via the
__mapper_args__
class attribute. Examples of use are available
at Mapper Configuration Options with Declarative.
When mapping with the imperative style,
keyword arguments are passed to the to registry.map_imperatively()
method which passes them along to the mapper()
function.
The full range of parameters accepted are documented at mapper
.
Mapped Class Behavior¶
Across all styles of mapping using the registry
object,
the following behaviors are common:
Default Constructor¶
The registry
applies a default constructor, i.e. __init__
method, to all mapped classes that don’t explicitly have their own
__init__
method. The behavior of this method is such that it provides
a convenient keyword constructor that will accept as optional keyword arguments
all the attributes that are named. E.g.:
from sqlalchemy.orm import declarative_base
Base = declarative_base()
class User(Base):
__tablename__ = "user"
id = Column(...)
name = Column(...)
fullname = Column(...)
An object of type User
above will have a constructor which allows
User
objects to be created as:
u1 = User(name="some name", fullname="some fullname")
The above constructor may be customized by passing a Python callable to
the registry.constructor
parameter which provides the
desired default __init__()
behavior.
The constructor also applies to imperative mappings:
from sqlalchemy.orm import registry
mapper_registry = registry()
user_table = Table(
"user",
mapper_registry.metadata,
Column("id", Integer, primary_key=True),
Column("name", String(50)),
)
class User:
pass
mapper_registry.map_imperatively(User, user_table)
The above class, mapped imperatively as described at Imperative Mapping,
will also feature the default constructor associated with the registry
.
New in version 1.4: classical mappings now support a standard configuration-level
constructor when they are mapped via the registry.map_imperatively()
method.
Runtime Introspection of Mapped classes, Instances and Mappers¶
A class that is mapped using registry
will also feature a few
attributes that are common to all mappings:
The
__mapper__
attribute will refer to theMapper
that is associated with the class:mapper = User.__mapper__
This
Mapper
is also what’s returned when using theinspect()
function against the mapped class:from sqlalchemy import inspect mapper = inspect(User)
The
__table__
attribute will refer to theTable
, or more generically to theFromClause
object, to which the class is mapped:table = User.__table__
This
FromClause
is also what’s returned when using theMapper.local_table
attribute of theMapper
:table = inspect(User).local_table
For a single-table inheritance mapping, where the class is a subclass that does not have a table of its own, the
Mapper.local_table
attribute as well as the.__table__
attribute will beNone
. To retrieve the “selectable” that is actually selected from during a query for this class, this is available via theMapper.selectable
attribute:table = inspect(User).selectable
Inspection of Mapper objects¶
As illustrated in the previous section, the Mapper
object is
available from any mapped class, regardless of method, using the
Runtime Inspection API system. Using the
inspect()
function, one can acquire the Mapper
from a
mapped class:
>>> from sqlalchemy import inspect
>>> insp = inspect(User)
Detailed information is available including Mapper.columns
:
>>> insp.columns
<sqlalchemy.util._collections.OrderedProperties object at 0x102f407f8>
This is a namespace that can be viewed in a list format or via individual names:
>>> list(insp.columns)
[Column('id', Integer(), table=<user>, primary_key=True, nullable=False), Column('name', String(length=50), table=<user>), Column('fullname', String(length=50), table=<user>), Column('nickname', String(length=50), table=<user>)]
>>> insp.columns.name
Column('name', String(length=50), table=<user>)
Other namespaces include Mapper.all_orm_descriptors
, which includes all mapped
attributes as well as hybrids, association proxies:
>>> insp.all_orm_descriptors
<sqlalchemy.util._collections.ImmutableProperties object at 0x1040e2c68>
>>> insp.all_orm_descriptors.keys()
['fullname', 'nickname', 'name', 'id']
As well as Mapper.column_attrs
:
>>> list(insp.column_attrs)
[<ColumnProperty at 0x10403fde0; id>, <ColumnProperty at 0x10403fce8; name>, <ColumnProperty at 0x1040e9050; fullname>, <ColumnProperty at 0x1040e9148; nickname>]
>>> insp.column_attrs.name
<ColumnProperty at 0x10403fce8; name>
>>> insp.column_attrs.name.expression
Column('name', String(length=50), table=<user>)
See also
Inspection of Mapped Instances¶
The inspect()
function also provides information about instances
of a mapped class. When applied to an instance of a mapped class, rather
than the class itself, the object returned is known as InstanceState
,
which will provide links to not only the Mapper
in use by the
class, but also a detailed interface that provides information on the state
of individual attributes within the instance including their current value
and how this relates to what their database-loaded value is.
Given an instance of the User
class loaded from the database:
>>> u1 = session.scalars(select(User)).first()
The inspect()
function will return to us an InstanceState
object:
>>> insp = inspect(u1)
>>> insp
<sqlalchemy.orm.state.InstanceState object at 0x7f07e5fec2e0>
With this object we can see elements such as the Mapper
:
>>> insp.mapper
<Mapper at 0x7f07e614ef50; User>
The Session
to which the object is attached, if any:
>>> insp.session
<sqlalchemy.orm.session.Session object at 0x7f07e614f160>
Information about the current persistence state for the object:
>>> insp.persistent
True
>>> insp.pending
False
Attribute state information such as attributes that have not been loaded or
lazy loaded (assume addresses
refers to a relationship()
on the mapped class to a related class):
>>> insp.unloaded
{'addresses'}
Information regarding the current in-Python status of attributes, such as attributes that have not been modified since the last flush:
>>> insp.unmodified
{'nickname', 'name', 'fullname', 'id'}
as well as specific history on modifications to attributes since the last flush:
>>> insp.attrs.nickname.value
'nickname'
>>> u1.nickname = "new nickname"
>>> insp.attrs.nickname.history
History(added=['new nickname'], unchanged=(), deleted=['nickname'])
flambé! the dragon and The Alchemist image designs created and generously donated by Rotem Yaari.
Created using Sphinx 7.2.6. Documentation last generated: Wed 30 Oct 2024 02:18:58 PM EDT