Составные типы

Первая форма CREATE TYPE создаёт составной тип. Составной тип задаётся списком имён атрибутов и типов данных. Также можно указать правило сортировки (collation) для атрибута, если его тип данных является сортируемым. Составной тип по сути совпадает со строковым типом таблицы, но использование CREATE TYPE позволяет избежать необходимости создавать фактическую таблицу, когда всё, что требуется, — это определить тип. Отдельный составной тип полезен, например, в качестве аргумента или возвращаемого типа функции.

Чтобы иметь возможность создать составной тип, вы должны иметь привилегию USAGE для всех типов атрибутов.

Перечисляемые типы

Вторая форма CREATE TYPE создаёт перечисляемый (enum) тип, как описано в Раздел 2.5.7. Для enum-типов указывается список заключённых в кавычки меток, каждая из которых должна быть короче NAMEDATALEN байт (64 байта в стандартной сборке Digital Q.DataBase). (Возможно создание перечисляемого типа с нулём меток, но такой тип нельзя использовать для хранения значений до тех пор, пока с помощью команды ALTER TYPE не будет добавлена хотя бы одна метка.)

Диапазонные типы

Третья форма CREATE TYPE создаёт новый диапазонный тип (range), как описано в Раздел 2.5.17.

subtype диапазонного типа может быть любым типом с ассоциированным классом операторов B-дерева (для определения порядка значений диапазонного типа). Обычно для определения порядка используется класс операторов B-дерева по умолчанию для подтипа; чтобы использовать нестандартный класс операторов, укажите его имя в параметре subtype_opclass. Если подтип является сортируемым и вы хотите использовать нестандартное правило сортировки в порядке диапазона, укажите нужное правило в параметре collation.

Необязательная функция canonical должна принимать один аргумент определяемого диапазонного типа и возвращать значение того же типа. Она используется для приведения значений диапазона к канонической форме, когда это применимо. Дополнительные сведения см. в Раздел 2.5.17.8. Создание функции canonical немного сложно, поскольку она должна быть определена до объявления диапазонного типа. Чтобы это сделать, необходимо сначала создать тип-оболочку, который является типом-заполнителем, не имеющим свойств, кроме имени и владельца. Это делается командой CREATE TYPE name без дополнительных параметров. Затем функцию можно объявить, используя тип-оболочку в качестве аргумента и результата, и, наконец, диапазонный тип можно объявить с тем же именем. Это автоматически заменяет запись типа-оболочки на корректный диапазонный тип.

Необязательная функция subtype_diff должна принимать два значения типа subtype в качестве аргументов и возвращать значение типа double precision, представляющее разницу между двумя заданными значениями. Хотя этот параметр необязателен, его указание позволяет значительно повысить эффективность GiST-индексов для столбцов диапазонного типа. Дополнительные сведения см. в Раздел 2.5.17.8.

Необязательный параметр multirange_type_name задаёт имя соответствующего мультидиапазонного типа. Если он не указан, это имя выбирается автоматически следующим образом. Если имя диапазонного типа содержит подстроку range, то имя мультидиапазонного типа формируется заменой подстроки range на multirange в имени диапазонного типа. В противном случае имя мультидиапазонного типа формируется добавлением суффикса _multirange к имени диапазонного типа.

Базовые типы

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

Параметры могут указываться в любом порядке, не только в том, который показан выше, и большинство из них необязательны. Вы должны зарегистрировать две или более функций (с помощью CREATE FUNCTION) перед определением типа. Поддерживающие функции input_function и output_function обязательны, в то время как функции receive_function, send_function, type_modifier_input_function, type_modifier_output_function, analyze_function и subscript_function необязательны. Как правило, эти функции должны быть написаны на C или другом низкоуровневом языке.

Функция input_function преобразует внешнее текстовое представление типа во внутреннее представление, используемое операторами и функциями, определёнными для типа. Функция output_function выполняет обратное преобразование. Функция ввода может быть объявлена как принимающая один аргумент типа cstring, или как принимающая три аргумента типов cstring, oid, integer. Первый аргумент — это вводимый текст в виде C-строки, второй аргумент — это собственный OID типа (за исключением типов массивов, которые вместо этого получают OID типа элемента), а третий — typmod целевого столбца, если он известен (если нет, будет передано -1). Функция ввода должна возвращать значение самого типа данных. Обычно функция ввода должна быть объявлена как STRICT; если это не так, она будет вызвана с первым параметром NULL при чтении входного значения NULL. В этом случае функция всё равно должна возвращать NULL, если только она не вызывает ошибку. (Этот случай в основном предназначен для поддержки входных функций доменов, которые могут отклонять входные значения NULL.) Функция вывода должна быть объявлена как принимающая один аргумент нового типа данных. Функция вывода должна возвращать тип cstring. Функции вывода не вызываются для значений NULL.

