Пакет

Оконные (аналитические) функцииКонтекстные переменные

Пакет `RDB$BLOB_UTIL`

Пакет RDB$BLOB_UTIL предназначен для управления BLOB-объектами так, как это не могут сделать стандартные функции Firebirdтакие, как BLOB_APPEND и SUBSTRING, или они работают очень медленно.

Эти подпрограммы работают с двоичными данными напрямую, даже с текстовыми BLOB.

Функция `RDB$BLOB_UTIL.NEW_BLOB`

Функция RDB$BLOB_UTIL.NEW_BLOB используется для создания нового BLOB. Он возвращает BLOB, подходящий для добавления данных, как это делает BLOB_APPEND.

Преимущество по сравнению с BLOB_APPEND заключается в том, что можно установить собственные параметры SEGMENTED и TEMP_STORAGE.

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

Возвращённый BLOB из этой функции, даже если TEMP_STORAGE = FALSE, может использоваться с BLOB_APPEND для добавления данных.

Table 1. Входные параметры функции `RDB$BLOB_UTIL.NEW_BLOB`
Параметр	Тип	Описание
`SEGMENTED`	`BOOLEAN NOT NULL`	Тип BLOB. Если TRUE - будет создан сегментированный BLOB, FALSE - потоковый.
`TEMP_STORAGE`	`BOOLEAN NOT NULL`	В каком хранилище создаётся BLOB. TRUE - во временном, FALSE - в постоянном (для записи в обычную таблицу).

Тип возвращаемого результата

BLOB SUB_TYPE BINARY

Функция `RDB$BLOB_UTIL.OPEN_BLOB`

Функция RDB$BLOB_UTIL.OPEN_BLOB используется для открытия существующего BLOB для чтения.Она возвращает дескриптор (целое число, связанное с транзакцией), подходящий для использования с другими функциями этого пакета,такими как SEEK, READ_DATA и CLOSE_HANDLE.

Table 2. Входные параметры функции `RDB$BLOB_UTIL.OPEN_BLOB`
Параметр	Тип	Описание
`BLOB`	`BLOB NOT NULL`	Входной BLOB.

Тип возвращаемого результата

INTEGER

Функция `RDB$BLOB_UTIL.IS_WRITABLE`

Функция RDB$BLOB_UTIL.IS_WRITABLE возвращает TRUE, если BLOB подходит для добавления данных без копирования с использованием BLOB_APPEND.

Table 3. Входные параметры функции `RDB$BLOB_UTIL.IS_WRITABLE`
Параметр	Тип	Описание
`BLOB`	`BLOB NOT NULL`	Проверяемый BLOB.

Тип возвращаемого результата

BOOLEAN

Функция `RDB$BLOB_UTIL.READ_DATA`

Функция RDB$BLOB_UTIL.READ_DATA используется для чтения фрагментов данных из дескриптора BLOB,открытого с помощью RDB$BLOB_UTIL.OPEN_BLOB. Когда BLOB полностью прочитан и данных больше нет, она возвращает NULL.

Если в LENGTH передаётся положительное число, то возвращается VARBINARY максимальной длины LENGTH.

Если в LENGTH передаётся NULL, то возвращается только сегмент BLOB с максимальной длиной 32765.

Table 4. Входные параметры функции `RDB$BLOB_UTIL.READ_DATA`
Параметр	Тип	Описание
`HANDLE`	`INTEGER NOT NULL`	Дескриптор открытого BLOB.
`LENGTH`	`INTEGER`	Количество байт, которое необходимо прочитать.

Тип возвращаемого результата

VARBINARY(32765)

Функция `RDB$BLOB_UTIL.SEEK`

Функция RDB$BLOB_UTIL.SEEK используется для установки позиции для следующего READ_DATA. Она возвращает новую позицию.

Параметр MODE может быть 0 (с начала), 1 (с текущей позиции) или 2 (с конца).

Когда параметр MODE равен 2, OFFSET должен быть нулевым или отрицательным.

