Встроенные агрегатные функции

1. Синтаксис

Приведённые ниже агрегатные функции доступны по умолчанию. Ещё две агрегатные функции входят в состав функций JSON SQL. Приложения могут определять пользовательские агрегатные функции с помощью интерфейса sqlite3_create_function().

В любой агрегатной функции, принимающей один аргумент, перед этим аргументом можно указать ключевое слово DISTINCT. В этом случае повторяющиеся элементы отфильтровываются перед передачей в агрегатную функцию. Например, функция "count(distinct X)" возвращает количество различных значений столбца X, а не общее количество ненулевых значений в столбце X.

Если указано предложение FILTER, то в агрегат включаются только строки, для которых expr имеет значение true.

Если указано предложение ORDER BY, оно определяет порядок обработки входных данных агрегатной функцией. Для таких агрегатных функций, как max() и count(), порядок входных данных не имеет значения. Однако для таких функций, как string_agg() и json_group_object(), предложение ORDER BY влияет на результат. Если предложение ORDER BY не указано, входные данные агрегатной функции обрабатываются в произвольном порядке, который может меняться от одного вызова к другому.

См. также: скалярные функции и оконные функции.

2. Список встроенных агрегатных функций

3. Описание встроенных агрегатных функций

avg(X)

Функция avg() возвращает среднее значение всех ненулевых значений X в группе. Строковые значения и значения BLOB, которые не похожи на числа, интерпретируются как 0. Если имеется хотя бы одно ненулевое входное значение, результат avg() всегда является числом с плавающей точкой, даже если все входные значения — целые числа. Если ненулевых входных значений нет, результат avg() равен NULL. Результат avg() вычисляется как total()/count(), поэтому к avg() применяются те же ограничения, что и к total().

count(X) count(*)

Функция count(X) возвращает количество случаев, когда значение X не равно NULL в группе. Функция count(*) (без аргументов) возвращает общее количество строк в группе.

group_concat(X) group_concat(X,Y) string_agg(X,Y)

Функция group_concat() возвращает строку, образованную объединением всех ненулевых значений X. Если указан параметр Y, он используется в качестве разделителя между значениями X. Если параметр Y не указан, в качестве разделителя используется запятая (",").

Функция string_agg(X,Y) является псевдонимом group_concat(X,Y). String_agg() совместима с PostgreSQL и SQL Server, а group_concat() — с MySQL.

Порядок объединения элементов произволен, если только сразу после последнего параметра не указан аргумент ORDER BY.

max(X)

Агрегатная функция max() возвращает максимальное значение среди всех значений в группе. Максимальным является значение, которое при сортировке того же столбца с помощью ORDER BY оказалось бы последним. Агрегатная функция max() возвращает NULL тогда и только тогда, когда в группе нет ненулевых значений.

median(X)

Функция median() возвращает медианное значение всех ненулевых значений X в группе. Функция median(X) эквивалентна percentile_cont(X,0.5). Дополнительные сведения см. в отдельной документации по расширению percentile.

Функция median() доступна начиная с SQLite версии 3.51.0 (2025-11-04), если объединённая исходная версия скомпилирована с параметром -DSQLITE_ENABLE_PERCENTILE, либо в качестве загружаемого расширения в более ранних версиях SQLite.

min(X)

Агрегатная функция min() возвращает минимальное ненулевое значение среди всех значений в группе. Минимальным является первое ненулевое значение, которое появилось бы при сортировке столбца с помощью ORDER BY. Агрегатная функция min() возвращает NULL тогда и только тогда, когда в группе нет ненулевых значений.

percentile(Y,P)

Агрегатная функция percentile(Y,P) вычисляет значение X, которое больше или равно P процентам ненулевых входных значений и меньше или равно 100-P процентам входных значений. Параметр P должен быть числом от 0.0 до 100.0. Значение P должно быть одинаковым для всех элементов агрегата и не может быть NULL. Входные значения Y должны быть либо NULL, либо числовыми. Значения NULL для Y игнорируются. Если любое ненулевое входное значение Y не является числовым, возникает ошибка.

Функция percentile(Y,P) эквивалентна percentile_cont(Y,p/100.0). Дополнительные сведения см. в отдельной документации по расширению percentile.

Функция percentile() доступна начиная с SQLite версии 3.51.0 (2025-11-04), если объединённая исходная версия скомпилирована с параметром -DSQLITE_ENABLE_PERCENTILE, либо в качестве загружаемого расширения в более ранних версиях SQLite.

