Метод scalar_one_or_none

Метод scalar_one_or_none класса Result возвращает первое значение первой колонки результата. Если в результате ровно одна строка, метод вернет скалярное значение. Если строк нет, метод вернет None. Если строк больше одной, метод выбрасывает исключение MultipleResultsFound. Параметров метод не принимает.

Метод удобно использовать, когда нужно получить одно значение из запроса, который может вернуть ноль или одну строку, например при поиске записи по уникальному идентификатору.

Синтаксис

Result.scalar_one_or_none()

Пример

Пусть у нас есть модель Article с таблицей articles:

from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column

class Base(DeclarativeBase):
	pass

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

Давайте найдем статью по идентификатору и получим ее заголовок. Метод вернет скалярное значение, так как строка одна:

from sqlalchemy import create_engine, select
from sqlalchemy.orm import Session
from models import Base, Article

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

with Session(engine) as session:
	session.add(Article(
		title='article 1',
		text='text 1',
		status='published',
		num=1,
	))
	session.commit()
	
	res = session.execute(
		select(Article.title).where(Article.id == 1)
	)
	value = res.scalar_one_or_none()
	print(value)

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

"article 1"

Пример

Если подходящей строки нет, метод вернет None. Давайте запросим статью с несуществующим идентификатором:

from sqlalchemy import create_engine, select
from sqlalchemy.orm import Session
from models import Base, Article

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

with Session(engine) as session:
	session.add(Article(
		title='article 1',
		text='text 1',
		status='published',
		num=1,
	))
	session.commit()
	
	res = session.execute(
		select(Article.title).where(Article.id == 999)
	)
	value = res.scalar_one_or_none()
	print(value)

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

None

Пример

Если запрос вернет больше одной строки, метод выбросит исключение MultipleResultsFound. Давайте добавим две статьи и запросим заголовки всех статей:

<+python+> from sqlalchemy import create_engine, select from sqlalchemy.orm import Session from models import Base, Article engine = create_engine('sqlite:///:memory:') Base.metadata.create_all(engine) with Session(engine) as session: session.add(Article( title='article 1', text='text 1', status='published', num=1, )) session.add(Article( title='article 2', text='text 2', status='draft', num=2, )) session.commit() res = session.execute(select(Article.title)) try: value = res.scalar_one_or_none() except Exception as exc: print(type(exc).__name__) <-python+>

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

<+python+> "MultipleResultsFound" <-python+>

Итоговый SQL запрос:

SELECT articles.title FROM articles

Пример

Метод можно применять и к запросам с агрегатными функциями, например для подсчета количества статей:

<+python+> from sqlalchemy import create_engine, select, func from sqlalchemy.orm import Session from models import Base, Article engine = create_engine('sqlite:///:memory:') Base.metadata.create_all(engine) with Session(engine) as session: session.add(Article( title='article 1', text='text 1', status='published', num=1, )) session.add(Article( title='article 2', text='text 2', status='draft', num=2, )) session.commit() res = session.execute(select(func.count(Article.id))) value = res.scalar_one_or_none() print(value) <-python+>

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

<+python+> 2 <-python+>

Итоговый SQL запрос:

SELECT count(articles.id) AS count_1 FROM articles

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

класс Result,
который представляет результат запроса
метод scalar_one,
который требует ровно одну строку
метод scalar,
который возвращает первое значение первой колонки
метод one_or_none,
который возвращает одну строку или None