Table 5. Входные параметры функции `RDB$BLOB_UTIL.SEEK`
Параметр	Тип	Описание
`HANDLE`	`INTEGER NOT NULL`	Дескриптор открытого BLOB.
`MODE`	`INTEGER NOT NULL`	Режим поиска.
`OFFSET`	`INTEGER NOT NULL`	Смещение, байт.

Тип возвращаемого результата

INTEGER

Процедура `RDB$BLOB_UTIL.CANCEL_BLOB`

Процедура RDB$BLOB_UTIL.CANCEL_BLOB используется для немедленного освобождения временного BLOB-объекта, например созданного с помощью BLOB_APPEND.

Обратите внимание, что если тот же BLOB используется после отмены, с использованием той же переменной или другой с той же ссылкой на идентификатор BLOB,то будет вызвана ошибка "invalid blob id error".

Table 6. Входные параметры процедуры `RDB$BLOB_UTIL.CANCEL_BLOB`
Параметр	Тип	Описание
`BLOB`	`BLOB NOT NULL`	BLOB для отмены.

Процедура `RDB$BLOB_UTIL.CLOSE_HANDLE`

Процедура RDB$BLOB_UTIL.CLOSE_HANDLE используется для закрытия дескриптора BLOB, открытого с помощью RDB$BLOB_UTIL.OPEN_BLOB.

Незакрытые дескрипторы закрываются автоматически только при завершении транзакции.

Table 7. Входные параметры процедуры `RDB$BLOB_UTIL.CLOSE_HANDLE`
Параметр	Тип	Описание
`HANDLE`	`INTEGER NOT NULL`	Дескриптор BLOB для закрытия.

Примеры использования `RDB$BLOB_UTIL`

Example 1. Создание BLOB во временном пространстве и возврат его в EXECUTE BLOCK

execute block returns (b blob)
as
begin
    -- Create a BLOB handle in the temporary space.
    b = rdb$blob_util.new_blob(false, true);

    -- Add chunks of data.
    b = blob_append(b, '12345');
    b = blob_append(b, '67');

    suspend;
end

Example 2. Открытие BLOB и его возврат по частям в EXECUTE BLOCK

execute block returns (s varchar(10))
as
    declare b blob = '1234567';
    declare bhandle integer;
begin
    -- Open the BLOB and get a BLOB handle.
    bhandle = rdb$blob_util.open_blob(b);

    -- Get chunks of data as string and return.

    s = rdb$blob_util.read_data(bhandle, 3);
    suspend;

    s = rdb$blob_util.read_data(bhandle, 3);
    suspend;

    s = rdb$blob_util.read_data(bhandle, 3);
    suspend;

    -- Here EOF is found, so it returns NULL.
    s = rdb$blob_util.read_data(bhandle, 3);
    suspend;

    -- Close the BLOB handle.
    execute procedure rdb$blob_util.close_handle(bhandle);
end

Example 3. Поиск в BLOB

set term !;

execute block returns (s varchar(10))
as
    declare b blob;
    declare bhandle integer;
begin
    -- Create a stream BLOB handle.
    b = rdb$blob_util.new_blob(false, true);

    -- Add data.
    b = blob_append(b, '0123456789');

    -- Open the BLOB.
    bhandle = rdb$blob_util.open_blob(b);

    -- Seek to 5 since the start.
    rdb$blob_util.seek(bhandle, 0, 5);
    s = rdb$blob_util.read_data(bhandle, 3);
    suspend;

    -- Seek to 2 since the start.
    rdb$blob_util.seek(bhandle, 0, 2);
    s = rdb$blob_util.read_data(bhandle, 3);
    suspend;

    -- Advance 2.
    rdb$blob_util.seek(bhandle, 1, 2);
    s = rdb$blob_util.read_data(bhandle, 3);
    suspend;

    -- Seek to -1 since the end.
    rdb$blob_util.seek(bhandle, 2, -1);
    s = rdb$blob_util.read_data(bhandle, 3);
    suspend;
end!

set term ;!

Example 4. Поверка доступен ли BLOB для записи

create table t(b blob);

set term !;

