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

Примеры OCTET_LENGTH

Example 1. Использование функции OCTET_LENGTH
SELECT OCTET_LENGTH('Hello!')
FROM rdb$database
-- возвратит 6

SELECT OCTET_LENGTH(_iso8859_1 'Grüß di!')
FROM rdb$database
-- возвратит 8: ü и ß занимают не более 1 байта в ISO8859_1

SELECT
  OCTET_LENGTH(CAST(_iso8859_1 'Grüß di!' AS VARCHAR(24) CHARACTER SET utf8))
FROM rdb$database
-- возвратит 10: ü и ß занимают 2 байта в UTF8

SELECT
  OCTET_LENGTH(CAST(_iso8859_1 'Grüß di!' AS CHAR(24) CHARACTER SET utf8))
FROM rdb$database
-- возвратит 26: всего 24 CHAR позиции, и две из них занимают 2 байта
См. также:

[fblangref-scalarfuncs-bit-length], [fblangref-scalarfuncs-char-length].

OVERLAY()

Доступно в

DSQL, PSQL

Синтаксис
OVERLAY (string PLACING replacement FROM pos [FOR length])
Table 1. Параметры функции OVERLAY
Параметр Описание

string

Строка, в которой происходит замена.

replacement

Строка, которой заменяется.

pos

Позиция, с которой происходит замена.

length

Количество символов, которые будут удалены из исходной строки.
Тип возвращаемого результата:

VARCHAR или BLOB

Функция OVERLAY предназначена для замены части строки другой строкой.

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

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

  • Функция полностью поддерживает тестовые BLOB с любым набором символов и любой длины;

  • Если входная строка имеет тип BLOB, то и результат будет иметь тип BLOB. В противном случае тип результата будет VARCHAR(n), где n является суммой длин параметров string и replacement;

  • Как и во всех строковых функциях SQL параметр pos является определяющим;

  • Если pos больше длины строки, то replacement помещается сразу после окончания строки;

  • Если число символов от pos до конца строки меньше, чем длина replacement (или, чем параметр length, если он задан), то строка усекается до значения pos и replacement помещается после него;

  • При нулевом параметре length (FOR 0) replacement просто вставляется в строку, начиная с позиции pos;

  • Если любой из параметров имеет значение NULL, то и результат будет NULL;

  • Если параметры pos и length не являются целым числом, то используется банковское округление (до чётного): 0.5 становится 0, 1.5 становится 2, 2.5 становится 2, 3.5 становится 4 и т.д.

Warning

При использовании BLOB функции может потребоваться загрузить весь объект в память.При больших размерах BLOB это может повлиять на производительность.

docnext count = 72

Примеры OVERLAY

Example 1. Использование функции OVERLAY
OVERLAY ('Goodbye' PLACING 'Hello' FROM 2) -- Результат: 'Ghelloe'
OVERLAY ('Goodbye' PLACING 'Hello' FROM 5) -- Результат: 'GoodHello'
OVERLAY ('Goodbye' PLACING 'Hello' FROM 8) -- Результат: 'GoodbyeHello'
OVERLAY ('Goodbye' PLACING 'Hello' FROM 20) -- Результат: 'GoodbyeHello'
OVERLAY ('Goodbye' PLACING 'Hello' FROM 2 FOR 0) -– Результат: 'GHellooodbye'
OVERLAY ('Goodbye' PLACING 'Hello' FROM 2 FOR 3) -- Результат: 'GHellobye'
OVERLAY ('Goodbye' PLACING 'Hello' FROM 2 FOR 6) -- Результат: 'GHello'
OVERLAY ('Goodbye' PLACING 'Hello' FROM 2 FOR 9) -- Результат: 'Ghello'
OVERLAY ('Goodbye' PLACING '' FROM 4) -- Результат: 'Goodbye'
OVERLAY ('Goodbye' PLACING '' FROM 4 FOR 3) -- Результат: 'Gooe'
OVERLAY ('Goodbye' PLACING '' FROM 4 FOR 20) -- Результат: 'Goo'
OVERLAY ('' PLACING 'Hello' FROM 4) -- Результат: 'Hello'
OVERLAY ('' PLACING 'Hello' FROM 4 FOR 0) -- Результат: 'Hello'
OVERLAY ('' PLACING 'Hello' FROM 4 FOR 20) -- Результат: 'Hello'
См. также:

