
this is the old content for reference while the new section is written

remove when complete


The ORM loader option system supports the concept of "wildcard" loader options,
in which a loader option can be passed an asterisk ``"*"`` to indicate that
a particular option should apply to all applicable attributes of a mapped
class.   Such as, if we wanted to load the ``Book`` class but only
the "summary" and "excerpt" columns, we could say::

    from sqlalchemy.orm import defer
    from sqlalchemy.orm import undefer
    from sqlalchemy import select

    stmt = select(Book).options(
        defer('*'), undefer(Book.summary), undefer(Book.excerpt))

    book_objs = session.scalars(stmt).all()

Above, the :func:`.defer` option is applied using a wildcard to all column
attributes on the ``Book`` class.   Then, the :func:`.undefer` option is used
against the "summary" and "excerpt" fields so that they are the  only columns
loaded up front. A query for the above entity will include only the "summary"
and "excerpt" fields in the SELECT, along with the primary key columns which
are always used by the ORM.

A similar function is available with less verbosity by using the
:func:`_orm.load_only` option.  This is a so-called **exclusionary** option
which will apply deferred behavior to all column attributes except those
that are named::

    from sqlalchemy.orm import load_only
    from sqlalchemy import select

    stmt = select(Book).options(load_only(Book.summary, Book.excerpt))

    book_objs = session.scal

Load Only and Wildcard Options
------------------------------

The ORM loader option system supports the concept of "wildcard" loader options,
in which a loader option can be passed an asterisk ``"*"`` to indicate that
a particular option should apply to all applicable attributes of a mapped
class.   Such as, if we wanted to load the ``Book`` class but only
the "summary" and "excerpt" columns, we could say::

    from sqlalchemy.orm import defer
    from sqlalchemy.orm import undefer
    from sqlalchemy import select

    stmt = select(Book).options(
        defer('*'), undefer(Book.summary), undefer(Book.excerpt))

    book_objs = session.scalars(stmt).all()

Above, the :func:`.defer` option is applied using a wildcard to all column
attributes on the ``Book`` class.   Then, the :func:`.undefer` option is used
against the "summary" and "excerpt" fields so that they are the  only columns
loaded up front. A query for the above entity will include only the "summary"
and "excerpt" fields in the SELECT, along with the primary key columns which
are always used by the ORM.

A similar function is available with less verbosity by using the
:func:`_orm.load_only` option.  This is a so-called **exclusionary** option
which will apply deferred behavior to all column attributes except those
that are named::

    from sqlalchemy.orm import load_only
    from sqlalchemy import select

    stmt = select(Book).options(load_only(Book.summary, Book.excerpt))

    book_objs = session.scalars(stmt).all()

Wildcard and Exclusionary Options with Multiple-Entity Queries
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Wildcard options and exclusionary options such as :func:`.load_only` may
only be applied to a single entity at a time within a statement.
To suit the less common case where a statement is returning multiple
primary entities at once, a special calling style may be required in order
to apply a wildcard or exclusionary option to a specific entity, which is to use the
:class:`_orm.Load` object to indicate the starting entity for a deferral option.
Such as, if we were loading ``Book`` and ``Author`` at once, the ORM
will raise an informative error if we try to apply :func:`.load_only` to
both at once.  Instead, we may use :class:`_orm.Load` to apply the option
to either or both of ``Book`` and ``Author`` individually::

    from sqlalchemy.orm import Load

    stmt = select(Book, Author).join(Book.author)
    stmt = stmt.options(
                Load(Book).load_only(Book.summary, Book.excerpt)
            )
    book_author_objs = session.execute(stmt).all()

Above, :class:`_orm.Load` is used in conjunction with the exclusionary option
:func:`.load_only` so that the deferral of all other columns only takes
place for the ``Book`` class and not the ``Author`` class.   Again,
the ORM should raise an informative error message when
the above calling style is actually required that describes those cases
where explicit use of :class:`_orm.Load` is needed.
ars(stmt).all()

