Функция nulls_first

Функция nulls_first применяется в конструкциях сортировки для указания того, что значения NULL должны располагаться в начале результата. Она принимает один параметр - выражение сортировки, обычно результат функции asc или desc, и возвращает модифицированное выражение, которое при генерации SQL-запроса добавляет инструкцию NULLS FIRST.

Функция особенно полезна при работе с базами данных, которые по умолчанию размещают NULL в конце при сортировке по возрастанию, или когда требуется единообразное поведение независимо от настроек СУБД.

Синтаксис

nulls_first(expr)

Пример

Давайте создадим таблицу articles с полем num, которое может содержать значения NULL, и отсортируем записи так, чтобы пустые значения шли первыми:

from sqlalchemy import create_engine, MetaData, Table, Column, Integer, String, select, nulls_first, asc

engine = create_engine('sqlite:///:memory:')
metadata = MetaData()

articles = Table(
	'articles', metadata,
	Column('id', Integer, primary_key=True),
	Column('title', String),
	Column('num', Integer)
)

metadata.create_all(engine)

with engine.connect() as conn:
	conn.execute(articles.insert(), [
		{'id': 1, 'title': 'article 1', 'num': 5},
		{'id': 2, 'title': 'article 2', 'num': None},
		{'id': 3, 'title': 'article 3', 'num': 2},
		{'id': 4, 'title': 'article 4', 'num': None},
	])
	
	stmt = select(articles.c.id, articles.c.num).order_by(
		nulls_first(asc(articles.c.num))
	)
	res = conn.execute(stmt).fetchall()
	print(res)

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

[(2, None), (4, None), (3, 2), (1, 5)]

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

SELECT articles.id, articles.num
FROM articles
ORDER BY articles.num ASC NULLS FIRST

Пример

Давайте применим nulls_first совместно с сортировкой по убыванию:

from sqlalchemy import create_engine, MetaData, Table, Column, Integer, String, select, nulls_first, desc

engine = create_engine('sqlite:///:memory:')
metadata = MetaData()

articles = Table(
	'articles', metadata,
	Column('id', Integer, primary_key=True),
	Column('title', String),
	Column('num', Integer)
)

metadata.create_all(engine)

with engine.connect() as conn:
	conn.execute(articles.insert(), [
		{'id': 1, 'title': 'article 1', 'num': 5},
		{'id': 2, 'title': 'article 2', 'num': None},
		{'id': 3, 'title': 'article 3', 'num': 2},
	])
	
	stmt = select(articles.c.id, articles.c.num).order_by(
		nulls_first(desc(articles.c.num))
	)
	res = conn.execute(stmt).fetchall()
	print(res)

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

[(2, None), (1, 5), (3, 2)]

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

SELECT articles.id, articles.num
FROM articles
ORDER BY articles.num DESC NULLS FIRST

Пример

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

from sqlalchemy import create_engine, MetaData, Table, Column, Integer, String, select, nulls_first, asc

engine = create_engine('sqlite:///:memory:')
metadata = MetaData()

articles = Table(
	'articles', metadata,
	Column('id', Integer, primary_key=True),
	Column('title', String),
	Column('num', Integer)
)

metadata.create_all(engine)

with engine.connect() as conn:
	conn.execute(articles.insert(), [
		{'id': 1, 'title': 'article', 'num': 1},
		{'id': 2, 'title': 'article', 'num': None},
		{'id': 3, 'title': 'article', 'num': 2},
	])
	
	stmt = select(articles.c.id, articles.c.title, articles.c.num).order_by(
		articles.c.title,
		nulls_first(asc(articles.c.num))
	)
	res = conn.execute(stmt).fetchall()
	print(res)

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

[(2, 'article', None), (1, 'article', 1), (3, 'article', 2)]

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

SELECT articles.id, articles.title, articles.num
FROM articles
ORDER BY articles.title, articles.num ASC NULLS FIRST

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

функцию nulls_last,
которая размещает NULL значения в конце
функцию asc,
которая задает сортировку по возрастанию
функцию desc,
которая задает сортировку по убыванию
функцию null,
которая создает выражение NULL