execute block returns (bool boolean)
as
    declare b blob;
begin
    b = blob_append(null, 'writable');
    bool = rdb$blob_util.is_writable(b);
    suspend;

    insert into t (b) values ('not writable') returning b into b;
    bool = rdb$blob_util.is_writable(b);
    suspend;
end!

set term ;!

Пакет `RDB$PROFILER`

Пакет RDB$PROFILER предназначен для управления сеансами профилирования.

Note

Пакет RDB$PROFILER для управления профилировщиком является стандартным, хотя сам профилировщикявляется подключаемым модулем. Используемый профилировщик зависит от настройки DefaultProfilerPluginв файле firebird.conf или databases.conf или от параметра PLUGIN_NAME в функции START_SESSION.
Firebird 5.0 поставляется с подключаемым модулем профилировщика под названием Default_Profiler.
Пользователям разрешено профилировать свои собственные подключения. Для профилирования подключений других пользователей требуется системная привилегия PROFILE_ANY_ATTACHMENT.

Подробное описание таблиц и представлений плагина профилирования Default_Profiler см. в приложении Таблицы плагинов. Плагин профилирования Default_Profiler.

Функция `START_SESSION`

Функция RDB$PROFILER.START_SESSION запускает новый сеанс профилировщика, превращает его в текущий сеанс (для заданного ATTACHMENT_ID) и возвращает его идентификатор.

Table 1. Входные параметры процедуры `RDB$PROFILER.START_SESSION`
Параметр	Тип	Описание
`DESCRIPTION`	`VARCHAR(255) CHARACTER SET UTF8`	Пользовательское описание сеанса профилирования. По умолчанию `NULL`.
`FLUSH_INTERVAL`	`INTEGER`	Интервал автоматического сброса статистики в таблицы снимков. По умолчанию `NULL`. Измеряется в секундах.
`ATTACHMENT_ID`	`BIGINT`	Идентификатор соединения для которого запускается сеанс профилирования. По умолчанию `CURRENT_CONNECTION`.
`PLUGIN_NAME`	`VARCHAR(255) CHARACTER SET UTF8`	Наименование плагина профилирования. По умолчанию `NULL`, что обозначает что будет использоваться плагин профилирования указанный в параметре конфигурации `DefaultProfilerPlugin`.
`PLUGIN_OPTIONS`	`VARCHAR(255) CHARACTER SET UTF8`	Параметры специфичные для плагина профилирования. По умолчанию `NULL`.

Тип выходного результата: BIGINT NOT NULL.

Если параметр FLUSH_INTERVAL отличен от NULL, то включается автоматический сброс статистики так же, как при вызове RDB$PROFILER.SET_FLUSH_INTERVAL вручную.

Если параметр PLUGIN_NAME имеет значение NULL (по умолчанию), он использует конфигурацию базы данных из параметра DefaultProfilerPlugin.

Для плагина Default_Profiler допустимыми значениями параметра PLUGIN_OPTIONS является NULL или строка DETAILED_REQUESTS.

Если указана опция DETAILED_REQUESTS, то таблица PLG$PROF_REQUESTS будет хранить подробные данные запросов, то есть одну запись для каждого вызова оператора. Это может привести к созданию большого количества записей, что приведёт к медленной работе RDB$PROFILER.FLUSH.

Когда DETAILED_REQUESTS не используется (по умолчанию), таблица PLG$PROF_REQUESTS сохраняет агрегированную запись для каждого оператора, используя REQUEST_ID = 0.

Процедура `CANCEL_SESSION`

Процедура RDB$PROFILER.CANCEL_SESSION отменяет текущий сеанс профилировщика (для заданного ATTACHMENT_ID).

Все данные сеанса, присутствующие в плагине профилировщика, отбрасываются и не сбрасываются.

Уже сброшенные данные не удаляются автоматически.

Table 2. Входные параметры процедуры `RDB$PROFILER.CANCEL_SESSION`
Параметр	Тип	Описание
`ATTACHMENT_ID`	`BIGINT`	Идентификатор соединения для которого отменяется сеанс профилирования. По умолчанию `CURRENT_CONNECTION`.