Wildcard and Exclusionary Options with Multiple-Entity Queries
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Wildcard options and exclusionary options such as :func:`.load_only` may
only be applied to a single entity at a time within a statement.
To suit the less common case where a statement is returning multiple
primary entities at once, a special calling style may be required in order
to apply a wildcard or exclusionary option to a specific entity, which is to use the
:class:`_orm.Load` object to indicate the starting entity for a deferral option.
Such as, if we were loading ``Book`` and ``Author`` at once, the ORM
will raise an informative error if we try to apply :func:`.load_only` to
both at once.  Instead, we may use :class:`_orm.Load` to apply the option
to either or both of ``Book`` and ``Author`` individually::

    from sqlalchemy.orm import Load

    stmt = select(Book, Author).join(Book.author)
    stmt = stmt.options(
                Load(Book).load_only(Book.summary, Book.excerpt)
            )
    book_author_objs = session.execute(stmt).all()

Above, :class:`_orm.Load` is used in conjunction with the exclusionary option
:func:`.load_only` so that the deferral of all other columns only takes
place for the ``Book`` class and not the ``Author`` class.   Again,
the ORM should raise an informative error message when
the above calling style is actually required that describes those cases
where explicit use of :class:`_orm.Load` is needed.




Deferred Column Loading
=======================

Deferred column loading allows particular columns of a table be loaded only
upon direct access, instead of when the entity is queried using
:class:`_sql.Select` or :class:`_orm.Query`.  This feature is useful when one wants to avoid
loading a large text or binary field into memory when it's not needed.

Configuring Deferred Loading at Mapper Configuration Time
---------------------------------------------------------

First introduced at :ref:`orm_declarative_column_options` and
:ref:`orm_imperative_table_column_options`, the
:paramref:`_orm.mapped_column.deferred` parameter of :func:`_orm.mapped_column`,
as well as the :func:`_orm.deferred` ORM function may be used to indicate mapped
columns as "deferred" at mapper configuration time.  With this configuration,
the target columns will not be loaded in SELECT statements by default, and
will instead only be loaded "lazily" when their corresponding attribute is
accessed on a mapped instance.   Deferral can be configured for individual
columns or groups of columns that will load together when any of them
are accessed.

In the example below, using :ref:`Declarative Table <orm_declarative_table>`
configuration, we define a mapping that will load each of
``.excerpt`` and ``.photo`` in separate, individual-row SELECT statements when each
attribute is first referenced on the individual object instance::

    from sqlalchemy import Text
    from sqlalchemy.orm import DeclarativeBase
    from sqlalchemy.orm import Mapped
    from sqlalchemy.orm import mapped_column

    class Base(DeclarativeBase):
        pass

    class Book(Base):
        __tablename__ = 'book'

        book_id: Mapped[int] = mapped_column(primary_key=True)
        title: Mapped[str]
        summary: Mapped[str]
        excerpt: Mapped[str] = mapped_column(Text, deferred=True)
        photo: Mapped[bytes] = mapped_column(deferred=True)

A :func:`_sql.select` construct for the above mapping will not include
``excerpt`` and ``photo`` by default::

    >>> from sqlalchemy import select
    >>> print(select(Book))
    SELECT book.book_id, book.title, book.summary
    FROM book

When an object of type ``Book`` is loaded by the ORM, accessing the
``.excerpt`` or ``.photo`` attributes will instead :term:`lazy load` the
data from each column using a new SQL statement.

When using :ref:`Imperative Table <orm_imperative_table_configuration>`
or fully :ref:`Imperative <orm_imperative_mapping>` configuration, the
:func:`_orm.deferred` construct should be used instead, passing the
target :class:`_schema.Column` object to be mapped as the argument::

    from sqlalchemy import Column, Integer, LargeBinary, String, Table, Text
    from sqlalchemy.orm import DeclarativeBase
    from sqlalchemy.orm import deferred


    class Base(DeclarativeBase):
        pass


    book = Table(
        "book",
        Base.metadata,
        Column("book_id", Integer, primary_key=True),
        Column("title", String),
        Column("summary", String),
        Column("excerpt", Text),
        Column("photo", LargeBinary),
    )


    class Book(Base):
        __table__ = book

        excerpt = deferred(book.c.excerpt)
        photo = deferred(book.c.photo)


