Руководство По Языку SQL СУБД Firebird 5.0 | Функции Для Работы Со Строками

Операторы процедурного SQL (PSQL)Агрегатные функции

`HEX_DECODE()`

Доступно в

DSQL, PSQL

Синтаксис

HEX_DECODE (hex_data)

Table 1. Параметры функции `HEX_DECODE`
Параметр	Описание
hex_data	Данные в шестнадцатеричном представлении.

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

VARBINARY или BLOB

Функция HEX_DECODE декодирует строку с шестнадцатеричными данными и возвращает декодированное значениекак VARBINARY или BLOB в зависимости от типа входного и размера аргумента.Если длина типа hex_data не кратна 2, во время подготовки возникает ошибка.Если длина значения hex_data не кратна 2, во время выполнения возникает ошибка.

Когда входной аргумент не является BLOB, то длина результирующего типа вычисляется как type_length / 2,где type_length — максимальная длина в байтах типа входного аргумента.

Примеры `HEX_DECODE`

Example 1. Использование функции HEX_DECODE

select cast(hex_decode('48657861646563696D616C') as varchar(12))
from rdb$database;

CAST
============
Hexadecimal

См. также:

[fblangref-scalarfuncs-hexencode], [fblangref-scalarfuncs-base64decode].

`HEX_ENCODE()`

Доступно в

DSQL, PSQL

Синтаксис

HEX_ENCODE (binary_data)

Table 1. Параметры функции `HEX_ENCODE`
Параметр	Описание
binary_data	Двоичные данные для кодирования

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

VARCHAR CHARACTER SET ASCII или BLOB SUB_TYPE TEXT CHARACTER SET ASCII

Функция HEX_ENCODE кодирует binary_data шестнадцатеричным числом и возвращает закодированное значениекак VARCHAR CHARACTER SET ASCII или BLOB SUB_TYPE TEXT CHARACTER SET ASCII в зависимости от входного аргумента.

Когда входной аргумент не является BLOB, то длина результирующего типа вычисляется как type_length * 2,где type_length — максимальная длина в байтах типа входного аргумента.

Примеры `HEX_ENCODE`

Example 1. Использование функции HEX_ENCODE

select hex_encode('Hexadecimal')
from rdb$database;

HEX_ENCODE
======================
48657861646563696D616C

См. также:

[fblangref-scalarfuncs-hexdecode], [fblangref-scalarfuncs-base64encode]

Функции для работы с датой и временем

`DATEADD()`

Доступно в

DSQL, PSQL

Синтаксис

DATEADD (<args>)

<args> ::= <amount> <unit> TO <datetime>
         | <unit>, <amount>, <datetime>

<unit> ::=
    YEAR | MONTH | WEEK | DAY | WEEKDAY | YEARDAY
  | HOUR | MINUTE | SECOND | MILLISECOND

Table 1. Параметры функции `DATEADD`
Параметр	Описание
amount	Выражение типа `SMALLINT`, `INTEGER`, `BIGINT` или `NUMERIC` (отрицательное вычитается).
unit	Составляющая даты/времени.
datetime	Выражение типа `DATE`, `TIME` или `TIMESTAMP`.

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

DATE, TIME или TIMESTAMP.

Функция DATEADD позволяет добавить заданное число лет, месяцев, недель, часов, минут, секунд, миллисекунд к заданному значению даты/времени.

Note	С аргументом типа `TIMESTAMP` и `DATE` можно использовать любую составляющую даты/времени <unit>; Для типа данных `TIME` разрешается использовать только `HOUR`, `MINUTE`, `SECOND` и `MILLISECOND`.

Примеры `DATEADD`

Example 1. Использование функции DATEADD

DATEADD (28 DAY TO CURRENT_DATE)
DATEADD (-6 HOUR TO CURRENT_TIME)
DATEADD (MONTH, 9, DATEOFCONCEPTION)
DATEADD (-38 WEEK TO DATEOFBIRTH)
DATEADD (MINUTE, 90, CAST('NOW' AS TIME))
DATEADD (? YEAR TO DATE '11-SEP-1973')

SELECT
  CAST(DATEADD(-1 * EXTRACT(MILLISECOND FROM ts) MILLISECOND TO ts) AS VARCHAR(30)) AS t,
  EXTRACT(MILLISECOND FROM ts) AS ms
FROM (
    SELECT TIMESTAMP'2014-06-09 13:50:17.4971' as ts
    FROM RDB$DATABASE
) a

T                             MS
------------------------------------
2014-06-09 13:50:17.0000	497.1

См. также:

[fblangref-scalarfuncs-datediff],[fblangref-datatypes-datetimeops].

`DATEDIFF()`

Доступно в

DSQL, PSQL

Синтаксис

DATEDIFF (<args>)

<args> ::= <unit> FROM <moment_1> TO <moment_2>
         | <unit>, <moment_1>, <moment_2>

<unit> ::=
    YEAR | MONTH | WEEK | DAY | WEEKDAY | YEARDAY
  | HOUR | MINUTE | SECOND | MILLISECOND

Table 1. Параметры функции `DATEDIFF`
Параметр	Описание
unit	Составляющая даты/времени.
monent_1	Выражение типа `DATE`, `TIME` или `TIMESTAMP`.
monent_2	Выражение типа `DATE`, `TIME` или `TIMESTAMP`.

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

BIGINT

Функция DATEDIFF возвращает количество лет, месяцев, недель, дней, часов, минут, секунд или миллисекунд между двумя значениями даты/времени.

Особенности использования:

Параметры DATE и TIMESTAMP могут использоваться совместно. Совместное использование типа TIME с типами DATE и TIMESTAMP не разрешается;
С аргументом типа TIMESTAMP и DATE можно использовать любую составляющую даты/времени <unit>;
Для типа данных TIME разрешается использовать только HOUR, MINUTE, SECOND и MILLISECOND.

Note