Процедура `DISCARD`

Процедура RDB$PROFILER.DISCARD удаляет все сеансы (для заданного ATTACHMENT_ID) из памяти, не сбрасывая их.

Если есть активная сессия, она отменяется.

Table 3. Входные параметры процедуры `RDB$PROFILER.DISCARD`
Параметр	Тип	Описание
`ATTACHMENT_ID`	`BIGINT`	Идентификатор соединения для которого удаляются все сеансы профилирования. По умолчанию `CURRENT_CONNECTION`.

Процедура `FINISH_SESSION`

Процедура RDB$PROFILER.FINISH_SESSION завершает текущий сеанс профилировщика (для заданного ATTACHMENT_ID).

Table 4. Входные параметры процедуры `RDB$PROFILER.FINISH_SESSION`
Параметр	Тип	Описание
`FLUSH`	`BOOLEAN`	Сбрасывать ли текущую статистику профилирования в таблицы моментальных снимков.
`ATTACHMENT_ID`	`BIGINT`	Идентификатор соединения для которого завершается сеанс профилирования. По умолчанию `CURRENT_CONNECTION`.

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

Вызов RDB$PROFILER.FINISH_SESSION(TRUE) имеет тот же смысл, что и вызов RDB$PROFILER.FINISH_SESSION(FALSE), за которым следует RDB$PROFILER.FLUSH (с использованием того же ATTACHMENT_ID).

Процедура `FLUSH`

Процедура RDB$PROFILER.FLUSH обновляет таблицы моментальных снимков данными из сеансов профиля (для заданного ATTACHMENT_ID) в памяти.

Table 5. Входные параметры процедуры `RDB$PROFILER.FLUSH`
Параметр	Тип	Описание
`ATTACHMENT_ID`	`BIGINT`	Идентификатор соединения для которого обновляются таблицы моментальных снимков из сеансов профилирования. По умолчанию `CURRENT_CONNECTION`.

После обновления данные сохраняются в таблицах PLG$PROF_SESSIONS, PLG$PROF_STATEMENTS, PLG$PROF_RECORD_SOURCES, PLG$PROF_REQUESTS, PLG$PROF_PSQL_STATS и PLG$PROF_RECORD_SOURCE_STATS и могут быть прочитаны и проанализированы пользователем.

Данные обновляются с помощью автономной транзакции, поэтому если процедура вызывается в snapshot транзакции,данные не будут доступны для прямого чтения в той же транзакции.

После сброса завершённые сеансы удаляются из памяти.

Процедура `PAUSE_SESSION`

Процедура RDB$PROFILER.PAUSE_SESSION приостанавливает текущий сеанс профилировщика (для заданного ATTACHMENT_ID), после чего статистика для последующих выполненных операторов не собирается.

Table 6. Входные параметры процедуры `RDB$PROFILER.PAUSE_SESSION`
Параметр	Тип	Описание
`FLUSH`	`BOOLEAN`	Сбрасывать ли текущую статистику профилирования в таблицы моментальных снимков.
`ATTACHMENT_ID`	`BIGINT`	Идентификатор соединения для которого приостанавливается сеанс профилирования. По умолчанию `CURRENT_CONNECTION`.

Если параметр FLUSH имеет значение TRUE, таблицы моментальных снимков обновляются данными до текущего момента.В противном случае данные остаются только в памяти для последующего обновления.

Вызов RDB$PROFILER.PAUSE_SESSION(TRUE) имеет тот же смысл, что и вызов RDB$PROFILER.PAUSE_SESSION(FALSE), за которым следует RDB$PROFILER.FLUSH (с использованием того же ATTACHMENT_ID).

Процедура `RESUME_SESSION`

Процедура RDB$PROFILER.RESUME_SESSION возобновляет текущий сеанс профилировщика (для заданного ATTACHMENT_ID), если он был приостановлен, после чего вновь собирается статистика последующих выполненных операторов.

