Описание

CREATE AGGREGATE определяет новую агрегатную функцию. CREATE OR REPLACE AGGREGATE либо определит новую агрегатную функцию, либо заменит существующее определение. Некоторые базовые и часто используемые агрегатные функции включены в дистрибутив; они документированы в Раздел 2.6.21. Если определяются новые типы или требуется агрегатная функция, которая еще не предоставлена, то можно использовать CREATE AGGREGATE для обеспечения нужных возможностей.

При замене существующего определения нельзя изменять типы аргументов, тип результата и количество прямых аргументов. Также новое определение должно быть того же вида (обычная агрегатная, упорядоченно-множественная или гипотетически-множественная), что и старое.

Если указано имя схемы (например, CREATE AGGREGATE myschema.myagg ...), то агрегатная функция создается в указанной схеме. В противном случае она создается в текущей схеме.

Агрегатная функция идентифицируется своим именем и типом(ами) входных данных. Две агрегатные функции в одной схеме могут иметь одинаковое имя, если они работают с разными типами входных данных. Имя и тип(ы) входных данных агрегатной функции также должны отличаться от имени и типов входных данных каждой обычной функции в той же схеме. Это поведение идентично перегрузке имен обычных функций (см. CREATE FUNCTION).

Простая агрегатная функция состоит из одной или двух обычных функций: функции перехода состояния sfunc и необязательной функции финального вычисления ffunc. Они используются следующим образом:

sfunc( внутреннее-состояние, следующие-значения-данных ) ---> следующее-внутреннее-состояние
ffunc( внутреннее-состояние ) ---> агрегатное-значение

Digital Q.DataBase создает временную переменную типа данных stype для хранения текущего внутреннего состояния агрегата. Для каждой входной строки вычисляется(ются) значение(я) аргумента(ов) агрегата и вызывается функция перехода состояния с текущим значением состояния и новым(ыми) значением(ями) аргумента(ов) для вычисления нового значения внутреннего состояния. После обработки всех строк один раз вызывается финальная функция для вычисления возвращаемого значения агрегата. Если финальная функция отсутствует, то конечное значение состояния возвращается как есть.

Агрегатная функция может предоставить начальное условие, то есть начальное значение для внутреннего состояния. Оно указывается и сохраняется в базе данных как значение типа text, но должно быть допустимым внешним представлением константы типа данных состояния. Если оно не предоставлено, то значение состояния начинается как NULL.

Если функция перехода состояния объявлена как «строгая», то ее нельзя вызывать с NULL-входами. При использовании такой функции выполнения агрегата поведение следующее. Строки с любыми NULL-значениями на входе игнорируются (функция не вызывается, и предыдущее значение состояния сохраняется). Если начальное значение состояния равно NULL, то на первой строке со всеми не-NULL значениями на входе первое значение аргумента заменяет значение состояния, и функция перехода вызывается для каждой последующей строки с всеми не-NULL значениями на входе. Это удобно для реализации агрегатов, таких как max. Обратите внимание, что такое поведение доступно только когда state_data_type совпадает с первым arg_data_type. Когда эти типы различаются, вы должны предоставить не-NULL начальное условие или использовать нестрогую функцию перехода.

Если функция перехода состояния не является строгой, то она будет вызываться безусловно для каждой входной строки и должна сама обрабатывать NULL-входы и NULL-значения состояния. Это позволяет автору агрегата иметь полный контроль над обработкой NULL-значений агрегатом.

Если финальная функция объявлена «строгой», то она не будет вызываться, когда конечное значение состояния равно NULL; вместо этого автоматически будет возвращен NULL-результат. (Разумеется, это обычное поведение строгих функций.) В любом случае финальная функция имеет возможность вернуть NULL-значение. Например, финальная функция для avg возвращает NULL, когда видит, что было нулевое количество входных строк.

Иногда полезно объявить финальную функцию как принимающую не только значение состояния, но и дополнительные параметры, соответствующие входным значениям агрегата. Основная причина для этого — если финальная функция полиморфна и тип данных значения состояния был бы недостаточным для определения типа результата. Эти дополнительные параметры всегда передаются как NULL (и поэтому финальная функция не должна быть строгой, когда используется опция FINALFUNC_EXTRA), но тем не менее они являются допустимыми параметрами. Финальная функция может, например, использовать get_fn_expr_argtype для определения фактического типа аргумента в текущем вызове.