percentile_cont(Y,P)

Агрегатная функция percentile(Y,P) вычисляет значение X, которое больше или равно доле P ненулевых входных значений и меньше или равно доле 1.0-P входных значений. Параметр P должен быть числом от 0.0 до 1.0. Значение P должно быть одинаковым для всех элементов агрегата и не может быть NULL. Входные значения Y должны быть либо NULL, либо числовыми. Значения NULL для Y игнорируются. Если любое ненулевое входное значение Y не является числовым, возникает ошибка. Функция percentile_cont(Y,P) работает как percentile(Y,P), за исключением того, что значение P находится в диапазоне от 0.0 до 1.0, а не от 0.0 до 100.0. Таким образом, результат percentile_cont(Y,P) совпадает с результатом percentile(Y,P*100). Дополнительные сведения см. в отдельной документации по расширению percentile.

Функция percentile_cont() доступна начиная с SQLite версии 3.51.0 (2025-11-04), если объединённая исходная версия скомпилирована с параметром -DSQLITE_ENABLE_PERCENTILE, либо в качестве загружаемого расширения в более ранних версиях SQLite.

percentile_disc(Y,P)

Функция percentile_disc(Y,P) работает как percentile_cont(Y,P), но вместо вычисления взвешенного среднего ближайших доступных входных значений всегда возвращает одно из входных значений — меньшее из двух возможных вариантов. Дополнительные сведения см. в отдельной документации по расширению percentile.

sum(X) total(X)

Агрегатные функции sum() и total() возвращают сумму всех ненулевых значений в группе. Если входных строк с ненулевыми значениями нет, sum() возвращает NULL, а total() — 0.0. NULL обычно не является полезным результатом суммы пустого набора строк, но этого требует стандарт SQL, и большинство других SQL-сУБД реализуют sum() таким же образом. Поэтому SQLite делает то же самое для обеспечения совместимости. Нестандартная функция total() предоставляется как удобный способ обойти эту особенность языка SQL.

Результат total() всегда является числом с плавающей точкой. Если все ненулевые входные значения являются целыми числами, результат sum() — целое число. Если какое-либо входное значение sum() не является ни целым числом, ни NULL, sum() возвращает число с плавающей точкой, представляющее приближённую математическую сумму.

Функция sum() вызовет исключение «переполнение целого числа», если все входные значения являются целыми числами или NULL и в какой-либо момент вычисления произойдёт переполнение. Если до этого любое входное значение было числом с плавающей точкой, ошибка переполнения не возникает. Функция total() никогда не вызывает ошибку переполнения целого числа.

При суммировании чисел с плавающей точкой, если порядки величин значений сильно различаются, сумма может оказаться неточной из-за того, что числа с плавающей точкой IEEE 754 являются приближёнными. Чтобы получить точную сумму чисел с плавающей точкой, используйте агрегатную функцию decimal_sum(X) из расширения decimal. Рассмотрим следующий тестовый пример:

CREATE TABLE t1(x REAL);
INSERT INTO t1 VALUES(1.55e+308),(1.23),(3.2e-16),(-1.23),(-1.55e308);
SELECT sum(x), decimal_sum(x) FROM t1;

Большие значения ±1.55e+308 взаимно компенсируются, но это происходит лишь в конце суммирования; тем временем большое значение +1.55e+308 подавляет малое значение 3.2e-16. В результате сумма sum() оказывается неточной. Агрегатная функция decimal_sum() даёт точный результат, но требует дополнительных затрат процессорного времени и памяти. Обратите также внимание, что decimal_sum() не входит в ядро SQLite, а является загружаемым расширением.

Если сумма входных значений слишком велика для представления в формате чисел с плавающей точкой IEEE 754, может быть возвращён результат +Infinity или -Infinity. Если используются очень большие значения с разными знаками и функция SUM() или TOTAL() не может определить, должен ли правильный результат быть +Infinity, -Infinity или каким-либо промежуточным значением, результатом будет NULL. Например, следующий запрос возвращает NULL:

WITH t1(x) AS (VALUES(1.0),(-9e+999),(2.0),(+9e+999),(3.0))
 SELECT sum(x) FROM t1;

Последнее обновление этой страницы: 2025-11-13 07:12:58Z

SQLite is in the Public Domain.
https://sqlite.org/lang_aggfunc.html