Table 7. Входные параметры процедуры `RDB$PROFILER.RESUME_SESSION`
Параметр	Тип	Описание
`ATTACHMENT_ID`	`BIGINT`	Идентификатор соединения для которого возобновляется сеанс профилирования. По умолчанию `CURRENT_CONNECTION`.

Процедура `SET_FLUSH_INTERVAL`

Процедура RDB$PROFILER.SET_FLUSH_INTERVAL включает периодическую автоматическую сброс статистики в таблицы моментальных снимков (когда FLUSH_INTERVAL больше 0) или выключает (когда FLUSH_INTERVAL равно 0).

Table 8. Входные параметры процедуры `RDB$PROFILER.SET_FLUSH_INTERVAL`
Параметр	Тип	Описание
`FLUSH_INTERVAL`	`INTEGER`	Интервал автоматического сброса статистики. Задаётся в секундах.
`ATTACHMENT_ID`	`BIGINT`	Идентификатор соединения для которого обновляются таблицы моментальных снимков из сеансов профилирования. По умолчанию `CURRENT_CONNECTION`.

Как работает профилирования SQL и PSQL кода

Профилировщик позволяет пользователям измерять стоимость производительности кода SQL и PSQL.

Это реализовано с помощью системного пакета в движке, передающего данные плагину профилировщика.

В этой документации части движка и плагина рассматриваются как единое целое, так как будет использоваться профилировщик по умолчанию (Default_Profiler).

Пакет RDB$PROFILER позволяет профилировать выполнение кода PSQL, собирая статистику о том, сколько раз выполнялась каждая строка, а также её минимальное, максимальное и накопленное время выполнения (с точностью до наносекунд), а также открывать и извлекать статистику неявных и явных SQL-курсоров.

Note	К сожалению профилировщик не может работать с базами данных 1 SQL-диалекта. Это происходит из-за того, что таблицы моментальных снимков содержат поля с типом BIGINT, которые нельзя создать в 1-диалекте.

Для сбора данных профиля пользователь должен сначала запустить сеанс профиля с помощью RDB$PROFILER.START_SESSION. Эта функция возвращает идентификатор сеанса профиля, который позже сохраняется в таблицах моментальных снимков профилировщика для запроса и анализа пользователем. Сеанс профилировщика может быть локальным (то же соединение) или удалённым (другое соединение).

Удалённое профилирование просто перенаправляет команды на удалённое соединение. Это позволяет клиенту одновременно профилировать несколько сеансов.Кроме того, локально или удалённо запущенный сеанс профилировщика может получать команды, выданные в другом соединении.

Для удалённых команд требуется, чтобы целевой сеанс находился в состоянии ожидания,то есть не выполнял других запросов. Когда они не простаивают, вызов блокируется в ожидании этого состояния.

Если удалённое соединение исходит от другого пользователя, вызывающий пользователь должен иметь системную привилегию PROFILE_ANY_ATTACHMENT.

После запуска сеанса в памяти начинает собираться статистика PSQL и SQL операторов. Обратите внимание, что сеанс профилировщика собирает данные только об операторах, выполненных только в том соединении, которое связанно с сеансом профилировщика.

Данные агрегируются и сохраняются для каждого запроса. При запросе таблиц моментальных снимков пользователь может выполнятьдополнительную агрегацию по операторам или использовать вспомогательные представления, которые делают это автоматически.

Сеанс профилирования может быть приостановлен для временного отключения сбора статистики. Его можно возобновить позже, чтобы вернуть сбор статистики в том же сеансе.

Новый сеанс профилировщика может быть запущен, когда уже есть активный сеанс. В этом случае текущий сеанс завершается как будто была вызвана процедураRDB$PROFILER.FINISH_SESSION(FALSE), поэтому таблицы моментальных снимков не обновляются в этот момент.

Чтобы проанализировать собранные данные, пользователь должен сбросить данные в таблицы моментальных снимков,что можно сделать, завершив или приостановив сеанс (с параметром FLUSH, установленным в TRUE) или вызвав RDB$PROFILER.FLUSH.Данные сбрасываются с помощью автономной транзакции (транзакция, запущенная и завершенная для конкретной цели обновления данных профилировщика).