Агрегат может дополнительно поддерживать режим подвижного агрегата, как описано в Раздел 5.1.12.1. Для этого требуется указание параметров MSFUNC, MINVFUNC и MSTYPE, и, опционально, параметров MSSPACE, MFINALFUNC, MFINALFUNC_EXTRA, MFINALFUNC_MODIFY и MINITCOND. За исключением MINVFUNC, эти параметры работают так же, как соответствующие параметры простого агрегата без M; они определяют отдельную реализацию агрегата, которая включает обратную функцию перехода.

Синтаксис с ORDER BY в списке параметров создает специальный тип агрегата, называемый упорядоченно-множественным агрегатом; или, если указан HYPOTHETICAL, создается гипотетически-множественный агрегат. Эти агрегаты работают с группами отсортированных значений зависящим от порядка способами, поэтому указание порядка сортировки входных данных является важной частью вызова. Также они могут иметь прямые аргументы, которые вычисляются только один раз на агрегацию, а не один раз на входную строку. Гипотетически-множественные агрегаты являются подклассом упорядоченно-множественных агрегатов, в которых некоторые прямые аргументы должны совпадать, по количеству и типам данных, с агрегируемыми столбцами аргументов. Это позволяет добавлять значения этих прямых аргументов в коллекцию строк агрегатного ввода как дополнительную «гипотетическую» строку.

Агрегат может дополнительно поддерживать частичную агрегацию, как описано в Раздел 5.1.12.4. Для этого требуется указание параметра COMBINEFUNC. Если state_data_type имеет тип internal, обычно также уместно предоставить параметры SERIALFUNC и DESERIALFUNC, чтобы была возможна параллельная агрегация. Обратите внимание, что агрегат также должен быть помечен как PARALLEL SAFE, чтобы включить параллельную агрегацию.

Агрегаты, которые ведут себя как MIN или MAX, иногда могут быть оптимизированы путем обращения к индексу вместо сканирования каждой входной строки. Если этот агрегат может быть так оптимизирован, укажите это, задав оператор сортировки. Базовое требование заключается в том, что агрегат должен выдавать первый элемент в порядке сортировки, индуцированном оператором; другими словами:

SELECT agg(col) FROM tab;

должно быть эквивалентно:

SELECT col FROM tab ORDER BY col USING sortop LIMIT 1;

Дополнительные предположения: агрегат игнорирует NULL-входы и выдает NULL-результат тогда и только тогда, когда не было не-NULL-входов. Обычно оператор < типа данных является подходящим оператором сортировки для MIN, а > — подходящим оператором сортировки для MAX. Обратите внимание, что оптимизация никогда фактически не вступит в силу, если указанный оператор не является членом стратегии «меньше чем» или «больше чем» класса операторов B-дерева индекса.

Чтобы иметь возможность создать агрегатную функцию, вы должны иметь привилегию USAGE на типы аргументов, тип(ы) состояния и тип возвращаемого значения, а также привилегию EXECUTE на вспомогательные функции.

Параметры

Параметры CREATE AGGREGATE могут быть записаны в любом порядке, а не только в том, что показан выше.

Замечания

В параметрах, указывающих имена вспомогательных функций, можно при необходимости писать имя схемы, например SFUNC = public.sum. Однако не пишите там типы аргументов — типы аргументов вспомогательных функций определяются из других параметров.

Обычно от функций Digital Q.DataBase ожидается, что они будут истинными функциями, которые не изменяют свои входные значения. Однако функция перехода состояния агрегата, при использовании в контексте агрегата, может нарушать это правило и изменять аргумент состояния на месте. Это может обеспечить значительный выигрыш в производительности по сравнению с созданием новой копии состояния каждый раз.

