Метод scalar_one

Метод scalar_one класса Session выполняет SQL-запрос и возвращает ровно одно скалярное значение из первой колонки первой строки результата. Если запрос вернул ноль строк или больше одной строки, метод вызывает исключение. Первым параметром метод принимает объект запроса или SQL-выражение, дополнительными параметрами могут быть словарь параметров и опции выполнения.

Синтаксис

Session.scalar_one(statement, [params])

Пример

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

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

class Base(DeclarativeBase):
	pass

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

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

with Session(engine) as session:
	article = Article(title='article')
	session.add(article)
	session.commit()
	
	res = session.scalar_one(select(Article.id))
	print(res)

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

1

Пример

Давайте получим скалярное значение поля title для одной конкретной записи:

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

class Base(DeclarativeBase):
	pass

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

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

with Session(engine) as session:
	article = Article(title='article')
	session.add(article)
	session.commit()
	
	res = session.scalar_one(
		select(Article.title).where(Article.id == 1)
	)
	print(res)

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

"article"

Пример

Давайте посмотрим, что произойдет, если запрос вернет больше одной строки:

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

class Base(DeclarativeBase):
	pass

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

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

with Session(engine) as session:
	session.add_all([
		Article(title='article 1'),
		Article(title='article 2'),
	])
	session.commit()
	
	try:
		res = session.scalar_one(select(Article.id))
		print(res)
	except Exception as exc:
		print(type(exc).__name__)

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

"MultipleResultsFound"

Пример

Давайте посмотрим, что произойдет, если запрос не вернет ни одной строки:

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

class Base(DeclarativeBase):
	pass

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

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

with Session(engine) as session:
	try:
		res = session.scalar_one(select(Article.id))
		print(res)
	except Exception as exc:
		print(type(exc).__name__)

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

"NoResultFound"

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

метод scalar,
который возвращает первое скалярное значение или None
метод scalar_one_or_none,
который возвращает одно значение или None без исключения
метод one,
который возвращает ровно одну строку целиком
метод execute,
который выполняет запрос и возвращает объект Result