[fblangref-scalarfuncs-substring], [fblangref-scalarfuncs-replace].

POSITION()

Доступно в

DSQL, PSQL

Синтаксис
  POSITION (substr IN string)
| POSITION (substr, string [, startpos])
Table 1. Параметры функции POSITION
Параметр Описание

substr

Подстрока, позиция которой ищется.

string

Строка, в которой ищется позиция.

startpos

Позиция, с которой начинается поиск подстроки.
Тип возвращаемого результата:

INTEGER

Функция POSITION возвращает позицию первого вхождения подстроки в строку.Отсчёт начинается с 1.Третий аргумент (опциональный) задаёт позицию в строке, с которой начинается поиск подстроки, тем самым игнорирую любые вхождения подстроки в строку до этой позиции.Если совпадение не найдено, функция возвращает 0.

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

  • Опциональный третий параметр поддерживается только вторым вариантом синтаксиса (синтаксис с запятой);

  • Пустую строку, функция считает подстрокой любой строки. Поэтому при входном параметре substr, равном '' (пустая строка), и при параметре string, отличном от NULL, результатом будет:

    • 1, если параметр startpos не задан;

    • startpos, если startpos не превышает длину параметра string;

    • 0, если startpos больше длины параметра string.

Примеры POSITION

Example 1. Использование функции POSITION
POSITION ('be' IN 'To be or not to be')   -- Результат: 4
POSITION ('be', 'To be or not to be')     -- Результат: 4
POSITION ('be', 'To be or not to be', 4)  -- Результат: 4
POSITION ('be', 'To be or not to be', 8)  -- Результат: 17
POSITION ('be', 'To be or not to be', 18) -- Результат: 0
POSITION ('be' in 'Alas, poor Yorick!') -- Результат: 0
См. также:

[fblangref-scalarfuncs-substring].

REPLACE()

Доступно в

DSQL, PSQL

Синтаксис
REPLACE (str, find, repl)
Table 1. Параметры функции REPLACE
Параметр Описание

str

Строка, в которой делается замена.

find

Строка, которая ищется.

repl

Строка, на которую происходит замена.
Тип возвращаемого результата:

VARCHAR или BLOB

Функция REPLACE заменяет в строке все вхождения одной строки на другую строку.

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

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

  • Если один из аргументов имеет тип BLOB, то результат будет иметь тип BLOB. В противном случае результат будет иметь тип VARCHAR(N), где N рассчитывается из длин str, find и repl таким образом, что даже максимальное количество замен не будет вызывать переполнения поля.

  • Если параметр find является пустой строкой, то возвращается str без изменений;

  • Если параметр repl является пустой строкой, то все вхождения find удаляются из строки str;

  • Если любой из аргументов равен NULL, то результатом всегда будет NULL, даже если не было произведено ни одной замены.

Warning

При использовании BLOB в параметрах функции может потребоваться загрузить объект полностью в память.При больших объёмах BLOB могут наблюдаться потери производительности.

Примеры REPLACE

Example 1. Использование функции REPLACE
REPLACE ('Billy Wilder', 'il', 'oog')  -- возвращает 'Boogly Woogder'
REPLACE ('Billy Wilder', 'il', '')     -- возвращает 'Bly Wder'
REPLACE ('Billy Wilder', null, 'oog')  -- возвращает NULL
REPLACE ('Billy Wilder', 'il', null)   -- возвращает NULL
REPLACE ('Billy Wilder', 'xyz', null)  -- возвращает NULL (!)
REPLACE ('Billy Wilder', 'xyz', 'abc') -- возвращает 'Billy Wilder'
REPLACE ('Billy Wilder', '', 'abc')    -- возвращает 'Billy Wilder'
См. также:

