Метод options класса Select

Метод options класса Select добавляет к запросу одну или несколько опций загрузки ORM. Опции управляют тем, как загружаются связанные объекты и отдельные атрибуты: например, жадной или ленивой загрузкой, объединением в один SQL-запрос или отдельными запросами. Первым параметром метод принимает одну опцию загрузки, а дополнительные опции можно передать следующими позиционными аргументами.

Опции загрузки импортируются из модуля sqlalchemy.orm и включают joinedload, selectinload, subqueryload, lazyload, noload, raiseload, load_only, defer, undefer и другие. Метод возвращает новый объект Select, поэтому его удобно объединять в цепочки вызовов.

Синтаксис

select(...).options(option, *additional_options)

Пример

Давайте создадим две связанные модели и применим опцию joinedload, чтобы загрузить статьи вместе с их авторами одним запросом:

from sqlalchemy import create_engine, ForeignKey, select
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship, Session
from sqlalchemy.orm import joinedload

class Base(DeclarativeBase):
	pass

class User(Base):
	__tablename__ = 'users'
	
	id: Mapped[int] = mapped_column(primary_key=True)
	name: Mapped[str]
	articles: Mapped[list['Article']] = relationship(back_populates='author')

class Article(Base):
	__tablename__ = 'articles'
	
	id: Mapped[int] = mapped_column(primary_key=True)
	title: Mapped[str]
	user_id: Mapped[int] = mapped_column(ForeignKey('users.id'))
	author: Mapped['User'] = relationship(back_populates='articles')

engine = create_engine('sqlite:///:memory:')
Base.metadata.create_all(engine)

with Session(engine) as session:
	user = User(name='user')
	user.articles = [Article(title='article 1'), Article(title='article 2')]
	session.add(user)
	session.commit()
	
	stmt = select(Article).options(joinedload(Article.author))
	res = session.scalars(stmt).all()
	for article in res:
		print(article.title, '->', article.author.name)

Результат выполнения кода:

article 1 -> user
article 2 -> user

Пример

Давайте применим опцию load_only, чтобы загрузить только выбранные столбцы модели:

from sqlalchemy import create_engine, select
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, Session
from sqlalchemy.orm import load_only

class Base(DeclarativeBase):
	pass

class Article(Base):
	__tablename__ = 'articles'
	
	id: Mapped[int] = mapped_column(primary_key=True)
	title: Mapped[str]
	text: Mapped[str]

engine = create_engine('sqlite:///:memory:')
Base.metadata.create_all(engine)

with Session(engine) as session:
	session.add(Article(title='article', text='some text'))
	session.commit()
	
	stmt = select(Article).options(load_only(Article.title))
	res = session.scalars(stmt).all()
	for article in res:
		print(article.title)

Результат выполнения кода:

"article"

Пример

Давайте объединим несколько опций загрузки в одном вызове метода options:

from sqlalchemy import create_engine, ForeignKey, select
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship, Session
from sqlalchemy.orm import joinedload, load_only

class Base(DeclarativeBase):
	pass

class User(Base):
	__tablename__ = 'users'
	
	id: Mapped[int] = mapped_column(primary_key=True)
	name: Mapped[str]
	articles: Mapped[list['Article']] = relationship(back_populates='author')

class Article(Base):
	__tablename__ = 'articles'
	
	id: Mapped[int] = mapped_column(primary_key=True)
	title: Mapped[str]
	text: Mapped[str]
	user_id: Mapped[int] = mapped_column(ForeignKey('users.id'))
	author: Mapped['User'] = relationship(back_populates='articles')

engine = create_engine('sqlite:///:memory:')
Base.metadata.create_all(engine)

with Session(engine) as session:
	user = User(name='user')
	user.articles = [Article(title='article', text='some text')]
	session.add(user)
	session.commit()
	
	stmt = select(Article).options(
		joinedload(Article.author),
		load_only(Article.title),
	)
	res = session.scalars(stmt).all()
	for article in res:
		print(article.title, '->', article.author.name)

Результат выполнения кода:

article -> user

Смотрите также

класс Select,
который представляет SELECT-запрос
метод execution_options,
который задает опции выполнения запроса
метод join,
который присоединяет таблицы к запросу
метод where,
который добавляет условие фильтрации