Deferred columns can be associated with a "group" name, so that they load
together when any of them are first accessed.  When using
:func:`_orm.mapped_column`, this group name may be specified using the
:paramref:`_orm.mapped_column.deferred_group` parameter, which implies
:paramref:`_orm.mapped_column.deferred` if that parameter is not already
set.  When using :func:`_orm.deferred`, the :paramref:`_orm.deferred.group`
parameter may be used.

The example below defines a mapping with a ``photos`` deferred group. When
an attribute within the group ``.photo1``, ``.photo2``, ``.photo3``
is accessed on an instance of ``Book``, all three columns will be loaded in one SELECT
statement. The ``.excerpt`` column however will only be loaded when it
is directly accessed::

    from sqlalchemy import Text
    from sqlalchemy.orm import DeclarativeBase
    from sqlalchemy.orm import Mapped
    from sqlalchemy.orm import mapped_column

    class Base(DeclarativeBase):
        pass

    class Book(Base):
        __tablename__ = 'book'

        book_id: Mapped[int] = mapped_column(primary_key=True)
        title: Mapped[str]
        summary: Mapped[str]
        excerpt: Mapped[str] = mapped_column(Text, deferred=True)
        photo1: Mapped[bytes] = mapped_column(deferred_group="photos")
        photo2: Mapped[bytes] = mapped_column(deferred_group="photos")
        photo3: Mapped[bytes] = mapped_column(deferred_group="photos")


.. _deferred_options:

Deferred Column Loader Query Options
------------------------------------
At query time, the :func:`_orm.defer`, :func:`_orm.undefer` and
:func:`_orm.undefer_group` loader options may be used to further control the
"deferral behavior" of mapped columns.

Columns can be marked as "deferred" or reset to "undeferred" at query time
using options which are passed to the :meth:`_sql.Select.options` method; the most
basic query options are :func:`_orm.defer` and
:func:`_orm.undefer`::

    from sqlalchemy.orm import defer
    from sqlalchemy.orm import undefer
    from sqlalchemy import select

    stmt = select(Book)
    stmt = stmt.options(defer(Book.summary), undefer(Book.excerpt))
    book_objs = session.scalars(stmt).all()


Above, the "summary" column will not load until accessed, and the "excerpt"
column will load immediately even if it was mapped as a "deferred" column.

:func:`_orm.deferred` attributes which are marked with a "group" can be undeferred
using :func:`_orm.undefer_group`, sending in the group name::

    from sqlalchemy.orm import undefer_group
    from sqlalchemy import select

    stmt = select(Book)
    stmt = stmt.options(undefer_group('photos'))
    book_objs = session.scalars(stmt).all()


.. _deferred_loading_w_multiple:

Deferred Loading across Multiple Entities
-----------------------------------------

Column deferral may also be used for a statement that loads multiple types of
entities at once, by referring to the appropriate class bound attribute
within the :func:`_orm.defer` function.  Suppose ``Book`` has a
relationship ``Book.author`` to a related class ``Author``, we could write
a query as follows which will defer the ``Author.bio`` column::

    from sqlalchemy.orm import defer
    from sqlalchemy import select

    stmt = select(Book, Author).join(Book.author)
    stmt = stmt.options(defer(Author.bio))

    book_author_objs = session.execute(stmt).all()


Column deferral options may also indicate that they take place along various
relationship paths, which are themselves often :ref:`eagerly loaded
<loading_toplevel>` with loader options.  All relationship-bound loader options
support chaining  onto additional loader options, which include loading for
further levels of relationships, as well as onto column-oriented attributes at
that path. Such as, to load ``Author`` instances, then joined-eager-load the
``Author.books`` collection for each author, then apply deferral options to
column-oriented attributes onto each ``Book`` entity from that relationship,
the :func:`_orm.joinedload` loader option can be combined with the :func:`.load_only`
option (described later in this section) to defer all ``Book`` columns except
those explicitly specified::

    from sqlalchemy.orm import joinedload
    from sqlalchemy import select

    stmt = select(Author)
    stmt = stmt.options(
        joinedload(Author.books).load_only(Book.summary, Book.excerpt)
    )

    author_objs = session.scalars(stmt).all()