[fblangref-scalarfuncs-overlay].

REVERSE()

Доступно в

DSQL, PSQL

Синтаксис
REVERSE (string)
Table 1. Параметры функции REVERSE
Параметр Описание

string

Выражение строкового типа.
Тип возвращаемого результата:

VARCHAR

Функция REVERSE возвратит строку перевёрнутую "задом наперёд".

Примеры REVERSE

Example 1. Использование функции REVERSE
REVERSE ('spoonful')             -- возвращает 'lufnoops'
REVERSE ('Was it a cat I saw?')  -- возвращает '?was I tac a ti saW'
Tip

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

CREATE INDEX ix_people_email ON people
COMPUTED BY (reverse(email));

SELECT * FROM people
WHERE REVERSE(email) STARTING WITH reverse('.br');

RIGHT()

Доступно в

DSQL, PSQL

Синтаксис
RIGHT (string, length)
Table 1. Параметры функции RIGHT
Параметр Описание

string

Выражение строкового типа.

length

Целое число.Определяет количество возвращаемых символов.
Тип возвращаемого результата:

VARCHAR или BLOB

Функция RIGHT возвращает конечную (правую) часть входной строки.Длина возвращаемой подстроки определяется вторым параметром.

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

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

  • Если строковый аргумент BLOB, результатом будет BLOB, в противном случае результатом будет VARCHAR(N), при этом N — будет равно длине строкового параметра;

  • Если числовой параметр превысит длину текста, результатом будет исходный текст.

Warning

При использовании BLOB в параметрах функции может потребоваться загрузить объект полностью в память.При больших объёмах BLOB могут наблюдаться потери производительности.
Example 1. Использование функции RIGHT
SELECT RIGHT('ABC', 1) FROM rdb$database;
-- результат C
См. также:

[fblangref-scalarfuncs-left], [fblangref-scalarfuncs-substring].

RPAD()

Доступно в

DSQL, PSQL

Синтаксис
RPAD (str, endlen [, padstr])
Table 1. Параметры функции RPAD
Параметр Описание

str

Выражение строкового типа.

endlen

Длина выходной строки.

padstr

Строка, которой дополняется исходная строка до указанной длины.По умолчанию является пробелом (' ').
Тип возвращаемого результата:

VARCHAR или BLOB

Функция RPAD дополняет справа входную строку пробелами или определённой пользователем строкой до заданной длины.

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

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

  • Если входная строка имеет тип BLOB, то результат также будет BLOB, в противном случае результат будет VARCHAR(endlen).

  • Если аргумент padstr задан, но равен '' (пустой строке), то дополнения строки не происходит! В случае если endlen меньше длины входной строки, то в результате происходит её усечение до длины endlen, даже если параметр padstr равен пустой строке.

Warning

При использовании BLOB в параметрах функции может потребоваться загрузить объект полностью в память.При больших объёмах BLOB могут наблюдаться потери производительности.

Примеры RPAD

Example 1. Использование функции RPAD
RPAD ('Hello', 12)                -- возвращает 'Hello       '
RPAD ('Hello', 12, '-')           -- возвращает 'Hello-------'
RPAD ('Hello', 12, '')            -- возвращает 'Hello'
RPAD ('Hello', 12, 'abc')         -- возвращает 'Helloabcabca'
RPAD ('Hello', 12, 'abcdefghij')  -- возвращает 'Helloabcdefg'
RPAD ('Hello', 2)                 -- возвращает 'He'
RPAD ('Hello', 2, '-')            -- возвращает 'He'
RPAD ('Hello', 2, '')             -- возвращает 'He'
См. также:

[fblangref-scalarfuncs-lpad].

ASCII_VAL()

Доступно в

DSQL, PSQL

Синтаксис
ASCII_VAL (ch)
Table 1. Параметры функции ASCII_VAL
Параметр Описание

ch

Строка типа данных [VAR]CHAR или текстовый BLOB максимального размера 32767 байт.
Тип возвращаемого результата:

SMALLINT