Необязательная функция receive_function преобразует внешнее двоичное представление типа во внутреннее представление. Если эта функция не предоставлена, тип не может участвовать в двоичном вводе. Двоичное представление должно быть выбрано так, чтобы преобразование во внутреннюю форму было дешёвым, и при этом оставалось достаточно переносимым. (Например, стандартные целочисленные типы данных используют сетевой порядок байтов в качестве внешнего двоичного представления, в то время как внутреннее представление использует собственный порядок байтов машины.) Функция получения должна выполнять достаточную проверку, чтобы гарантировать, что значение корректно. Функция получения может быть объявлена как принимающая один аргумент типа internal, или как принимающая три аргумента типов internal, oid, integer. Первый аргумент — это указатель на буфер StringInfo, содержащий полученную байтовую строку; дополнительные аргументы такие же, как и для текстовой функции ввода. Функция получения должна возвращать значение самого типа данных. Обычно функция получения должна быть объявлена как STRICT; если это не так, она будет вызвана с первым параметром NULL при чтении входного значения NULL. В этом случае функция всё равно должна возвращать NULL, если только она не вызывает ошибку. (Этот случай в основном предназначен для поддержки функций получения доменов, которые могут отклонять входные значения NULL.) Аналогично, необязательная функция send_function преобразует из внутреннего представления во внешнее двоичное представление. Если эта функция не предоставлена, тип не может участвовать в двоичном выводе. Функция отправки должна быть объявлена как принимающая один аргумент нового типа данных. Функция отправки должна возвращать тип bytea. Функции отправки не вызываются для значений NULL.

На этом этапе вы можете задаться вопросом, как функции ввода и вывода могут быть объявлены с результатами или аргументами нового типа, когда они должны быть созданы до того, как можно создать новый тип. Ответ заключается в том, что тип сначала должен быть определён как тип-оболочка (shell type), который является типом-заполнителем, не имеющим свойств, кроме имени и владельца. Это делается с помощью команды CREATE TYPE name без дополнительных параметров. Затем C-функции ввода/вывода могут быть определены со ссылкой на тип-оболочку. Наконец, CREATE TYPE с полным определением заменяет запись-оболочку на полное, корректное определение типа, после чего новый тип может использоваться обычным образом.

Необязательные функции type_modifier_input_function и type_modifier_output_function необходимы, если тип поддерживает модификаторы, то есть дополнительные ограничения, прикреплённые к объявлению типа, такие как char(5) или numeric(30,2). Digital Q.DataBase позволяет пользовательским типам принимать одну или несколько простых констант или идентификаторов в качестве модификаторов. Однако эта информация должна быть способна упаковываться в одно неотрицательное целочисленное значение для хранения в системных каталогах. Функции type_modifier_input_function передаются объявленные модификаторы в виде массива cstring. Она должна проверить значения на корректность (выбросив ошибку, если они неверны), и если они корректны, вернуть одно неотрицательное integer значение, которое будет сохранено как «typmod» столбца. Модификаторы типа будут отклонены, если у типа нет type_modifier_input_function. Функция type_modifier_output_function преобразует внутреннее целочисленное значение typmod обратно в правильную форму для отображения пользователю. Она должна возвращать значение cstring, которое является точной строкой для добавления к имени типа; например, функция для numeric может возвращать (30,2). Разрешено опускать type_modifier_output_function, и в этом случае формат отображения по умолчанию — это просто сохранённое целочисленное значение typmod, заключённое в скобки.

Необязательная функция analyze_function выполняет специфичный для типа сбор статистики для столбцов этого типа данных. По умолчанию ANALYZE попытается собрать статистику, используя операторы «равно» и «меньше» типа, если для типа существует класс операторов B-дерева по умолчанию. Для нескалярных типов такое поведение, скорее всего, непригодно, поэтому его можно переопределить, указав пользовательскую функцию анализа. Функция анализа должна быть объявлена как принимающая один аргумент типа internal и возвращающая результат типа boolean. Подробный API для функций анализа приведён в src/include/commands/vacuum.h.

