Метод nulls_first

Метод nulls_first класса ColumnElement возвращает модифицированное выражение сортировки, которое размещает значения NULL в начале результирующего набора. Метод не принимает параметров и применяется к выражениям, уже обернутым в asc или desc. Если СУБД поддерживает конструкцию NULLS FIRST, она будет добавлена в итоговый SQL-запрос.

Синтаксис

column_element.nulls_first()

Пример

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

from sqlalchemy import create_engine, select
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]
	status: Mapped[str | None]

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

with Session(engine) as session:
	session.add_all([
		Article(title='article 1', status='published'),
		Article(title='article 2', status=None),
		Article(title='article 3', status='draft'),
	])
	session.commit()
	
	stmt = select(Article.title).order_by(
		Article.status.asc().nulls_first()
	)
	res = session.execute(stmt).scalars().all()
	print(res)

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

['article 2', 'article 3', 'article 1']

Пример

Давайте посмотрим, какой SQL-запрос формируется при использовании метода nulls_first:

from sqlalchemy import create_engine, select
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]
	num: Mapped[int | None]

stmt = select(Article.title).order_by(
	Article.num.desc().nulls_first()
)
print(stmt)

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

SELECT articles.title
FROM articles
ORDER BY articles.num DESC NULLS FIRST

Пример

Давайте сравним поведение сортировки с методом nulls_first на одних и тех же данных:

<+python+> from sqlalchemy import create_engine, select 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] num: Mapped[int | None] engine = create_engine('sqlite:///:memory:') Base.metadata.create_all(engine) with Session(engine) as session: session.add_all([ Article(title='article 1', num=10), Article(title='article 2', num=None), Article(title='article 3', num=5), ]) session.commit() stmt = select(Article.title).order_by( Article.num.desc().nulls_first() ) res = session.execute(stmt).scalars().all() print(res) <-python+>

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

['article 2', 'article 1', 'article 3']

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

класс ColumnElement,
который представляет элемент столбца в SQLAlchemy
метод nulls_last,
который размещает значения NULL в конце сортировки
метод asc,
который задает сортировку по возрастанию
метод desc,
который задает сортировку по убыванию