Функция DATEDIFF не проверяет разницу в более мелких составляющих даты/времени, чем задана в первом аргументе <unit>. В результате получаем:
- DATEDIFF (YEAR, DATE '1-JAN-2009', DATE '31-DEC-2009') вернёт 0, но
- DATEDIFF (YEAR, DATE '31-DEC-2009', DATE '1-JAN-2010') вернёт 1
Однако для более мелких составляющих даты/времени имеем:
- DATEDIFF (DAY, DATE '26-JUN-1908', DATE '11-SEP-1973') вернёт 23818
- DATEDIFF (DAY, DATE '30-NOV-1971', DATE '8-JAN-1972') вернёт 39
Отрицательное значение функции говорит о том, что дата/время в moment_2 меньше, чем в moment_1.

Примеры `DATEDIFF`

Example 1. Использование функции DATEDIFF

DATEDIFF (HOUR FROM CURRENT_TIMESTAMP TO TIMESTAMP '12-JUN-2059 06:00')
DATEDIFF (MINUTE FROM TIME '0:00' TO CURRENT_TIME)
DATEDIFF (MONTH, CURRENT_DATE, DATE '1-1-1900')
DATEDIFF (DAY FROM CURRENT_DATE TO CAST (? AS DATE))

См. также:

[fblangref-scalarfuncs-dateadd],[fblangref-datatypes-datetimeops].

`EXTRACT()`

Доступно в

DSQL, PSQL

Синтаксис

EXTRACT (<part> FROM <datetime>)

<part> ::=
    YEAR | QUARTER | MONTH | WEEK | DAY | WEEKDAY | YEARDAY
  | HOUR | MINUTE | SECOND | MILLISECOND
  | TIMEZONE_HOUR | TIMEZONE_MINUTE

Table 1. Параметры функции `EXTRACT`
Параметр	Описание
part	Составляющая даты/времени.
datetime	Выражение типа `DATE`, `TIME` или `TIMESTAMP`.

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

SMALLINT или NUNERIC

Функция EXTRACT извлекает составляющие даты и времени из типов данных DATE, TIME и TIMESTAMP.

Table 2. Типы и диапазоны результатов функции `EXTRACT`
Составляющая даты/времени	Тип	Диапазон	Комментарий
`YEAR`	`SMALLINT`	1–9999	Год
`QUARTER`	`SMALLINT`	1-4	Квартал
`MONTH`	`SMALLINT`	1–12	Месяц
`WEEK`	`SMALLINT`	1–53	Номер недели в году
`DAY`	`SMALLINT`	1–31	День
`WEEKDAY`	`SMALLINT`	0–6	День недели. 0 — Воскресенье
`YEARDAY`	`SMALLINT`	0–365	Номер дня в году. 0 = 1 января
`HOUR`	`SMALLINT`	0–23	Часы
`MINUTE`	`SMALLINT`	0–59	Минуты
`SECOND`	`NUMERIC(9,4)`	0.0000–59.9999	Секунды. Включает в себя миллисекунды
`MILLISECOND`	`NUMERIC(9,1)`	0.0–999.9	Миллисекунды
`TIMEZONE_HOUR`	`SMALLINT`	от -14 до +14	Смещение часов часового пояса
`TIMEZONE_MINUTE`	`SMALLINT`	от -59 до +59	Смещение минут часового пояса

Note	Если составляющая даты/времени не присутствует в аргументе дата/время, например SECOND в аргументе с типом DATE или YEAR в TIME, то функция вызовет ошибку.

Из аргумента с типом данных DATE или TIMESTAMP можно извлекать номер недели.В соответствии со стандартом ISO-8601 неделя начинается с понедельника и всегда включает в себя 7 дней.Первой неделей года является первая неделя, у которой в ней больше дней в новом году (по крайней мере, 4): дни 1-3 могут принадлежать предыдущей неделе (52 или 53) прошлого года.По аналогии дни 1-3 текущего года могут принадлежать 1 неделе следующего года.

Example 1. Использование функции EXTRACT

/* получить по дате номер квартала */
SELECT (EXTRACT(MONTH FROM CURRENT_TIMESTAMP)-1)/3+1
FROM RDB$DATABASE

См. также:

Типы данных для работы с датой и временем.

`FIRST_DAY()`

Доступно в

DSQL, PSQL

Синтаксис

FIRST_DAY(OF <period> FROM date_or_timestamp)

<period> ::= YEAR | QUARTER | MONTH | WEEK