Необязательная функция subscript_function позволяет индексировать (обращаться по индексу) значения типа данных в SQL-командах. Указание этой функции не приводит к тому, что тип считается «настоящим» типом массива; например, он не будет кандидатом на тип результата конструкции ARRAY[]. Но если индексация значения типа является естественной нотацией для извлечения данных из него, то subscript_function может быть написана для определения того, что это означает. Функция индексации должна быть объявлена как принимающая один аргумент типа internal и возвращающая результат типа internal, который является указателем на структуру методов (функций), реализующих индексацию. Подробный API для функций индексации приведён в src/include/nodes/subscripting.h. Также может быть полезно прочитать реализацию массива в src/backend/utils/adt/arraysubs.c, или более простой код в contrib/hstore/hstore_subs.c. Дополнительная информация приведена в Array Types ниже.

Хотя детали внутреннего представления нового типа известны только функциям ввода/вывода и другим функциям, которые вы создаёте для работы с типом, есть несколько свойств внутреннего представления, которые должны быть объявлены для Digital Q.DataBase. Важнейшим из них является internallength. Базовые типы данных могут быть фиксированной длины, в этом случае internallength является положительным целым числом, или переменной длины, что указывается установкой internallength в VARIABLE. (Внутренне это представляется установкой typlen в -1.) Внутреннее представление всех типов переменной длины должно начинаться с 4-байтового целого числа, указывающего общую длину этого значения типа. (Обратите внимание, что поле длины часто кодируется, как описано в Раздел 7.15.2; обращаться к нему напрямую неразумно.)

Необязательный флаг PASSEDBYVALUE указывает, что значения этого типа данных передаются по значению, а не по ссылке. Типы, передаваемые по значению, должны иметь фиксированную длину, и их внутреннее представление не может быть больше размера типа Datum (4 байта на некоторых машинах, 8 байт на других).

Параметр alignment определяет требуемое выравнивание хранилища для типа данных. Допустимые значения соответствуют выравниванию по границам 1, 2, 4 или 8 байт. Обратите внимание, что типы переменной длины должны иметь выравнивание не менее 4, поскольку они обязательно содержат int4 в качестве первого компонента.

Параметр storage позволяет выбрать стратегию хранения для типов данных переменной длины. (Только plain разрешён для типов фиксированной длины.) plain указывает, что данные типа всегда будут храниться в строке и не сжиматься. extended указывает, что система сначала попытается сжать длинное значение данных и переместит значение из основной строки таблицы, если оно всё ещё слишком длинное. external позволяет переместить значение из основной таблицы, но система не будет пытаться сжать его. main допускает сжатие, но не поощряет перемещение значения из основной таблицы. (Элементы данных с этой стратегией хранения всё равно могут быть перемещены из основной таблицы, если нет другого способа уместить строку, но они будут сохраняться в основной таблице предпочтительнее элементов extended и external.)

Все значения storage, отличные от plain, подразумевают, что функции типа данных могут обрабатывать значения, которые были тостированы (toasted), как описано в Раздел 7.15.2 и Раздел 5.1.13.1. Конкретное другое заданное значение лишь определяет стратегию хранения TOAST по умолчанию для столбцов тостируемого типа данных; пользователи могут выбирать другие стратегии для отдельных столбцов с помощью ALTER TABLE SET STORAGE.

Параметр like_type предоставляет альтернативный метод указания основных свойств представления типа данных: скопировать их из некоторого существующего типа. Значения internallength, passedbyvalue, alignment и storage копируются из указанного типа. (Возможно, хотя обычно нежелательно, переопределить некоторые из этих значений, указав их вместе с предложением LIKE.) Указание представления таким способом особенно полезно, когда низкоуровневая реализация нового типа «заимствует» у существующего типа тем или иным образом.

