Метод first класса Session

Метод first класса Session возвращает первую строку из результата выполнения запроса. Если записей нет, метод возвращает None. Метод принимает на вход объект запроса или SQL-выражение и автоматически ограничивает выборку одной записью. Это удобный способ получить одну запись без необходимости вызывать scalars и one_or_none.

Синтаксис

session.first(statement)

Пример

Давайте создадим модель и получим первую запись из таблицы articles:

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

class Base(DeclarativeBase):
	pass

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

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

with Session(engine) as session:
	session.add_all([
		Article(title='article 1', text='text 1', status='active', num=1),
		Article(title='article 2', text='text 2', status='active', num=2),
		Article(title='article 3', text='text 3', status='draft', num=3),
	])
	session.commit()
	
	res = session.first(
		session.query(Article).order_by(Article.id)
	)
	print(res.title)

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

"article 1"

Пример

Давайте убедимся, что метод возвращает None, если записей нет:

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

class Base(DeclarativeBase):
	pass

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

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

with Session(engine) as session:
	res = session.first(
		session.query(Article).filter(Article.status == 'deleted')
	)
	print(res)

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

None

Пример

Давайте получим первую запись с сортировкой по убыванию поля num:

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

class Base(DeclarativeBase):
	pass

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

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

with Session(engine) as session:
	session.add_all([
		Article(title='article 1', text='text 1', status='active', num=1),
		Article(title='article 2', text='text 2', status='active', num=2),
		Article(title='article 3', text='text 3', status='draft', num=3),
	])
	session.commit()
	
	res = session.first(
		session.query(Article).order_by(Article.num.desc())
	)
	print(res.title)

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

"article 3"

Пример

Давайте посмотрим итоговый SQL-запрос, который формирует метод first:

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

class Base(DeclarativeBase):
	pass

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

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

with Session(engine) as session:
	res = session.first(session.query(Article))

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

SELECT articles.id AS articles_id, articles.title AS articles_title, articles.text AS articles_text, articles.status AS articles_status, articles.num AS articles_num
FROM articles
LIMIT ? OFFSET ?

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

класс Session,
который управляет сессией работы с базой данных
метод one_or_none,
который возвращает одну запись или None
метод scalar,
который возвращает первый столбец первой записи
метод execute,
который выполняет SQL-выражение