Пример

Ниже приведён пример сеанса профилировщика и запросов для анализа данных.

Подготовка — создание таблицы и процедур, которые будут анализироваться.

create table tab (
    id integer not null,
    val integer not null
);

set term !;

create or alter function mult(p1 integer, p2 integer) returns integer
as
begin
    return p1 * p2;
end!

create or alter procedure ins
as
    declare n integer = 1;
begin
    while (n <= 1000)
    do
    begin
        if (mod(n, 2) = 1) then
            insert into tab values (:n, mult(:n, 2));
        n = n + 1;
    end
end!

set term ;!

Запуск профилирования.

select rdb$profiler.start_session('Profile Session 1') from rdb$database;

set term !;

execute block
as
begin
    execute procedure ins;
    delete from tab;
end!

set term ;!

execute procedure rdb$profiler.finish_session(true);

execute procedure ins;

select rdb$profiler.start_session('Profile Session 2') from rdb$database;

select mod(id, 5),
       sum(val)
  from tab
  where id <= 50
  group by mod(id, 5)
  order by sum(val);

execute procedure rdb$profiler.finish_session(true);

Анализ результатов профилирования.

set transaction read committed;

select * from plg$prof_sessions;

select * from plg$prof_psql_stats_view;

select * from plg$prof_record_source_stats_view;

select preq.*
  from plg$prof_requests preq
  join plg$prof_sessions pses
    on pses.profile_id = preq.profile_id and
       pses.description = 'Profile Session 1';

select pstat.*
  from plg$prof_psql_stats pstat
  join plg$prof_sessions pses
    on pses.profile_id = pstat.profile_id and
       pses.description = 'Profile Session 1'
  order by pstat.profile_id,
           pstat.request_id,
           pstat.line_num,
           pstat.column_num;

select pstat.*
  from plg$prof_record_source_stats pstat
  join plg$prof_sessions pses
    on pses.profile_id = pstat.profile_id and
       pses.description = 'Profile Session 2'
  order by pstat.profile_id,
           pstat.request_id,
           pstat.cursor_id,
           pstat.record_source_id;

Пакет

Пакет RDB$BLOB_UTIL

Функция RDB$BLOB_UTIL.NEW_BLOB

Функция RDB$BLOB_UTIL.OPEN_BLOB

Функция RDB$BLOB_UTIL.IS_WRITABLE

Функция RDB$BLOB_UTIL.READ_DATA

Функция RDB$BLOB_UTIL.SEEK

Процедура RDB$BLOB_UTIL.CANCEL_BLOB

Процедура RDB$BLOB_UTIL.CLOSE_HANDLE

Примеры использования RDB$BLOB_UTIL

Пакет RDB$PROFILER

Функция START_SESSION

Процедура CANCEL_SESSION

Процедура DISCARD

Процедура FINISH_SESSION

Процедура FLUSH

Процедура PAUSE_SESSION

Процедура RESUME_SESSION

Процедура SET_FLUSH_INTERVAL

Как работает профилирования SQL и PSQL кода

Пример

Пакет `RDB$BLOB_UTIL`

Функция `RDB$BLOB_UTIL.NEW_BLOB`

Функция `RDB$BLOB_UTIL.OPEN_BLOB`

Функция `RDB$BLOB_UTIL.IS_WRITABLE`

Функция `RDB$BLOB_UTIL.READ_DATA`

Функция `RDB$BLOB_UTIL.SEEK`

Процедура `RDB$BLOB_UTIL.CANCEL_BLOB`

Процедура `RDB$BLOB_UTIL.CLOSE_HANDLE`

Примеры использования `RDB$BLOB_UTIL`

Пакет `RDB$PROFILER`

Функция `START_SESSION`

Процедура `CANCEL_SESSION`

Процедура `DISCARD`

Процедура `FINISH_SESSION`

Процедура `FLUSH`

Процедура `PAUSE_SESSION`

Процедура `RESUME_SESSION`

Процедура `SET_FLUSH_INTERVAL`