Параметры category и preferred могут быть использованы для помощи в выборе неявного приведения в неоднозначных ситуациях. Каждый тип данных принадлежит категории, обозначаемой одним символом ASCII, и каждый тип является либо «предпочтительным», либо нет внутри своей категории. Анализатор предпочтёт приведение к предпочтительным типам (но только от других типов внутри той же категории), когда это правило полезно в разрешении перегруженных функций или операторов. Для получения более подробной информации см. Глава 2.7. Для типов, у которых нет неявных приведений к другим типам или из других типов, достаточно оставить эти настройки значениями по умолчанию. Однако для группы связанных типов, имеющих неявные приведения, часто полезно пометить их все как принадлежащие категории и выбрать один или два из «наиболее общих» типов как предпочтительные внутри категории. Параметр category особенно полезен при добавлении пользовательского типа в существующую встроенную категорию, такую как числовые или строковые типы. Однако также возможно создание полностью пользовательских категорий типов. Для названия такой категории выберите любой символ ASCII, кроме заглавной буквы.

Можно указать значение по умолчанию на случай, если пользователь захочет, чтобы столбцы типа данных по умолчанию имели значение, отличное от NULL. Укажите значение по умолчанию с помощью ключевого слова DEFAULT. (Такое значение по умолчанию может быть переопределено явным предложением DEFAULT, прикреплённым к конкретному столбцу.)

Чтобы указать, что тип является типом массива фиксированной длины, укажите тип элементов массива с помощью ключевого слова ELEMENT. Например, чтобы определить массив 4-байтовых целых чисел (int4), укажите ELEMENT = int4. Для получения дополнительной информации см. Array Types ниже.

Чтобы указать разделитель, используемый между значениями во внешнем представлении массивов этого типа, параметру delimiter можно присвоить определённый символ. Разделитель по умолчанию — запятая (,). Обратите внимание, что разделитель связан с типом элемента массива, а не с самим типом массива.

Если необязательный булев параметр collatable имеет значение true, определения столбцов и выражения типа могут нести информацию о сортировке (collation) через использование предложения COLLATE. Реализациям функций, работающих с типом, предоставляется возможность фактически использовать информацию о сортировке; это не происходит автоматически только из-за пометки типа как сортируемого.

Типы массивов

Всякий раз, когда создаётся пользовательский тип, Digital Q.DataBase автоматически создаёт связанный тип массива, имя которого состоит из имени типа элемента с предшествующим символом подчёркивания и усекается при необходимости, чтобы сохранить длину менее NAMEDATALEN байт. (Если сгенерированное имя конфликтует с именем существующего типа, процесс повторяется, пока не найдётся неконфликтующее имя.) Этот неявно созданный тип массива является типом переменной длины и использует встроенные функции ввода и вывода array_in и array_out. Более того, этот тип используется системой для конструкций типа ARRAY[] над пользовательским типом. Тип массива отслеживает любые изменения владельца или схемы его типа элемента и удаляется, если удаляется тип элемента.

Возможно, вы зададитесь вопросом, зачем нужна опция ELEMENT, если система создаёт правильный тип массива автоматически. Основной случай, когда полезно использовать ELEMENT, — это когда вы создаёте тип фиксированной длины, который внутренне представляет собой массив из нескольких одинаковых элементов, и вы хотите разрешить доступ к этим элементам напрямую через индексацию, в дополнение к любым операциям, которые вы планируете предоставить для типа в целом. Например, тип point представляется как просто два числа с плавающей запятой, к которым можно получить доступ с помощью point[0] и point[1]. Обратите внимание, что эта возможность работает только для типов фиксированной длины, внутренняя форма которых в точности представляет собой последовательность одинаковых полей фиксированной длины. По историческим причинам (т.е. это явно ошибка, но уже слишком поздно её менять) индексация типов массивов фиксированной длины начинается с нуля, а не с единицы, как для массивов переменной длины.

Указание опции SUBSCRIPT позволяет индексировать значения типа данных, даже если система в остальном не считает его типом массива. Поведение, описанное выше для массивов фиксированной длины, фактически реализуется функцией-обработчиком SUBSCRIPT raw_array_subscript_handler, которая используется автоматически, если вы указываете ELEMENT для типа фиксированной длины без явного указания SUBSCRIPT.

При указании пользовательской функции SUBSCRIPT нет необходимости указывать ELEMENT, если только функции-обработчику SUBSCRIPT не нужно обращаться к typelem, чтобы узнать, что возвращать. Имейте в виду, что указание ELEMENT приводит к тому, что система предполагает, что новый тип содержит или как-то физически зависит от типа элемента; таким образом, например, изменение свойств типа элемента не будет разрешено, если есть какие-либо столбцы зависимого типа.