Option structures as above can also be organized in more complex ways, such
as hierarchically using the :meth:`_orm.Load.options`
method, which allows multiple sub-options to be chained to a common parent
option at once.   The example below illustrates a more complex structure::

    from sqlalchemy.orm import defer
    from sqlalchemy.orm import joinedload
    from sqlalchemy.orm import load_only
    from sqlalchemy import select

    stmt = select(Author)
    stmt = stmt.options(
        joinedload(Author.book).options(
            load_only(Book.summary, Book.excerpt),
            joinedload(Book.citations).options(
                joinedload(Citation.author),
                defer(Citation.fulltext)
            )
        )
    )
    author_objs = session.scalars(stmt).all()


Another way to apply options to a path is to use the :func:`_orm.defaultload`
function.   This function is used to indicate a particular path within a loader
option structure without actually setting any options at that level, so that further
sub-options may be applied.  The :func:`_orm.defaultload` function can be used
to create the same structure as we did above using :meth:`_orm.Load.options` as::

    from sqlalchemy import select
    from sqlalchemy.orm import defaultload

    stmt = select(Author)
    stmt = stmt.options(
        joinedload(Author.book).load_only(Book.summary, Book.excerpt),
        defaultload(Author.book).joinedload(Book.citations).joinedload(Citation.author),
        defaultload(Author.book).defaultload(Book.citations).defer(Citation.fulltext)
    )

    author_objs = session.scalars(stmt).all()

.. seealso::

    :ref:`relationship_loader_options` - targeted towards relationship loading


.. _deferred_raiseload:

Raiseload for Deferred Columns
------------------------------

.. versionadded:: 1.4

The :func:`.deferred` loader option and the corresponding loader strategy also
support the concept of "raiseload", which is a loader strategy that will raise
:class:`.InvalidRequestError` if the attribute is accessed such that it would
need to emit a SQL query in order to be loaded.   This behavior is the
column-based equivalent of the :func:`_orm.raiseload` feature for relationship
loading, discussed at :ref:`prevent_lazy_with_raiseload`.    Using the
:paramref:`_orm.defer.raiseload` parameter on the :func:`_orm.defer` option,
an exception is raised if the attribute is accessed::

    book = session.scalar(
      select(Book).options(defer(Book.summary, raiseload=True)).limit(1)
    )

    # would raise an exception
    book.summary

Deferred "raiseload" can be configured at the mapper level via
:paramref:`.orm.deferred.raiseload` on either :func:`_orm.mapped_column`
or in :func:`.deferred`, so that an explicit
:func:`.undefer` is required in order for the attribute to be usable.
Below is a :ref:`Declarative table <orm_declarative_table>` configuration example::


    from sqlalchemy import Text
    from sqlalchemy.orm import DeclarativeBase
    from sqlalchemy.orm import Mapped
    from sqlalchemy.orm import mapped_column

    class Base(DeclarativeBase):
        pass

    class Book(Base):
        __tablename__ = 'book'

        book_id: Mapped[int] = mapped_column(primary_key=True)
        title: Mapped[str]
        summary: Mapped[str] = mapped_column(raiseload=True)
        excerpt: Mapped[str] = mapped_column(Text, raiseload=True)

Alternatively, the example below illustrates the same mapping using a
:ref:`Imperative table <orm_imperative_table_configuration>` configuration::

    from sqlalchemy import Column, Integer, LargeBinary, String, Table, Text
    from sqlalchemy.orm import DeclarativeBase
    from sqlalchemy.orm import deferred


    class Base(DeclarativeBase):
        pass


    book = Table(
        "book",
        Base.metadata,
        Column("book_id", Integer, primary_key=True),
        Column("title", String),
        Column("summary", String),
        Column("excerpt", Text),
    )


    class Book(Base):
        __table__ = book

        summary = deferred(book.c.summary, raiseload=True)
        excerpt = deferred(book.c.excerpt, raiseload=True)

With both mappings, if we wish to have either or both of ``.excerpt``
or ``.summary`` available on an object when loaded, we make use of the
:func:`_orm.undefer` loader option::

    book_w_excerpt = session.scalars(
      select(Book).options(undefer(Book.excerpt)).where(Book.id == 12)
    ).first()

The :func:`_orm.undefer` option will populate the ``.excerpt`` attribute
above, even if the ``Book`` object were already loaded, assuming the
``.excerpt`` field was not populated by some other means previously.