Table 1. Параметры функции `FIRST_DAY`
Параметр	Описание
date_or_timestamp	Выражение типа `DATE` или `TIMESTAMP [WITH

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

DATE или TIMESTAMP [WITH | WITHOUT] TIME ZONE

Возвращает первый день года, месяца или недели для заданной даты.

Note	Первым днём недели считается воскресенье, как это возвращает функция `EXTRACT` с частью `WEEKDAY`. Когда в качестве аргумента функции передаётся выражение типа `TIMESTAMP`, то возвращаемое значение сохраняет временную часть.

Примеры `FIRST_DAY`

Example 1. Использование функции FIRST_DAY

SELECT FIRST_DAY(OF MONTH FROM current_date) FROM rdb$database;
SELECT FIRST_DAY(OF YEAR FROM current_timestamp) FROM rdb$database;
SELECT FIRST_DAY(OF WEEK FROM date '2017-11-01') FROM rdb$database;

См. также:

[fblangref-scalarfuncs-lastday].

`LAST_DAY()`

Доступно в

DSQL, PSQL

Синтаксис

LAST_DAY(OF <period> FROM date_or_timestamp)

<period> ::=  YEAR | QUARTER | MONTH | WEEK

Table 1. Параметры функции `LAST_DAY`
Параметр	Описание
date_or_timestamp	Выражение типа `DATE` или `TIMESTAMP [WITH

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

DATE или TIMESTAMP [WITH | WITHOUT] TIME ZONE

Возвращает последний день года, месяца или недели для заданной даты.

Note	Последним днём недели считается суббота, как это возвращает функция `EXTRACT` с частью `WEEKDAY`. Когда в качестве аргумента функции передаётся выражение типа `TIMESTAMP`, то возвращаемое значение сохраняет временную часть.

Примеры `LAST_DAY`

Example 1. Использование функции LAST_DAY

SELECT LAST_DAY(OF MONTH FROM current_date) FROM rdb$database;
SELECT LAST_DAY(OF YEAR FROM current_timestamp) FROM rdb$database;
SELECT LAST_DAY(OF WEEK FROM date '2017-11-01') FROM rdb$database;

См. также:

[fblangref-scalarfuncs-firstday].

Функции для работы с типом BLOB

`BLOB_APPEND()`

Доступно в

DSQL, PSQL

Синтаксис

BLOB_APPEND(<blob> [, <value1>, ... <valueN]>

Table 1. Параметры функции `BLOB_APPEND`
Параметр	Описание
blob	BLOB или NULL.
value	Значение любого типа.

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

временный не закрытый BLOB с флагом BLB_close_on_read.

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

Входные аргументы:

Для первого аргумента в зависимости от его значения определено следующее поведение функции:
- NULL: будет создан новый пустой не закрытый BLOB
- постоянный BLOB (из таблицы) или временный уже закрытый BLOB:будет создан новый пустой не закрытый BLOB и содержимоепервого BLOB будет в него добавлено
- временный не закрытый BLOB: он будет использован далее
- другие типы данных преобразуются в строку, будет создан временный не закрытый BLOB с содержимым этой строки
остальные аргументы могут быть любого типа. Для них определено следующее поведение:
- NULL игнорируется
- не BLOB преобразуются в строки (по обычным правилам) и добавляются к содержимомурезультата
- BLOB при необходимости транслитерируются к набору символов первого аргумента и ихсодержимое добавляется к результату

В качестве выходного значения функция BLOB_APPEND возвращает временный не закрытый BLOB с флагом BLB_close_on_read.Это или новый BLOB, или тот же, что был в первом аргументе. Таким образом ряд операций видаblob = BLOB_APPEND(blob, …) приведёт к созданию не более одного BLOB (если не пытаться добавить BLOB к самому себе).Этот BLOB будет автоматически закрыт движком при попытке прочитать его клиентом, записать в таблицу или использовать в других выражениях, требующих чтения содержимого.

Note	Проверка BLOB на значение NULL с помощью оператора `IS [NOT] NULL` не читает его, а следовательно временный BLOBне будет закрыт при таких проверках.

execute block
returns (b blob sub_type text)
as
begin
  -- создаст новый временный не закрытый BLOB
  -- и запишет в него строку из 2-ого аргумента
  b = blob_append(null, 'Hello ');
  -- добавляет во временный BLOB две строки не закрывая его
  b = blob_append(b, 'World', '!');
  -- сравнение BLOB со строкой закроет его, ибо для этого надо прочитать BLOB
  if (b = 'Hello World!') then
  begin
  -- ...
  end
  -- создаст временный закрытый BLOB добавив в него строку
  b = b || 'Close';
  suspend;
end

Tip	Используйте функции `LIST` и `BLOB_APPEND` для конкатенации BLOB. Это позволит сэкономить объём потребляемой памяти,дисковый ввод/вывод, а также предотвратит разрастание базы данных из-за создания множества временных BLOB при использовании операторов конкатенации.

Example 1. Использование функции BLOB_APPEND

Предположим вам надо собрать JSON на стороне сервера. У нас есть PSQL пакет JSON_UTILS с набором функций дляпреобразования элементарных типов данных в JSON нотацию. Тогда сборка JSON с использованием функции BLOB_APPEND будет выглядетьследующим образом:

EXECUTE BLOCK
RETURNS (
    JSON_STR BLOB SUB_TYPE TEXT CHARACTER SET UTF8)
AS
  DECLARE JSON_M BLOB SUB_TYPE TEXT CHARACTER SET UTF8;
BEGIN
  FOR
      SELECT
          HORSE.CODE_HORSE,
          HORSE.NAME,
          HORSE.BIRTHDAY
      FROM HORSE
      WHERE HORSE.CODE_DEPARTURE = 15
      FETCH FIRST 1000 ROW ONLY
      AS CURSOR C
  DO
  BEGIN
    SELECT
      LIST(
          '{' ||
          JSON_UTILS.NUMERIC_PAIR('age', MEASURE.AGE) ||
          ',' ||
          JSON_UTILS.NUMERIC_PAIR('height', MEASURE.HEIGHT_HORSE) ||
          ',' ||
          JSON_UTILS.NUMERIC_PAIR('length', MEASURE.LENGTH_HORSE) ||
          ',' ||
          JSON_UTILS.NUMERIC_PAIR('chestaround', MEASURE.CHESTAROUND) ||
          ',' ||
          JSON_UTILS.NUMERIC_PAIR('wristaround', MEASURE.WRISTAROUND) ||
          ',' ||
          JSON_UTILS.NUMERIC_PAIR('weight', MEASURE.WEIGHT_HORSE) ||
          '}'
      ) AS JSON_M
    FROM MEASURE
    WHERE MEASURE.CODE_HORSE = :C.CODE_HORSE
    INTO JSON_M;

    JSON_STR = BLOB_APPEND(
      JSON_STR,
      IIF(JSON_STR IS NULL, '[', ',' || ascii_char(13)),
      '{',
      JSON_UTILS.INTEGER_PAIR('code_horse', C.CODE_HORSE),
      ',',
      JSON_UTILS.STRING_PAIR('name', C.NAME),
      ',',
      JSON_UTILS.TIMESTAMP_PAIR('birthday', C.BIRTHDAY),
      ',',
      JSON_UTILS.STRING_VALUE('measures') || ':[', JSON_M, ']',
      '}'
    );
  END
  JSON_STR = BLOB_APPEND(JSON_STR, ']');
  SUSPEND;
END

Аналогичный пример с использованием обычного оператора конкатенации ||работает в 18 раз медленнее, и делает в 1000 раз больше операций записи на диск.

Функции для работы с типом DECFLOAT

`COMPARE_DECFLOAT()`

Доступно в

DSQL, PSQL

Синтаксис

COMPARE_DECFLOAT (decfloat1, decfloat2)

Table 1. Параметры функции `COMPARE_DECFLOAT`
Параметр	Описание
decfloat1, decfloat2	Значения или выражения типа `DECFLOAT` или быть совместимыми с типом `DECFLOAT`.

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

SMALLINT

Функция COMPARE_DECFLOAT сравнивает два значения типа DECFLOAT, которые могут быть одинаковыми, разными или неупорядоченными.Замыкающие нули учитываются при сравнении.

Функция возвращает:

`0`	Значения равны;
`1`	Первое значение меньше чем второе;
`2`	Первое значение больше чем второе;
`3`	Значения не упорядочены (одно или оба `NaN`/`sNaN`).

В отличие от операторов сравнения (‘<’, ‘=’, ‘>’ и др.) сравнение является точным,т.е. COMPARE_DECFLOAT(2.17, 2.170) вернёт 2, а не 0.

См. также:[fblangref-scalarfuncs-totalorder]

`NORMALIZE_DECFLOAT()`

Доступно в

DSQL, PSQL

Синтаксис

NORMALIZE_DECFLOAT (decfloat_value)

Table 1. Параметры функции `NORMALIZE_DECFLOAT`
Параметр	Описание
decfloat_value	Значение или выражение типа `DECFLOAT` или быть совместимым с типом `DECFLOAT`.

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

DECFLOAT

Функция NORMALIZE_DECFLOAT возвращает число в нормализованном виде.Это обозначает, что для любого ненулевого значения удаляются завершающие нули с соответствующей коррекцией экспоненты.

Примеры `NORMALIZE_DECFLOAT`

Example 1. Нормализация различных значений типа DECFLOAT

NORMALIZE_DECFLOAT(12.00) -- возвращает 12
NORMALIZE_DECFLOAT(120) -- возвращает 1.2E+2

`QUANTIZE()`

Доступно в

DSQL, PSQL

Синтаксис

QUANTIZE (decfloat_value, exp_value)

Table 1. Параметры функции `QUANTIZE`
Параметр	Описание
decfloat_value	Значение или выражение типа `DECFLOAT` или быть совместимым с типом `DECFLOAT`.
exp_value	Значение или выражение для использования в качестве показателя степени;должно иметь тип `DECFLOAT` или быть совместимым с типом `DECFLOAT`.

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

DECFLOAT

Функция QUANTIZE возвращает значение первого аргумента масштабированным с использованием второго значения в качестве шаблона.Другими словами функция QUANTIZE возвращает значение DECFLOAT, равное по значению (за исключением любого округления) и знаку decfloat_value, а также экспоненте, равной по значению экспоненте exp_value.Функцию QUANTIZE можно использовать для реализации округления с точностью до нужного знака, например, округление до ближайшего цента с использованием установленного режима округления DECFLOAT.

Тип возвращаемого значения — DECFLOAT(16), если оба аргумента — DECFLOAT(16), в противном случае тип результата — DECFLOAT(34).

Note

Целевой показатель — это показатель, используемый в формате хранения Decimal64 или Decimal128 для DECFLOAT из exp_value.Это не обязательно то же самое, что экспонента, отображаемая в таких инструментах, как isql.Например, значение 1.23E+2 - это коэффициент 123 и показатель степени 0,а значение 1.2 - это коэффициент 12 и показатель степени -1.

Если показатель decfloat_value больше, чем показатель exp_value, коэффициент decfloat_value умножается на степень десяти, и его показатель уменьшается, если показатель меньше, то его коэффициент округляется с использованием текущего режима округления decfloat, и его показатель увеличивается.

Когда невозможно достичь целевого показателя экспоненты, поскольку коэффициент превысит целевую точность (16 или 34 десятичных знака), то либо возникает ошибка “Decfloat float invalid operation”, либо возвращается NaN (в зависимости от текущего конфигурация decfloat traps).

Ограничений на exp_value практически нет.Однако почти во всех случаях использования NaN/sNaN/Infinity будет вызывать исключение(если это не разрешено текущей конфигурацией decfloat traps)

Если одно из значений NULL, то результатом функции будет NULL и т.д.

Example 1. Использование функции QUANTIZE

select v, pic, quantize(v, pic) from examples;

V                       PIC                   QUANTIZE
======================= ===================== ==================
                   3.16                 0.001              3.160
                   3.16                 0.01               3.16
                   3.16                 0.1                3.2
                   3.16                 1                  3
                   3.16                 1E+1               0E+1
                   -0.1                 1                 -0
                      0                 1E+5               0E+5
                    316                 0.1              316.0
                    316                 1                316
                    316                 1E+1             3.2E+2
                    316                 1E+2               3E+2

`TOTALORDER()`

Доступно в

DSQL, PSQL

Синтаксис

TOTALORDER (decfloat1, decfloat2)

Table 1. Параметры функции `TOTALORDER`
Параметр	Описание
decfloat1, decfloat2	Значение или выражение типа `DECFLOAT` или быть совместимым с типом `DECFLOAT`.

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

SMALLINT

Функция TOTALORDER сравнивает два значения типа DECFLOAT, включая специальные значения.Сравнение является точным. Замыкающие нули учитываются при сравнении.

Функция возвращает:

-1 — если первое значение меньше второго;
0 — если значения равны;
1 — если первое значение больше второго.

Сравнений значений DEFLOAT происходит в следующем порядке:

-nan < -snan < -inf < -0.1 < -0.10 < -0 < 0 < 0.10 < 0.1 < inf < snan < nan

См. также:[fblangref-scalarfuncs-comparedecfloat]

Криптографические функции

В Firebird 4.0 поддерживается только подмножество симметричных алгоритмов шифрования (как блочных так и потоковых), так и RSA.

`CRYPT_HASH()`

Доступно в

DSQL, PSQL

Синтаксис

CRYPT_HASH (value USING <algorithm>)

<algorithm> ::= { MD5 | SHA1 | SHA256 | SHA512 | SHA3_224 | SHA3_256 | SHA3_384 | SHA3_512 }

Table 1. Параметры функции `CRYPT_HASH`
Параметр	Описание
value	Выражение любого типа. Не строковые и не бинарные типы приводятся к строке.
algorithm	Алгоритм хеширования.

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

VARBINARY

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

Note	Алгоритмы `MD5` и `SHA1` не рекомендуются для использования из-за известных серьезных проблем, которые предоставляются только для обратной совместимости.

Примеры `CRYPT_HASH`

Example 1. Использование функции CRYPT_HASH

SELECT CRYPT_HASH(x USING SHA256) FROM MyTable;
-- результат типа VARBINARY

`DECRYPT()`

Доступно в

DSQL, PSQL

Синтаксис

DECRYPT (encrypted_input
  [USING <algorithm>] [MODE <mode>]
  KEY key
  [IV iv] [<ctr_type>] [CTR_LENGTH ctr_length]
  [COUNTER initial_counter] )

<algorithm> ::= <block_cipher> | <stream_cipher>

<block_cipher> ::=
    AES | ANUBIS | BLOWFISH | KHAZAD | RC5
  | RC6 | SAFER+ | TWOFISH | XTEA

<stream_cipher> ::= CHACHA20 | RC4 | SOBER128

<mode> ::= CBC | CFB | CTR | ECB | OFB

<ctr_type> ::= CTR_BIG_ENDIAN | CTR_LITTLE_ENDIAN

Table 1. Параметры функции `DECRYPT`
Параметр	Описание
encrypted_input	Зашифрованный BLOB или (двоичная) строка
algorithm	Алгоритм шифрования.Поддерживаются как блочные, так и потоковые алгоритмы.
mode	Режим шифрования.Обязателен для блочных алгоритмов шифрования.
key	Ключ шифрования.
iv	Вектор инициализации (IV). Должен быть указан для всех блочных алгоритмов шифрования за исключением `ECB` и всех потоковых алгоритмов шифрования за исключением `RC4`.
ctr_type	Порядок байтов счётчика.Может быть указан только в режиме `CTR`.По умолчанию используется `CTR_LITTLE_ENDIAN`.
ctr_length	Длина счётчика в байтах.Может быть указана только в режиме `CTR`.По умолчанию равна длине вектора инициализации IV.
initial_counter	Начальное значение счётчика.Может быть указана только для алгоритма `CHACHA20`.По умолчанию равно 0.

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

BLOB или VARBINARY.

Функция DECRYPT дешифрует данные с использованием симметричного шифра.Размеры строк передаваемых в эту функцию должны соответствовать требованиям выбранного алгоритма и режима.

Example 1. Использование функции DECRYPT

select decrypt(x'0154090759DF' using sober128 key 'AbcdAbcdAbcdAbcd'
               iv '01234567')
from rdb$database;

select decrypt(secret_field using aes mode ofb key '0123456701234567'
               iv init_vector)
from secure_table;

См. также:

[fblangref-scalarfuncs-encrypt].

`ENCRYPT()`

Доступно в

DSQL, PSQL

Синтаксис

ENCRYPT (input
  [USING <algorithm>] [MODE <mode>]
  KEY key
  [IV iv] [<ctr_type>] [CTR_LENGTH ctr_length]
  [COUNTER initial_counter] )

<algorithm> ::= <block_cipher> | <stream_cipher>

<block_cipher> ::=
    AES | ANUBIS | BLOWFISH | KHAZAD | RC5
  | RC6 | SAFER+ | TWOFISH | XTEA

<stream_cipher> ::= CHACHA20 | RC4 | SOBER128

<mode> ::= CBC | CFB | CTR | ECB | OFB

<ctr_type> ::= CTR_BIG_ENDIAN | CTR_LITTLE_ENDIAN

Table 1. Параметры функции `ENCRYPT`
Параметр	Описание
input	Выражение строкового типа или `BLOB`, которое необходимо зашифровать.
algorithm	Алгоритм шифрования.Поддерживаются как блочные, так и потоковые алгоритмы.
mode	Режим шифрования.Обязателен для блочных алгоритмов шифрования.
key	Ключ шифрования.
iv	Вектор инициализации (IV). Должен быть указан для всех блочных алгоритмов шифрования за исключением `ECB` и всех потоковых алгоритмов шифрования за исключением `RC4`.
ctr_type	Порядок байтов счётчика.Может быть указан только в режиме `CTR`.По умолчанию используется `CTR_LITTLE_ENDIAN`.
ctr_length	Длина счётчика в байтах.Может быть указана только в режиме `CTR`.По умолчанию равна длине вектора инициализации IV.
initial_counter	Начальное значение счётчика.Может быть указана только для алгоритма `CHACHA20`.По умолчанию равно 0.

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

BLOB или VARBINARY

Функция ENCRYPT шифрует данные с использованием симметричного шифра.

Note

Эта функция возвращает BLOB SUB_TYPE BINARY, если первым аргументом является BLOB, и VARBINARY для всех других текстовых и двоичных типов.
Размеры строк (например, key и iv) передаваемых в эту функцию должны соответствовать требованиям выбранного алгоритма и режима.Подробнее см. таблицу [fblangref-scalarfuncs-tbl-encrypt-req].
- Как правило, размер iv должен соответствовать размеру блока алгоритма.
- Для режимов ECB и CBC input должен быть кратным размеру блока, вам нужно будет вручную заполнить нулями или пробелами, если это необходимо.

Особенности различных алгоритмов и режимов выходят за рамки данного справочника по языку.

Table 2. Требования алгоритмов шифрования
Алгоритм	Размер ключа (байт)	Размер блока (байт)	Примечание
Блочное шифрование
`AES`	16, 24, 32	16
`ANUBIS`	16 - 40, с шагом 4	16
`BLOWFISH`	8 - 56	8
`KHAZAD`	16	8
`RC5`	8 - 128	8
`RC6`	8 - 128	16
`SAFER+`	16, 24, 32	16
`TWOFISH`	16, 24, 32	16
`XTEA`	16	8
Поточное шифрование
`CHACHA20`	16, 32	1	Размер (IV) составляет 8 или 12 байт.Для размера 8 initial_counter - это 64-битное целое число, для размера 12 - 32-битное.
`RC4`	5 - 256	1
`SOBER128`	4x	1	Размер (IV) составляет 4y байт, длина не зависит от размера ключа.

Example 1. Использование функции ENCRYPT

select encrypt('897897' using sober128 key 'AbcdAbcdAbcdAbcd' iv '01234567')
from rdb$database;

См. также:

[fblangref-scalarfuncs-decrypt].

`RSA_PRIVATE()`

Доступно в

DSQL, PSQL

Синтаксис

RSA_PRIVATE (size)

Table 1. Параметры функции RSA_PRIVATE
Параметр	Описание
size	Размер ключа в байтах.

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

VARBINARY

Функция RSA_PRIVATE возвращает RSA закрытый ключ заданной длины (в байтах) в PKCS#1 формате как строку VARBINARY.

Example 1. Использование функции RSA_PRIVATE

select rdb$set_context('USER_SESSION', 'private_key', rsa_private(256))
from rdb$database;

См. также:

[fblangref-scalarfuncs-rsa_public].

`RSA_PUBLIC()`

Доступно в

DSQL, PSQL

Синтаксис

RSA_PUBLIC (private-key)

Table 1. Параметры функции RSA_PUBLIC
Параметр	Описание
private-key	RSA закрытый ключ.

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

VARBINARY

Функция RSA_PUBLIC возвращает RSA открытый ключ для заданного RSA закрытого ключа.Оба ключа должны быть в PKCS#1 формате.

Example 1. Использование функции RSA_PUBLIC

Закрытый ключ должен быть инициализирован ранее см.пример в RSA_PRIVATE

select rdb$set_context('USER_SESSION', 'public_key',
    rsa_public(rdb$get_context('USER_SESSION', 'private_key')))
from rdb$database;

См. также:

[fblangref-scalarfuncs-rsa_private].

`RSA_ENCRYPT()`

Доступно в

DSQL, PSQL

Синтаксис

RSA_ENCRYPT (<data> KEY <public_key> [LPARAM <tag>] [HASH <hash>])

<hash> ::= { MD5 | SHA1 | SHA256 | SHA512 }

Table 1. Параметры функции `RSA_ENCRYPT`
Параметр	Описание
data	Данные (строка или BLOB) для шифрования.
public_key	Открытый RSA ключ, который возвращает функция `RSA_PUBLIC`.
tag	Дополнительный системный тег, который можно применять для определения того, какая система закодировала сообщение.Значением по умолчанию является `NULL`.
hash	Алгоритм хеширования.По умолчанию SHA256.

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

VARBINARY

Заполняет данные, используя заполнение OAEP, и шифрует их, используя открытый ключ RSA.Обычно используется для шифрования коротких симметричных ключей, которые затем используются в блочных шифрах для шифрования сообщения.

Example 1. Использование функции RSA_ENCRYPT

Открытый ключ должен быть инициализирован ранее см.пример в [fblangref-scalarfuncs-rsa_public]

select rdb$set_context('USER_SESSION', 'msg',
    rsa_encrypt('Some message' key rdb$get_context('USER_SESSION', 'public_key')))
from rdb$database;

См. также:

[fblangref-scalarfuncs-rsa_public], [fblangref-scalarfuncs-rsa_decrypt].

`RSA_DECRYPT()`

Доступно в

DSQL, PSQL

Синтаксис

RSA_DECRYPT (<data> KEY <private_key> [LPARAM <tag>] [HASH <hash>])

<hash> ::= { MD5 | SHA1 | SHA256 | SHA512 }

Table 1. Параметры функции `RSA_DECRYPT`
Параметр	Описание
data	Данные (строка или BLOB) для дешифрования.
private_key	Закрытый RSA ключ, который возвращает функция `RSA_PRIVATE`.
tag	Дополнительный системный тег.Должно быть тем же самым значением, которое передавалось `RSA_ENCRYPT`.Если оно не совпадает с тем, который использовался во время кодирования, эта функция не расшифровывает пакет.Значением по умолчанию является `NULL`.
hash	Алгоритм хеширования.По умолчанию SHA256.

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

VARCHAR

Расшифровывает с использованием закрытого ключа RSA, и удаляет OAEP дополненные данные.

Example 1. Использование функции RSA_DECRYPT

Закрытый ключ должен быть инициализирован ранее см. пример в [fblangref-scalarfuncs-rsa_private].Данные для расшифровки используются из примера в [fblangref-scalarfuncs-rsa_encrypt].

select RSA_DECRYPT(rdb$get_context('USER_SESSION', 'msg')
    key rdb$get_context('USER_SESSION', 'private_key'))
from RDB$DATABASE;

См. также:

[fblangref-scalarfuncs-rsa_private], [fblangref-scalarfuncs-rsa_encrypt].

`RSA_SIGN_HASH()`

Доступно в

DSQL, PSQL

Синтаксис

RSA_SIGN_HASH (<data> KEY <private_key> [HASH <hash>] [SALT_LENGTH <length>])

<hash> ::= { MD5 | SHA1 | SHA256 | SHA512 }

Table 1. Параметры функции `RSA_SIGN_HASH`
Параметр	Описание
data	Данные (строка или BLOB) для кодирования.
private_key	Закрытый RSA ключ, который возвращает функция `RSA_PRIVATE`.
hash	Алгоритм хеширования.По умолчанию SHA256.
length	Указывает на длину желаемой соли и, как правило, должен быть небольшим.Хорошее значение от 8 до 16.

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

VARBINARY

Выполняет PSS-кодирование дайджеста сообщения для подписи и подписывает его с использованием закрытого ключа RSA.Возвращает подпись сообщения.

Example 1. Использование функции RSA_SIGN_HASH

Закрытый ключ должен быть инициализирован ранее см.пример в [fblangref-scalarfuncs-rsa_private].

select rdb$set_context('USER_SESSION', 'msg',
    rsa_sign_hash(crypt_hash('Test message' using sha256)
                  key rdb$get_context('USER_SESSION', 'private_key')))
from rdb$database;

См. также:

[fblangref-scalarfuncs-rsa_private], [fblangref-scalarfuncs-rsa_verify_hash].

`RSA_VERIFY_HASH()`

Доступно в

DSQL, PSQL

Синтаксис

RSA_VERIFY_HASH (<data> SIGNATURE <signature> KEY <public_key> [HASH <hash>]
  [SALT_LENGTH <length>])

<hash> ::= { MD5 | SHA1 | SHA256 | SHA512 }

Table 1. Параметры функции `RSA_VERIFY_HASH`
Параметр	Описание
data	Данные (строка или BLOB) для кодирования.
signature	Подпись.Должно быть значением возвращаемым функцией `RSA_SIGN_HASH`.
public_key	Открытый RSA ключ, который возвращает функция `RSA_PUBLIC`.
hash	Алгоритм хеширования.По умолчанию SHA256.
length	Указывает на длину желаемой соли и, как правило, должен быть небольшим.Хорошее значение от 8 до 16.

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

BOOLEAN

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

Example 1. Использование функции RSA_VERIFY_HASH

Открытый ключ должен быть инициализирован ранее см. пример в [fblangref-scalarfuncs-rsa_public].Цифровая подпись получена ранее с помощью функции [fblangref-scalarfuncs-rsa_sign_hash].

select rsa_verify_hash(crypt_hash('Test message' using sha256)
    signature rdb$get_context('USER_SESSION', 'msg')
    key rdb$get_context('USER_SESSION', 'public_key'))
from rdb$database;

См. также:

[fblangref-scalarfuncs-rsa_sign_hash], [fblangref-scalarfuncs-rsa_public].

Функции преобразования типов

`CAST()`

Доступно в

DSQL, PSQL

Синтаксис

CAST(value | NULL AS <type>)

<type> ::=
    <datatype>
  | [TYPE OF] domain
  | TYPE OF COLUMN relname.colname

<datatype> ::=
    <scalar_datatype> | <blob_datatype> | <array_datatype>

<scalar_datatype> ::=  См. Синтаксис скалярных типов данных

<blob_datatype> ::= См. Синтаксис типа данных BLOB

<array_datatype> ::= См. Синтаксис массивов

Table 1. Параметры функции CAST
Параметр	Описание
value	SQL выражение.
datatype	Тип данных SQL.
domain	Домен.
relname	Имя таблицы или представления.
colname	Имя столбца таблицы или представления.

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

<type>.

Функция CAST служит для явного преобразования данных из одного типа данных в другой тип данных или домен.Если это невозможно будет выдана ошибка.

Table 2. Допустимые преобразования для функции `CAST`
Из типа	В тип
Числовые типы	Числовые типы, `[VAR]CHAR`, `BLOB`
`[VAR]CHAR`, `BLOB`	`[VAR]CHAR`, `BLOB`, `BOOLEAN`, Числовые типы, `DATE`, `TIME`, `TIMESTAMP`
`DATE`, `TIME`	`[VAR]CHAR`, `BLOB`, `TIMESTAMP`
`TIMESTAMP`	`[VAR]CHAR`, `BLOB`, `TIME`, `DATE`
`BOOLEAN`	`[VAR]CHAR`, `BLOB`

Имейте в виду, что иногда информация может быть потерянна, например, когда вы преобразуете тип TIMESTAMP к DATE.Кроме того, тот факт, что типы совместимы для функции CAST, ещё не гарантирует, что преобразование будет успешным.“CAST (123456789 AS SMALLINT)” безусловно приведёт к ошибке, так же как и “CAST('Judgement Day' as DATE)”.

Вы можете применить преобразование типа к параметрам оператора:

CAST (? AS INTEGER)

Это дает вам контроль над типом полей ввода.

Преобразование к домену или к его базовому типу

При преобразовании к домену должны быть удовлетворены любые ограничения (NOT NULL и/или CHECK) объявленные для домена, иначе преобразование не будет выполнено.Помните, что проверка CHECK проходит, если его вычисление даёт TRUE или UNKNOWN (NULL). Для следующих операторов:

CREATE DOMAIN quint AS INT CHECK (VALUE >= 5000)
SELECT CAST (2000 AS quint) FROM rdb$database -- (1)
SELECT CAST (8000 AS quint) FROM rdb$database -- (2)
SELECT CAST (null AS quint) FROM rdb$database -- (3)

только (1) завершится с ошибкой.

При использовании модификатора TYPE OF выражение будет преобразовано к базовому типу домена, игнорируя любые ограничения.Для домена quint, объявленного выше, оба преобразования будут эквивалентны и оба будут успешно выполнены:

SELECT CAST (2000 AS TYPE OF quint) FROM rdb$database
SELECT CAST (2000 AS INT) FROM rdb$database

При использовании TYPE OF с [VAR]CHAR типом, его набор символов и порядок сортировки (collate) сохраняются.

CREATE DOMAIN iso20 VARCHAR(20) CHARACTER SET iso8859_1;
CREATE DOMAIN dunl20 VARCHAR(20) CHARACTER SET iso8859_1 COLLATE du_nl;
CREATE TABLE zinnen (zin VARCHAR(20));
COMMIT;
INSERT INTO zinnen VALUES ('Deze');
INSERT INTO zinnen VALUES ('Die');
INSERT INTO zinnen VALUES ('die');
INSERT INTO zinnen VALUES ('deze');
SELECT CAST(zin AS TYPE OF iso20) FROM zinnen ORDER BY 1;
-- returns Deze -> Die -> deze -> die
SELECT CAST(zin AS TYPE OF dunl20) FROM zinnen ORDER BY 1;
-- returns deze -> Deze -> die -> Die

Warning

Если определение домена изменяется, то существующие преобразования к домену или его типу могут стать ошибочными.Если такие преобразования происходят в PSQL модулях, то их ошибки могут быть обнаружены.См. Поле RDB$VALID_BLR.

Преобразование к типу столбца

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

CREATE TABLE ttt (
  s VARCHAR(40) CHARACTER SET utf8 COLLATE unicode_ci_ai
);
COMMIT;
SELECT CAST ('Jag har många vänner' AS TYPE OF COLUMN ttt.s)
FROM rdb$database;

Warning

Если определение столбца изменяется, то существующие преобразования к его типу могут стать ошибочными.Если такие преобразования происходят в PSQL модулях, то их ошибки могут быть обнаружены.См. Поле RDB$VALID_BLR.

См. также:

[fblangref-datatypes-convert-explicit].

Примеры приведения типов

SELECT CAST ('12' || '-June-' || '1959' AS DATE) FROM rdb$database

Заметьте, что в некоторых случаях вы можете не использовать синтаксис преобразования как в примере выше, так как Firebird поймёт из контекста (сравнение с полем типа DATE) как интерпретировать строку:

UPDATE People SET AgeCat = 'Old'
WHERE BirthDate < '1-Jan-1943'

Но это не всегда возможно.Преобразование в примере ниже не может быть опущено, так как система будет пытаться преобразовать строку к числу чтобы вычесть из неё число:

SELECT CAST('TODAY' AS DATE) - 7 FROM rdb$database

Функции побитовых операций

`BIN_AND()`

Доступно в

DSQL, PSQL

Синтаксис

BIN_AND (number, number [, number ...])

Table 1. Параметры функции `BIN_AND`
Параметр	Описание
number	Целое число.

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

SMALLINT, INTEGER, BIGINT или INT128

Функция BIN_AND возвращает результат побитовой операции AND (И) аргументов.

См. также:

[fblangref-scalarfuncs-bin-or], [fblangref-scalarfuncs-bin-xor].

`BIN_NOT()`

Доступно в

DSQL, PSQL

Синтаксис

BIN_NOT (number)

Table 1. Параметры функции `BIN_NOT`
Параметр	Описание
number	Целое число.

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

SMALLINT, INTEGER, BIGINT или INT128

Функция BIN_NOT возвращает результат побитовой операции NOT над аргументом.

См. также:

[fblangref-scalarfuncs-bin-or], [fblangref-scalarfuncs-bin-and].

`BIN_OR()`

Доступно в

DSQL, PSQL

Синтаксис

BIN_OR (number, number [, number ...])

Table 1. Параметры функции `BIN_OR`
Параметр	Описание
number	Целое число.

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

SMALLINT, INTEGER, BIGINT или INT128

Функция BIN_OR возвращает результат побитовой операции OR (ИЛИ) аргументов.

См. также:

[fblangref-scalarfuncs-bin-and], [fblangref-scalarfuncs-bin-xor].

`BIN_SHL()`

Доступно в

DSQL, PSQL

Синтаксис

BIN_SHL (number, shift)

Table 1. Параметры функции BIN_SHL
Параметр	Описание
number	Целое число.
shift	Количество бит, на которое смещается значение number.

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

BIGINT или INT128.

Функция BIN_SHL возвращает первый параметр, побитно смещённый влево на значение второго параметра, т.е. a << b или a·2^b.

См. также:

[fblangref-scalarfuncs-bin-shr].

`BIN_SHR()`

Доступно в

DSQL, PSQL

Синтаксис

BIN_SHR (number, shift)

Table 1. Параметры функции `BIN_SHR`
Параметр	Описание
number	Целое число.
shift	Количество бит на которое смещается значение number.

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

BIGINT или INT128.

Функция BIN_SHR возвращает первый параметр, побитно смещённый вправо на значение второго параметра, т.е. a >> b или a/2^b.

Выполняемая операция является арифметическим сдвигом вправо (SAR), а это означает, что знак первого операнда всегда сохраняется.

См. также:

[fblangref-scalarfuncs-bin-shl].

`BIN_XOR()`

Доступно в

DSQL, PSQL

Синтаксис

BIN_XOR (number, number [, number ...])

Table 1. Параметры функции `BIN_XOR`
Параметр	Описание
number	Целое число.

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

SMALLINT, INTEGER, BIGINT или INT128

Функция BIN_XOR возвращает результат побитовой операции XOR аргументов.

См. также:

[fblangref-scalarfuncs-bin-and], [fblangref-scalarfuncs-bin-or].

HEX_DECODE()

HEX_DECODE()

Примеры HEX_DECODE

HEX_ENCODE()

Примеры HEX_ENCODE

Функции для работы с датой и временем

DATEADD()

Примеры DATEADD

DATEDIFF()

Примеры DATEDIFF

EXTRACT()

FIRST_DAY()

Примеры FIRST_DAY

LAST_DAY()

Примеры LAST_DAY

Функции для работы с типом BLOB

BLOB_APPEND()

Функции для работы с типом DECFLOAT

COMPARE_DECFLOAT()

NORMALIZE_DECFLOAT()

Примеры NORMALIZE_DECFLOAT

QUANTIZE()

TOTALORDER()

Криптографические функции

CRYPT_HASH()

Примеры CRYPT_HASH

DECRYPT()

ENCRYPT()

RSA_PRIVATE()

RSA_PUBLIC()

RSA_ENCRYPT()

RSA_DECRYPT()

RSA_SIGN_HASH()

RSA_VERIFY_HASH()

Функции преобразования типов

CAST()

Преобразование к домену или к его базовому типу

Преобразование к типу столбца

Примеры приведения типов

Функции побитовых операций

BIN_AND()

BIN_NOT()

BIN_OR()

BIN_SHL()

BIN_SHR()

BIN_XOR()

`HEX_DECODE()`

Примеры `HEX_DECODE`

`HEX_ENCODE()`

Примеры `HEX_ENCODE`

`DATEADD()`

Примеры `DATEADD`

`DATEDIFF()`

Примеры `DATEDIFF`

`EXTRACT()`

`FIRST_DAY()`

Примеры `FIRST_DAY`

`LAST_DAY()`

Примеры `LAST_DAY`

`BLOB_APPEND()`

`COMPARE_DECFLOAT()`

`NORMALIZE_DECFLOAT()`

Примеры `NORMALIZE_DECFLOAT`

`QUANTIZE()`

`TOTALORDER()`

`CRYPT_HASH()`

Примеры `CRYPT_HASH`

`DECRYPT()`

`ENCRYPT()`

`RSA_PRIVATE()`

`RSA_PUBLIC()`

`RSA_ENCRYPT()`

`RSA_DECRYPT()`

`RSA_SIGN_HASH()`

`RSA_VERIFY_HASH()`

`CAST()`

`BIN_AND()`

`BIN_NOT()`

`BIN_OR()`

`BIN_SHL()`

`BIN_SHR()`

`BIN_XOR()`