CREATE TYPE

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

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

Вторая форма CREATE TYPE создает тип перечислений (ENUM), описанный в разделе Enumerated Types документации PostgreSQL. Типы ENUM принимают список меток в кавычках, каждая из которых должна быть короче NAMEDATALEN байт (64 в стандартной сборке).

Можно создать тип перечислений без меток, но такой тип нельзя использовать для хранения значений до тех пор, пока хотя бы одна метка не будет добавлена с помощью ALTER TYPE.

Третья форма CREATE TYPE создает новый диапазонный тип, описанный в разделе Range Types.

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

Необязательная функция canonical_function должна принимать один аргумент определяемого диапазонного типа и возвращать значение того же типа. Она используется для приведения значений диапазона к канонической форме, когда это применимо. Подробнее см. Defining New Range Types. Создание функции canonical_function — несколько нетривиальная задача, поскольку функция должна быть определена до объявления диапазонного типа. Для этого сначала необходимо создать тип-оболочку — тип-заглушку, у которого нет свойств, кроме имени и владельца. Такой тип создается командой CREATE TYPE <name> без дополнительных параметров. Затем функция может быть объявлена с использованием типа-оболочки в качестве аргумента и результата, и, наконец, диапазонный тип может быть объявлен с тем же именем. Это автоматически заменит запись типа-оболочки на полноценный диапазонный тип.

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

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

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

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

Необязательные функции type_modifier_input_function и type_modifier_output_function требуются, если тип поддерживает модификаторы. Модификаторы — это необязательные ограничения, прикрепленные к объявлению типа, такие как char(5) или numeric(30,2). Хотя Greengage DB позволяет пользовательским типам принимать одну или несколько простых констант или идентификаторов в качестве модификаторов, эта информация должна помещаться в одно неотрицательное целое число для хранения в системных каталогах. Greengage DB передает объявленные модификаторы в type_modifier_input_function в виде массива cstring. Функция ввода модификатора должна проверить значения на корректность и вывести ошибку, если они некорректны. Если значения корректны, функция ввода модификатора возвращает одно неотрицательное целое число, которое Greengage DB сохраняет в столбце typmod. Модификаторы типа отклоняются, если тип не был определен с type_modifier_input_function. Функция type_modifier_output_function преобразует внутреннее целочисленное значение typmod обратно в корректную форму для отображения пользователю. Функция вывода модификатора должна возвращать значение cstring, являющееся точной строкой, которая добавляется к имени типа. Например, функция типа numeric может вернуть (30,2). Функция type_modifier_output_function необязательна. Если она не указана, формат отображения по умолчанию — это сохраненное целочисленное значение typmod в скобках.

Чтобы разрешить кажущуюся циклическую зависимость (функции ввода/вывода требуют тип, который еще не существует), тип сначала определяется как "тип-оболочка" (shell type) — шаблон, у которого есть только имя и владелец. Для этого используется команда CREATE TYPE <name> без дополнительных параметров. Затем функции ввода/вывода можно определить с использованием ссылки на тип-оболочку. Наконец, команда CREATE TYPE с полным определением заменяет запись типа-оболочки полным, корректным определением типа, после чего новый тип можно использовать обычным образом.

Параметр like_type предоставляет альтернативный способ задания базовых свойств представления типа данных: скопировать их из существующего типа. Из указанного типа копируются значения internallength, passedbyvalue, alignment и storage. Хотя обычно это нежелательно, можно переопределить некоторые из этих значений, указав их вместе с выражением LIKE. Определение представления таким способом особенно полезно, когда низкоуровневая реализация нового типа тем или иным образом "паразитирует" на существующем типе.

Хотя детали внутреннего представления нового типа известны только функциям ввода/вывода и другим функциям, созданным для работы с этим типом, несколько свойств внутреннего представления необходимо объявить для Greengage DB. Наиболее важным из них является internallength. Базовые типы данных могут быть фиксированной длины (в этом случае internallength — положительное целое число) или переменной длины (что указывается установкой internallength в VARIABLE). Внутренне это представляется установкой typlen в -1. Внутреннее представление всех типов переменной длины должно начинаться с 4-байтового целого числа, задающего общую длину этого значения типа.

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

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

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

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

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

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

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

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

При создании пользовательского типа Greengage DB автоматически создает соответствующий тип массива, имя которого состоит из имени типа-элемента с добавлением подчеркивания в начале и при необходимости усекается, чтобы его длина не превышала число байт, заданных в константе NAMEDATALEN. Если сгенерированное имя конфликтует с существующим именем типа, процесс повторяется до нахождения неконфликтующего имени. Этот неявно созданный тип массива имеет переменную длину и использует встроенные функции ввода и вывода array_in и array_out. Тип массива отслеживает любые изменения владельца или схемы типа элемента и удаляется при удалении типа элемента.

Может возникнуть резонный вопрос: зачем нужен параметр ELEMENT, если система автоматически создает правильный тип массива? Единственный случай, когда полезно использовать ELEMENT, — это создание типа фиксированной длины, который внутренне представляет собой массив одинаковых элементов, и вы хотите разрешить доступ к этим элементам по индексу, в дополнение к любым операциям, предусмотренным для типа в целом. Например, тип point представлен просто двумя числами с плавающей запятой, к каждому из которых можно обратиться через point[0] и point[1]. Обратите внимание, что эта возможность работает только для типов фиксированной длины, внутренняя форма которых представляет собой последовательность одинаковых полей фиксированной длины. Тип переменной длины с поддержкой индексации должен иметь обобщенное внутреннее представление, используемое функциями array_in и array_out. По историческим причинам индексация массивов фиксированной длины начинается с нуля, а не с единицы, как для массивов переменной длины.