def joinedload_all(*keys, **kw):
"""Return a ``MapperOption`` that will convert all properties along the
given dot-separated path into an joined eager load.
.. note:: This function is known as :func:`eagerload_all` in all versions
of SQLAlchemy prior to version 0.6beta3, including the 0.5 and 0.4 series.
:func:`eagerload_all` will remain available for
the foreseeable future in order to enable cross-compatibility.
Used with :meth:`~sqlalchemy.orm.query.Query.options`.
For example::
query.options(joinedload_all('orders.items.keywords'))...
will set all of 'orders', 'orders.items', and 'orders.items.keywords' to
load in one joined eager load.
Individual descriptors are accepted as arguments as well::
query.options(joinedload_all(User.orders, Order.items, Item.keywords))
The keyword arguments accept a flag `innerjoin=True|False` which will
override the value of the `innerjoin` flag specified on the relationship().
See also: :func:`subqueryload_all`, :func:`lazyload`
"""
innerjoin = kw.pop('innerjoin', None)
if innerjoin is not None:
return (strategies.EagerLazyOption(keys, lazy='joined', chained=True),
strategies.EagerJoinOption(keys, innerjoin, chained=True))
else:
return strategies.EagerLazyOption(keys, lazy='joined', chained=True)
def eagerload(name, mapper=None):
"""Return a ``MapperOption`` that will convert the property of the given name into an eager load.
Used with ``query.options()``.
"""
return strategies.EagerLazyOption(name, lazy=False, mapper=mapper)
def subqueryload(*keys):
"""Return a ``MapperOption`` that will convert the property
of the given name into an subquery eager load.
.. note:: This function is new as of SQLAlchemy version 0.6beta3.
Used with :meth:`~sqlalchemy.orm.query.Query.options`.
examples::
# subquery-load the "orders" colleciton on "User"
query(User).options(subqueryload(User.orders))
# subquery-load the "keywords" collection on each "Item",
# but not the "items" collection on "Order" - those
# remain lazily loaded.
query(Order).options(subqueryload(Order.items, Item.keywords))
# to subquery-load across both, use subqueryload_all()
query(Order).options(subqueryload_all(Order.items, Item.keywords))
See also: :func:`joinedload`, :func:`lazyload`
"""
return strategies.EagerLazyOption(keys, lazy="subquery")
def noload(*keys):
"""Return a ``MapperOption`` that will convert the property of the
given name into a non-load.
Used with ``query.options()``.
"""
return strategies.EagerLazyOption(keys, lazy=None)
def lazyload(name):
"""Return a ``MapperOption`` that will convert the property of the
given name into a lazy load.
Used with ``query.options()``.
"""
return strategies.EagerLazyOption(name, lazy=True)
def joinedload(*keys, **kw):
"""Return a ``MapperOption`` that will convert the property of the given
name into an joined eager load.
.. note:: This function is known as :func:`eagerload` in all versions
of SQLAlchemy prior to version 0.6beta3, including the 0.5 and 0.4 series.
:func:`eagerload` will remain available for
the foreseeable future in order to enable cross-compatibility.
Used with :meth:`~sqlalchemy.orm.query.Query.options`.
examples::
# joined-load the "orders" colleciton on "User"
query(User).options(joinedload(User.orders))
# joined-load the "keywords" collection on each "Item",
# but not the "items" collection on "Order" - those
# remain lazily loaded.
query(Order).options(joinedload(Order.items, Item.keywords))
# to joined-load across both, use joinedload_all()
query(Order).options(joinedload_all(Order.items, Item.keywords))
:func:`joinedload` also accepts a keyword argument `innerjoin=True` which
indicates using an inner join instead of an outer::
query(Order).options(joinedload(Order.user, innerjoin=True))
Note that the join created by :func:`joinedload` is aliased such that
no other aspects of the query will affect what it loads. To use joined eager
loading with a join that is constructed manually using :meth:`~sqlalchemy.orm.query.Query.join`
or :func:`~sqlalchemy.orm.join`, see :func:`contains_eager`.
See also: :func:`subqueryload`, :func:`lazyload`
"""
innerjoin = kw.pop('innerjoin', None)
if innerjoin is not None:
return (strategies.EagerLazyOption(keys, lazy='joined'),
strategies.EagerJoinOption(keys, innerjoin))
else:
return strategies.EagerLazyOption(keys, lazy='joined')
def noload(*keys):
"""Return a ``MapperOption`` that will convert the property of the
given name into a non-load.
Used with :meth:`~sqlalchemy.orm.query.Query.options`.
See also: :func:`lazyload`, :func:`eagerload`, :func:`subqueryload`
"""
return strategies.EagerLazyOption(keys, lazy=None)
def eagerload_all(name, mapper=None):
"""Return a ``MapperOption`` that will convert all properties along the given dot-separated path into an eager load.
For example, this::
query.options(eagerload_all('orders.items.keywords'))...
will set all of 'orders', 'orders.items', and 'orders.items.keywords'
to load in one eager load.
Used with ``query.options()``.
"""
return strategies.EagerLazyOption(name, lazy=False, chained=True, mapper=mapper)
def contains_eager(*keys, **kwargs):
"""Return a ``MapperOption`` that will indicate to the query that
the given attribute will be eagerly loaded.
Used when feeding SQL result sets directly into ``query.instances()``.
Also bundles an ``EagerLazyOption`` to turn on eager loading in case it
isn't already.
`alias` is the string name of an alias, **or** an ``sql.Alias`` object,
which represents the aliased columns in the query. This argument is
optional.
"""
alias = kwargs.pop('alias', None)
if kwargs:
raise exceptions.ArgumentError("Invalid kwargs for contains_eager: %r" % kwargs.keys())
return (strategies.EagerLazyOption(keys, lazy=False), strategies.LoadEagerFromAliasOption(keys, alias=alias))
def contains_eager(key, alias=None, decorator=None):
"""Return a ``MapperOption`` that will indicate to the query that
the given attribute will be eagerly loaded.
Used when feeding SQL result sets directly into
``query.instances()``. Also bundles an ``EagerLazyOption`` to
turn on eager loading in case it isn't already.
`alias` is the string name of an alias, **or** an ``sql.Alias``
object, which represents the aliased columns in the query. This
argument is optional.
`decorator` is mutually exclusive of `alias` and is a
row-processing function which will be applied to the incoming row
before sending to the eager load handler. use this for more
sophisticated row adjustments beyond a straight alias.
"""
return (strategies.EagerLazyOption(key, lazy=False), strategies.RowDecorateOption(key, alias=alias, decorator=decorator))
def contains_eager(*keys, **kwargs):
"""Return a ``MapperOption`` that will indicate to the query that
the given attribute should be eagerly loaded from columns currently
in the query.
Used with :meth:`~sqlalchemy.orm.query.Query.options`.
The option is used in conjunction with an explicit join that loads
the desired rows, i.e.::
sess.query(Order).\\
join(Order.user).\\
options(contains_eager(Order.user))
The above query would join from the ``Order`` entity to its related
``User`` entity, and the returned ``Order`` objects would have the
``Order.user`` attribute pre-populated.
:func:`contains_eager` also accepts an `alias` argument, which
is the string name of an alias, an :func:`~sqlalchemy.sql.expression.alias`
construct, or an :func:`~sqlalchemy.orm.aliased` construct. Use this
when the eagerly-loaded rows are to come from an aliased table::
user_alias = aliased(User)
sess.query(Order).\\
join((user_alias, Order.user)).\\
options(contains_eager(Order.user, alias=user_alias))
See also :func:`eagerload` for the "automatic" version of this
functionality.
"""
alias = kwargs.pop('alias', None)
if kwargs:
raise exceptions.ArgumentError(
"Invalid kwargs for contains_eager: %r" % kwargs.keys())
return (strategies.EagerLazyOption(keys,
lazy='joined',
propagate_to_loaders=False),
strategies.LoadEagerFromAliasOption(keys, alias=alias))
def subqueryload_all(*keys):
"""Return a ``MapperOption`` that will convert all properties along the
given dot-separated path into a subquery eager load.
.. note:: This function is new as of SQLAlchemy version 0.6beta3.
Used with :meth:`~sqlalchemy.orm.query.Query.options`.
For example::
query.options(subqueryload_all('orders.items.keywords'))...
will set all of 'orders', 'orders.items', and 'orders.items.keywords' to
load in one subquery eager load.
Individual descriptors are accepted as arguments as well::
query.options(subqueryload_all(User.orders, Order.items, Item.keywords))
See also: :func:`joinedload_all`, :func:`lazyload`
"""
return strategies.EagerLazyOption(keys, lazy="subquery", chained=True)
def nestedload_all(*keys, **kw):
return _sqla_strat.EagerLazyOption(keys,
lazy='akiban_nested',
chained=True)
def nestedload(*keys, **kw):
return _sqla_strat.EagerLazyOption(keys, lazy='akiban_nested')