Аналогично, хотя от финальной функции агрегата обычно ожидается, что она не будет изменять свои входные значения, иногда практически невозможно избежать изменения аргумента состояния. Такое поведение должно быть объявлено с использованием параметра FINALFUNC_MODIFY. Значение READ_WRITE указывает, что финальная функция изменяет состояние неопределенным образом. Это значение предотвращает использование агрегата в качестве оконной функции, а также предотвращает слияние состояний для вызовов агрегатов, которые имеют одинаковые входные значения и функции перехода. Значение SHAREABLE указывает, что функцию перехода нельзя применить после финальной функции, но можно выполнить несколько вызовов финальной функции над конечным значением состояния. Это значение предотвращает использование агрегата в качестве оконной функции, но позволяет объединять состояния. (То есть интересующая оптимизация здесь — не многократное применение одной и той же финальной функции, а применение разных финальных функций к одному и тому же конечному значению состояния. Это разрешено до тех пор, пока ни одна из финальных функций не помечена как READ_WRITE.)

Если агрегат поддерживает режим подвижного агрегата, это повысит эффективность вычислений, когда агрегат используется в качестве оконной функции для окна с движущимся началом кадра (то есть режимом начала кадра, отличным от UNBOUNDED PRECEDING). Концептуально прямая функция перехода добавляет входные значения в состояние агрегата, когда они входят в оконный кадр снизу, а обратная функция перехода удаляет их, когда они покидают кадр сверху. Таким образом, когда значения удаляются, они всегда удаляются в том же порядке, в котором были добавлены. Всякий раз, когда вызывается обратная функция перехода, она будет получать самое раннее добавленное, но еще не удаленное значение(я) аргумента. Обратная функция перехода может предполагать, что по крайней мере одна строка останется в текущем состоянии после удаления самой старой строки. (Когда это было бы не так, механизм оконных функций просто начинает новую агрегацию, а не использует обратную функцию перехода.)

Прямой функции перехода для режима подвижного агрегата запрещено возвращать NULL в качестве нового значения состояния. Если обратная функция перехода возвращает NULL, это воспринимается как указание, что обратная функция не может обратить вычисление состояния для этого конкретного входного значения, и поэтому вычисление агрегата будет переделано с нуля для текущей начальной позиции кадра. Это соглашение позволяет использовать режим подвижного агрегата в ситуациях, когда есть некоторые редкие случаи, которые непрактично обратить из текущего значения состояния.

Если реализация подвижного агрегата не предоставлена, агрегат все еще можно использовать с движущимися кадрами, но Digital Q.DataBase будет пересчитывать всю агрегацию всякий раз, когда начало кадра перемещается. Обратите внимание, что независимо от того, поддерживает ли агрегат режим подвижного агрегата, Digital Q.DataBase может обрабатывать движущийся конец кадра без пересчета; это делается путем продолжения добавления новых значений в состояние агрегата. Именно поэтому использование агрегата в качестве оконной функции требует, чтобы финальная функция была доступна только для чтения: она не должна повреждать значение состояния агрегата, чтобы агрегация могла быть продолжена даже после получения результата агрегата для одного набора границ кадра.

Синтаксис для упорядоченно-множественных агрегатов позволяет указывать VARIADIC как для последнего прямого параметра, так и для последнего агрегированного параметра (WITHIN GROUP). Однако текущая реализация ограничивает использование VARIADIC двумя способами. Во-первых, упорядоченно-множественные агрегаты могут использовать только VARIADIC "any", а не другие вариативные типы массивов. Во-вторых, если последний прямой параметр — VARIADIC "any", то может быть только один агрегированный параметр, и он также должен быть VARIADIC "any". (В представлении, используемом в системных каталогах, эти два параметра объединяются в один элемент VARIADIC "any", поскольку pg_proc не может представлять функции с более чем одним параметром VARIADIC.) Если агрегат является гипотетически-множественным, прямые аргументы, которые соответствуют параметру VARIADIC "any", являются гипотетическими; любые предшествующие параметры представляют дополнительные прямые аргументы, которые не ограничены необходимостью соответствовать агрегированным аргументам.

В настоящее время упорядоченно-множественные агрегаты не нуждаются в поддержке режима подвижного агрегата, поскольку они не могут использоваться в качестве оконных функций.

Частичная (включая параллельную) агрегация в настоящее время не поддерживается для упорядоченно-множественных агрегатов. Кроме того, она никогда не будет использоваться для вызовов агрегатов, которые включают предложения DISTINCT или ORDER BY, поскольку эта семантика не может поддерживаться во время частичной агрегации.

Примеры

См. Раздел 5.1.12.

Совместимость

CREATE AGGREGATE является расширением языка Digital Q.DataBase. Стандарт SQL не предусматривает пользовательские агрегатные функции.

См. также