Функция ASCII_VAL возвращает ASCII код символа, переданного в качестве аргумента.

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

  • Если строка содержит более одного символа, то возвращается код первого символа строки;

  • Если строка пустая, возвращается ноль;

  • Если аргумент NULL, то возвращаемое значение также NULL.

См. также:

[fblangref-scalarfuncs-ascii-char].

SUBSTRING()

Доступно в

DSQL, PSQL

Синтаксис
SUBSTRING (<substring-args>)

<substring-args> ::=
    str FROM startpos [FOR length]
  | str SIMILAR <similar_pattern> ESCAPE <escape>

<similar-pattern> ::=
  <similar-pattern-R1>
  <escape>"<similar pattern_R2><escape>"
  <similar pattern-R3>
Table 1. Параметры функции SUBSTRING
Параметр Описание

str

Выражение строкового типа.

startpos

Позиция, с которой начинается извлечение подстроки.Целочисленное выражение.

length

Длина возвращаемой подстроки.Целочисленное выражение.

similar-pattern

Шаблон регулярного выражения SQL, по которому ищется подстрока.

escape

Символ экранирования.
Тип возвращаемого результата:

VARCHAR или BLOB

Функция SUBSTRING возвращает подстроку из строки, начиная с заданной позиции до конца строки или до указанной длины, либо извлекает подстроку с использованием шаблона регулярного выражения SQL.

Если любой из входных параметров имеет значение NULL, то и результат тоже будет иметь значение NULL.

Warning

При использовании BLOB в параметрах функции может потребоваться загрузить объект в память полностью.При больших объёмах BLOB могут наблюдаться потери производительности.

Позиционный SUBSTRING

В простой позиционной форме (с FROM) эта функция возвращает подстроку, начинающуюся с позиции символа startpos (позиция первого сивола равна 1). Без аргумента FOR он возвращает все оставшиеся символы в строке.С использованием FOR возвращается length символов или остаток строки, в зависимости от того что короче.

Начиная с Firebird 4.0, startpos может быть меньше 1.Когда startpos меньше 1, подстрока ведет себя так, как если бы строка имела дополнительные позиции 1 - startpos передфактическим первым символом в позиции 1.Значение length считается от этого воображаемого начала строки, поэтому результирующая строка может быть короче указанной length или даже пустой.

Функция полностью поддерживает двоичные и текстовые BLOB любой длины и с любым набором символов.Если параметр str имеет тип BLOB, то и результат будет иметь тип BLOB.Для любых других типов результатом будет тип VARCHAR.

Для входного параметра str, не являющегося BLOB, длина результата функции всегда будет равна длине строки str, независимо от значений параметров startpos и length.

Example 1. Использование функции SUBSTRING
select substring('abcdef' from 1 for 2) from rdb$database;
-- результат: 'ab'

select substring('abcdef' from 2) from rdb$database;
-- результат: 'bcdef'

select substring('abcdef' from 0 for 2) from rdb$database;
-- результат: 'a'
-- не 'ab', потому что в позиции 0 нет "ничего"

select substring('abcdef' from -5 for 2) from rdb$database;
-- результат: ''
-- длина заканчивается до фактического начала строки

SUBSTRING по регулярному выражению

Функция SUBSTRING с регулярным выражением (с SIMILAR) возвращает часть строки соответствующей шаблону регулярного выражения SQL.Если соответствия не найдено, то возвращается NULL.

