5.1.13.1. Особенности TOAST

Как описано в разделе Раздел 5.1.2, Digital Q.DataBase может быть расширен для поддержки новых типов данных. Этот раздел описывает, как определять новые базовые типы, которые являются типами данных, определёнными ниже уровня языка SQL. Создание нового базового типа требует реализации функций для работы с типом на низкоуровневом языке, обычно C.

Примеры в этом разделе можно найти в complex.sql и complex.c в каталоге src/tutorial дистрибутива исходного кода. См. файл README в этом каталоге для инструкций о запуске примеров.

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

Предположим, мы хотим определить тип complex, который представляет комплексные числа. Естественным способом представления комплексного числа в памяти будет следующая структура C:

typedef struct Complex {
    double      x;
    double      y;
} Complex;

Нам нужно будет сделать этот тип передаваемым по ссылке, так как он слишком велик, чтобы поместиться в одно значение Datum.

В качестве внешнего строкового представления типа мы выбираем строку вида (x,y).

Входная и выходная функции обычно не сложны в написании, особенно выходная. Но при определении внешнего строкового представления типа помните, что вы должны в конечном итоге написать полный и надёжный парсер для этого представления в качестве вашей входной функции. Например:

PG_FUNCTION_INFO_V1(complex_in);

Datum
complex_in(PG_FUNCTION_ARGS)
{
    char       *str = PG_GETARG_CSTRING(0);
    double      x,
                y;
    Complex    *result;

    if (sscanf(str, " ( %lf , %lf )", &x, &y) != 2)
        ereport(ERROR,
                (errcode(ERRCODE_INVALID_TEXT_REPRESENTATION),
                 errmsg("invalid input syntax for type %s: \"%s\"",
                        "complex", str)));

    result = (Complex *) palloc(sizeof(Complex));
    result->x = x;
    result->y = y;
    PG_RETURN_POINTER(result);
}

Выходная функция может быть просто:

PG_FUNCTION_INFO_V1(complex_out);

Datum
complex_out(PG_FUNCTION_ARGS)
{
    Complex    *complex = (Complex *) PG_GETARG_POINTER(0);
    char       *result;

    result = psprintf("(%g,%g)", complex->x, complex->y);
    PG_RETURN_CSTRING(result);
}

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

Опционально, определяемый пользователем тип может предоставлять двоичные входные и выходные процедуры. Двоичный ввод/вывод обычно быстрее, но менее переносим, чем текстовый ввод/вывод. Как и с текстовым вводом/выводом, вам решать, как именно определить внешнее двоичное представление. Большинство встроенных типов данных пытаются предоставить машинно-независимое двоичное представление. Для complex мы будем использовать преобразователи двоичного ввода/вывода для типа float8:

PG_FUNCTION_INFO_V1(complex_recv);

Datum
complex_recv(PG_FUNCTION_ARGS)
{
    StringInfo  buf = (StringInfo) PG_GETARG_POINTER(0);
    Complex    *result;

    result = (Complex *) palloc(sizeof(Complex));
    result->x = pq_getmsgfloat8(buf);
    result->y = pq_getmsgfloat8(buf);
    PG_RETURN_POINTER(result);
}

PG_FUNCTION_INFO_V1(complex_send);

Datum
complex_send(PG_FUNCTION_ARGS)
{
    Complex    *complex = (Complex *) PG_GETARG_POINTER(0);
    StringInfoData buf;

    pq_begintypsend(&buf);
    pq_sendfloat8(&buf, complex->x);
    pq_sendfloat8(&buf, complex->y);
    PG_RETURN_BYTEA_P(pq_endtypsend(&buf));
}

Как только мы написали функции ввода/вывода и скомпилировали их в общую библиотеку, мы можем определить тип complex в SQL. Сначала мы объявляем его как тип-оболочку:

CREATE TYPE complex;

Это служит заполнителем, который позволяет нам ссылаться на тип во время определения его функций ввода/вывода. Теперь мы можем определить функции ввода/вывода:

CREATE FUNCTION complex_in(cstring)
    RETURNS complex
    AS 'filename'
    LANGUAGE C IMMUTABLE STRICT;

CREATE FUNCTION complex_out(complex)
    RETURNS cstring
    AS 'filename'
    LANGUAGE C IMMUTABLE STRICT;

CREATE FUNCTION complex_recv(internal)
   RETURNS complex
   AS 'filename'
   LANGUAGE C IMMUTABLE STRICT;

CREATE FUNCTION complex_send(complex)
   RETURNS bytea
   AS 'filename'
   LANGUAGE C IMMUTABLE STRICT;

Наконец, мы можем предоставить полное определение типа данных:

CREATE TYPE complex (
   internallength = 16,
   input = complex_in,
   output = complex_out,
   receive = complex_recv,
   send = complex_send,
   alignment = double
);

Когда вы определяете новый базовый тип, Digital Q.DataBase автоматически предоставляет поддержку массивов этого типа. Тип массива обычно имеет то же имя, что и базовый тип, с добавленным символом подчёркивания (_) в начале.

Как только тип данных существует, мы можем объявить дополнительные функции для предоставления полезных операций над типом данных. Затем операторы могут быть определены поверх функций, и, если необходимо, могут быть созданы классы операторов для поддержки индексации типа данных. Эти дополнительные слои обсуждаются в следующих разделах.

Если внутреннее представление типа данных имеет переменную длину, то внутреннее представление должно следовать стандартной схеме для данных переменной длины: первые четыре байта должны быть полем char[4], которое никогда не доступно напрямую (обычно называется vl_len_). Вы должны использовать макрос SET_VARSIZE() для сохранения общего размера данного (включая само поле длины) в этом поле и VARSIZE() для его извлечения. (Эти макросы существуют, потому что поле длины может быть закодировано в зависимости от платформы.)

Для дальнейших подробностей см. описание команды CREATE TYPE.