Шаблон SIMILAR формируется из трех шаблонов регулярных выражений SQL: R1, R2 и R3.Полностью шаблон имеет форму R1 || '<escape>"' || R2 || '<escape>"' || R3, где <escape> — это escape-символ, определенный в предложении ESCAPE.R2 — это шаблон, который соответствует подстроке для извлечения и заключен в экранированные двойные кавычки (<escape>", например, “#"” с escape-символом ‘#’). R1 соответствует префиксу строки, а R3 — суффиксу строки.И R1, и R3 необязательны (они могут быть пустыми), но шаблон должен соответствовать всей строке.Другими словами, недостаточно указать шаблон, который находит только подстроку для извлечения.

Tip

Экранированные двойные кавычки вокруг R2 можно сравнить с определением одной группы захвата в более распространенном синтаксисе регулярных выражений, таком как PCRE.То есть полный шаблон эквивалентен R1(R2)R3, который должен соответствовать всей входной строке, а группа захвата — это возвращаемая подстрока.

Возвращаемое значение соответствует части R2 регулярного выражения.Для этого значения истинно выражение

str SIMILAR TO R1 || R2 || R3 ESCAPE <escape>
Note

Если любая часть шаблона из R1, R2 или R3 не является пустой строкой и не имеет формата регулярного выражения SQL, возникает исключение.

Полный формат регулярных выражений SQL описан в Синтаксис регулярных выражений SQL.

Example 2. Использование функции SUBSTRING с регулярными выражениями
SUBSTRING('abcabc' SIMILAR 'a#"bcab#"c' ESCAPE '#')  -- bcab
SUBSTRING('abcabc' SIMILAR 'a#"%#"c' ESCAPE '#')     -- bcab
SUBSTRING('abcabc' SIMILAR '_#"%#"_' ESCAPE '#')     -- bcab
SUBSTRING('abcabc' SIMILAR '#"(abc)*#"' ESCAPE '#')  -- abcabc
SUBSTRING('abcabc' SIMILAR '#"abc#"' ESCAPE '#')     -- <null>
См. также:

[fblangref-scalarfuncs-position], [fblangref-scalarfuncs-left], [fblangref-scalarfuncs-right],[fblangref-scalarfuncs-char-length], [fblangref-commons-predsimilarto].

TRIM()

Доступно в

DSQL, PSQL

Синтаксис
TRIM ([<adjust>] str)

<adjust> ::=  {[<where>] [what]} FROM

<where> ::=  BOTH | LEADING | TRAILING
Table 1. Параметры функции TRIM
Параметр Описание

str

Выражение строкового типа.

where

Из какого места необходимо удалить подстроку — BOTH | LEADING | TRAILING.По умолчанию BOTH.

what

Подстрока, которую надо удалить (неоднократно, если таких вхождений несколько) из входной строки str в её начале и/или конце.По умолчанию является пробелом (' ').
Тип возвращаемого результата:

VARCHAR или BLOB

Функция TRIM удаляет начальные и /или концевые пробелы (или текст согласно настройкам) из входной строки.

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

  • Если входной параметр str имеет тип BLOB, то и результат будет иметь тип BLOB. В противном случае результат будет иметь тип VARCHAR(n), где n является длиной параметра str;

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

При использовании BLOB в параметрах функции может потребоваться загрузить объект в память полностью.При больших объёмах BLOB могут наблюдаться потери производительности.

Примеры TRIM

Example 1. Использование функции TRIM
SELECT TRIM (' Waste no space ')
FROM RDB$DATABASE -- Результат: 'Waste no space'

SELECT TRIM (LEADING FROM ' Waste no space ')
FROM RDB$DATABASE -- Результат: 'Waste no space '

SELECT TRIM (LEADING '.' FROM ' Waste no space ')
FROM RDB$DATABASE -- Результат: ' Waste no space '

SELECT TRIM (TRAILING '!' FROM 'Help!!!!')
FROM RDB$DATABASE -- Результат: 'Help'

SELECT TRIM ('la' FROM 'lalala I love you Ella')
FROM RDB$DATABASE -- Результат: ' I love you El'
См. также:

[fblangref-scalarfuncs-overlay], [fblangref-scalarfuncs-replace].

UNICODE_CHAR()

Доступно в

DSQL, PSQL

Синтаксис
UNICODE_CHAR (number)
Table 1. Параметры функции UNICODE_CHAR
Параметр Описание

number

Допустимая кодовая точка UTF-32 вне диапазона суррогатов верхней/нижней границы (от 0xD800 до 0xDFFF). В противном случае будет выдана ошибка.
Тип возвращаемого результата:

CHAR CHARACTER SET UTF8

Функция UNICODE_CHAR возвращает UNICODE символ для заданной кодовой точки.

Примеры UNICODE_CHAR

Example 1. Использование функции UNICODE_CHAR
select unicode_char(x) from y;
См. также:

[fblangref-scalarfuncs-unicodeval].

UNICODE_VAL()

Доступно в

DSQL, PSQL

Синтаксис
UNICODE_VAL (string)
Table 1. Параметры функции UNICODE_VAL
Параметр Описание

string

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

INTEGER

Функция UNICODE_VAL возвращает UTF-32 кодовую точку для первого символа в строке. Возвращает 0 для пустой строки.

Примеры UNICODE_VAL

Example 1. Использование функции UNICODE_VAL
select unicode_val(x) from y;
См. также:

[fblangref-scalarfuncs-unicodechar].

UPPER()

Доступно в

DSQL, PSQL

Синтаксис
UPPER (str)
Table 1. Параметры функции UPPER
Параметр Описание

str

Выражение строкового типа.
Тип возвращаемого результата:

[VAR]CHAR или BLOB

Функция UPPER возвращает входную строку в верхнем регистре.Точный результат зависит от набора символов входной строки.Например, для наборов символов NONE и ASCII только ASCII символы переводятся в верхний регистр; для OCTETS — вся входная строка возвращается без изменений.

Примеры UPPER

Example 1. Использование функции UPPER
select upper(_iso8859_1 'Débâcle')
from rdb$database
-- returns 'DÉBÂCLE'

select upper(_iso8859_1 'Débâcle' collate fr_fr)
from rdb$database
-- returns 'DEBACLE', following French uppercasing rules
См. также:

[fblangref-scalarfuncs-lower].

BASE64_DECODE()

Доступно в

DSQL, PSQL

Синтаксис
BASE64_DECODE (base64_data)
Table 1. Параметры функции BASE64_DECODE
Параметр Описание

base64_data

Данные в кодировке Base64, дополненные знаком = до длины кратной 4
Тип возвращаемого результата

BLOB или VARBINARY

BASE64_DECODE декодирует строку с данными закодированными алгоритмом base64и возвращает декодированное значение как VARBINARY или BLOB в зависимости от входного аргумента.

Если длина типа base64_data не кратна 4, то во время подготовки возникает ошибка.Если длина значения base64_data не кратна 4, то во время выполнения возникает ошибка.

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

Примеры BASE64_DECODE

Example 1. Использование BASE64_DECODE
select cast(base64_decode('VGVzdCBiYXNlNjQ=') as varchar(12))
from rdb$database;
CAST

============
Test base64
См. также:

[fblangref-scalarfuncs-base64encode].

BASE64_ENCODE()

Доступно в

DSQL, PSQL

Синтаксис
BASE64_ENCODE (binary_data)
Table 1. Параметры функции BASE64_ENCODE
Параметр Описание

binary_data

Двоичные данные для кодирования
Тип возвращаемого результата

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

Функция BASE64_ENCODE кодирует binary_data с помощью алгоритма base64 ивозвращает закодированное значение как VARCHAR CHARACTER SET ASCII или BLOB SUB_TYPE TEXT CHARACTER SET ASCIIв зависимости от типа входного аргумента.Возвращаемое значение дополняется знаком ‘=’, чтобы его длина была кратна 4.

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

Примеры BASE64_ENCODE

Example 1. Использование функции BASE64_ENCODE
select base64_encode('Test base64')
from rdb$database;
BASE64_ENCODE
================
VGVzdCBiYXNlNjQ=
См. также:

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

BIT_LENGTH()

Доступно в

DSQL, PSQL

Синтаксис
BIT_LENGTH (string)
Table 1. Параметры функции BIT_LENGTH
Параметр Описание

string

Выражение строкового типа.
Тип возвращаемого результата:

BIGINT

Функция BIT_LENGTH возвращает длину входной строки в битах.Для многобайтных наборов символов результат может быть в 8 раз больше, чем количество символов в “формальном” числе байт на символ, записанном в RDB$CHARACTER_SETS.

С параметрами типа CHAR эта функция берет во внимание всю формальную строковую длину (например, объявленная длина поля или переменной). Если вы хотите получить “логическую” длину в битах, не считая пробелов, то перед передачей аргумента в BIT_LENGTH надо выполнить над ним операцию RIGHT TRIM.

Примеры BIT_LENGTH

Example 1. Использование функции BIT_LENGTH
SELECT BIT_LENGTH ('Hello!') FROM RDB$DATABASE
-- возвращает 48

SELECT BIT_LENGTH (_ISO8859_1 'Grüß Di!')
FROM RDB$DATABASE
-- возвращает 64: каждый, и ü, и ß занимают один байт в ISO8859_1

SELECT BIT_LENGTH (
CAST (_ISO8859_1 'Grüß di!' AS VARCHAR (24)
CHARACTER SET UTF8))
FROM RDB$DATABASE
-- возвращает 80: каждый, и ü, и ß занимают по два байта в UTF8

SELECT BIT_LENGTH (
CAST (_ISO8859_1 'Grüß di!' AS CHAR (24)
CHARACTER SET UTF8))
FROM RDB$DATABASE
-- возвращает 208: размер всех 24 позиций CHAR и два из них 16-битные
См. также:

[fblangref-scalarfuncs-char-length], [fblangref-scalarfuncs-octet-length].

CHAR_LENGTH(), CHARACTER_LENGTH()

Доступно в

DSQL, PSQL

Синтаксис
  CHAR_LENGTH (string)
| CHARACTER_LENGTH (string)
Table 1. Параметры функции CHAR_LENGTH
Параметр Описание

string

Выражение строкового типа.
Тип возвращаемого результата:

BIGINT

Функция CHAR_LENGTH возвращает длину (в символах) строки, переданной в качестве аргумента.

Note

С параметрами типа CHAR эта функция берет во внимание всю формальную строковую длину (например, объявленная длина поля или переменной). Если вы хотите получить “логическую” длину без учёта пробелов, то перед передачей аргумента в CHAR[ACTER]_LENGTH надо выполнить над ним операцию RIGHT TRIM.
См. также:

[fblangref-scalarfuncs-bit-length], [fblangref-scalarfuncs-octet-length].

HASH()

Доступно в

DSQL, PSQL

Синтаксис
HASH (str [USING <algorithm>])

<algorithm> ::= { CRC32 }
Table 1. Параметры функции HASH
Параметр Описание

str

Выражение строкового типа.
Тип возвращаемого результата:

BIGINT

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

Необязательное предложение USING определяет применяемый некриптографический алгоритм хеширования.Когда предложение USING отсутствует, применяется устаревший алгоритм PJW; это идентично его поведению в предыдущихверсиях Firebird.

Поддерживаемые алгоритмы:
не указан

Если алгоритм не указан, то используется 64-битный вариант некриптографическойхэш-функции PJW (также известной как ELF64).Эта функция очень быстра и может использоваться для общих целей (хеш-таблицы и т.д.), но имеет большое количество коллизий.Для более надежного хеширования следует использовать другие хеш-функции, явно указанные в предложении USING, или криптографические хеши с помощью [fblangref-scalarfuncs-crypthash].

Для этого алгоритма хеширования функция возвращает тип BIGINT.

CRC32

Если в предложении USING указан алгоритм CRC32, то Firebird применяет алгоритм CRC32, используя полином 0x04C11DB7.

Для этого алгоритма функция HASH возвращает результат с типом INTEGER.

Примеры HASH

Example 1. Вычисление хеша с алгоритмом PJW
SELECT HASH(x) FROM MyTable;
-- результат типа BIGINT
Example 2. Вычисление хеша с алгоритмом CRC32
SELECT HASH(x USING CRC32) FROM MyTable;
-- результат типа INTEGER

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

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·2b.

См. также:

[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/2b.

  • Выполняемая операция является арифметическим сдвигом вправо (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].