1. Обзор

Основные функции, показанные ниже, доступны по умолчанию. Функции даты и времени, агрегатные функции, функции окна, математические функции и функции JSON документированы отдельно. Применение может определить дополнительные функции, написанные на C, и добавить к ядру базы данных, используя sqlite3_create_function() API.

simple-function-invocation:

Посмотрите здесь для получения дополнительной информации о том, как вызовы функции SQL вписываются в контекст SQL-выражения.

2. Список основных функций

3. Описания встроенных скалярных функций SQL

abs(X)

abs(X) возвращает абсолютное значение числового аргумента X. Abs(X) вернет NULL, если X = NULL. Abs(X) вернет 0.0, если X это последовательность или blob, которая не может быть преобразована в числовое значение. Если X целое число -9223372036854775808, abs(X) бросит ошибку integer overflow, так как нет никаких эквивалентных положительных 64-битовых значений.

changes()

changes() возвращает количество строк базы данных, которые были изменены, вставлены или удалены последний раз законченным INSERT, DELETE или UPDATE, кроме запросов в триггерах низшего уровня. Функция SQL changes() это обертка вокруг функции C/C++ sqlite3_changes64() и следовательно следует тем же самым правилам для подсчета изменений.

char(X1,X2,...,XN)

char(X1,X2,...,XN) возвращает последовательность, состоявшую из знаков, имеющих unicode-значения кодовой точки целых чисел от X1 до XN, соответственно.

coalesce(X,Y,...)

coalesce() возвращает копию своего первого ненулевого аргумента или NULL, если все аргументы NULL. Coalesce() должна иметь по крайней мере 2 аргумента.

concat(X,...)

concat(...) возвращает последовательность, которая является связью строкового представления всех ненулевых аргументов. Если все аргументы NULL, то concat() возвращает пустую строку.

concat_ws(SEP,X,...)

concat_ws(SEP,...) возвращает последовательность, которая является связью всех ненулевых аргументов вне первого аргумента, используя текстовое значение первого аргумента как сепаратор. Если первый аргумент NULL, concat_ws() вернет NULL. Если все аргументы кроме первого NULL, то concat_ws() возвращает пустую строку.

format(FORMAT,...)

format(FORMAT,...) работает подобно С-функции sqlite3_mprintf() и функции printf() из стандартной библиотеки C. Первый аргумент это строка формата, которая определяет, как построить выводимую строку, используя значения, взятые от последующих аргументов. Если аргумент FORMAT отсутствует или NULL, результат NULL. Формат %n тихо проигнорирован и не потребляет аргумент. Формат %p это псевдоним для %X. Формат %z взаимозаменяемый с %s. Если есть слишком мало аргументов в списке аргументов, у недостающих аргументов, как предполагается, есть значение NULL, которое переведено в 0 или 0.0 для числовых форматов или в пустую строку для %s. Посмотрите встроенный printf() для подробностей.

glob(X,Y)

glob(X,Y) эквивалент выражения "Y GLOB X". Обратите внимание на то, что аргументы X и Y полностью изменены в функции glob() относительно оператора GLOB. Y это строка, а X это шаблон. Так, например, следующие выражения эквивалентны:

name GLOB '*helium*'
glob('*helium*',name)

Если sqlite3_create_function() использоваться, чтобы отвергнуть glob(X,Y) с альтернативным внедрением, то оператор GLOB вызовет альтернативное внедрение.

hex(X)

hex() интерпретирует свой аргумент как BLOB и возвращает последовательность, которая является заглавным шестнадцатеричным представлением содержания BLOB.

Если X в "hex(X)" integer или число с плавающей точкой, то "интерпретирует его аргумент как BLOB" значит, что двоичное число сначала преобразовывается в текстовое представление UTF8, затем тот текст интерпретируется как BLOB. Следовательно, "hex(12345678)" воспринимается как "3132333435363738", не двоичное представление целочисленного значения "0000000000BC614E". См. также: unhex().

ifnull(X,Y)

ifnull() возвращает копию своего первого ненулевого аргумента или NULL, если оба аргумента NULL. У Ifnull() должно быть точно 2 аргумента. ifnull() эквивалентна coalesce() с двумя аргументами.

iif(X,Y,Z)

iif(X,Y,Z) вернет Y, если X = true, иначе Z. iif(X,Y,Z) логически эквивалентна и производит тот же самый байт-код, как CASE expression "CASE WHEN X THEN Y ELSE Z END".

instr(X,Y)

instr(X,Y) находит первое возникновение последовательности Y в последовательности X и возвращает количество предшествующих знаков плюс 1 или 0, если Y нигде не найден в X. Или, если X и Y оба BLOB, instr(X,Y) возвращает число байт+1 до первого возникновения Y или 0, если Y не происходит нигде в X. Если оба аргумента X и Y instr(X,Y) не-NULL и не являются BLOB, оба интерпретируются как последовательности. Если X или Y = NULL, instr(X,Y) вернет NULL.

last_insert_rowid()

last_insert_rowid() вернет ROWID последней вставки строки от соединения с базой данных, которое вызвало функцию. SQL-функция last_insert_rowid() является оберткой вокруг функции C/C++ sqlite3_last_insert_rowid().

length(X)

Для строкового значения X length(X) возвращает количество знаков (не байт) в X до первого символа NUL. Так как последовательности SQLite обычно не содержат знаки NUL, length(X) будет обычно возвращать общее количество знаков в последовательности X. Для значения blob X length(X) вернет число байтов в blob. Если X = NULL, length(X) = NULL. Если X числовое, тогда length(X) вернет длину строкового представления X.

Обратите внимание на то, что для последовательностей length(X) возвращает длину в знаках последовательности, а не длину в байтах. Это количество знаков в последовательности. Длина в знаках всегда отличается от длины в байтах для последовательностей UTF-16 и может отличаться от длины в байтах для последовательностей UTF-8, если последовательность содержит многобайтовые символы. Используйте octet_length(), чтобы найти длину последовательности в байтах.

Для BLOB length(X) всегда вернет длину BLOB в байтах.

Для строковых значений length(X) должна прочитать всю последовательность в память, чтобы вычислить длину в знаках. Но для значений BLOB это не нужно, поскольку SQLite знает, сколько байтов находится в BLOB. Следовательно, для мультимегабайтных значений length(X) обычно намного быстрее для BLOB, чем для последовательностей, так как это не должно загружать значение в память.

like(X,Y)
like(X,Y, Z)

like() используется, чтобы осуществить выражение "Y LIKE X [ESCAPE Z]". Если дополнительный пункт ESCAPE присутствует, то like() вызвана с тремя аргументами. Иначе это вызвано только с двумя аргументами. Обратите внимание на то, что X и параметры Y полностью изменены в like() относительно оператора LIKE. X это шаблон, а Y является строкой, чтобы соответствовать шаблону. Следовательно, следующие выражения эквивалентны:

name LIKE '%neon%'
like('%neon%',name)

sqlite3_create_function() может использоваться, чтобы отвергнуть like() и таким образом изменить операцию оператора LIKE. Отвергая функцию like(), может быть важно отвергнуть двух и трехаргументные версии like(). Иначе различный код можно вызвать, чтобы осуществить оператор LIKE в зависимости от того, был ли пункт ESCAPE определен.

likelihood(X,Y)

likelihood(X,Y) вернет X без изменений. Y в likelihood(X,Y) константой с плавающей точкой между 0.0 и 1.0, включительно. likelihood(X) ничего не делает, когда генератор кода оптимизирует так, чтобы это не потребляло циклов CPU во время времени выполнения (то есть, во время sqlite3_step()). Цель likelihood(X,Y) это предоставить намек планировщику запроса, что аргументом X является булево значение, которое верно с вероятностью приблизительно Y. unlikely(X) это сокращение для likelihood(X,0.0625). likely(X) это сокращение для likelihood(X,0.9375).

likely(X)

likely(X) вернет X без изменений. likely(X) ничего не делает, когда генератор кода оптимизирует так, чтобы это не потребляло циклов CPU во время времени выполнения (то есть, во время sqlite3_step()). Цель likely(X) это предоставить намек планировщику запроса, что аргументом X является булево значение, которое обычно верно. likely(X) эквивалентна likelihood(X,0.9375). См. также: unlikely(X).

load_extension(X)
load_extension(X,Y)

load_extension(X,Y) загружает расширение из совместно использованного файла библиотеки, названного X, через точку входа Y. Результат load_extension() всегда NULL. Если Y опущен, имя точки входа по умолчанию используется. load_extension() поднимает исключение, если расширение не загружается или инициализируется правильно.

load_extension() потерпит неудачу, если расширение попытается изменить или удалить функцию SQL или последовательность сопоставления. Расширение может добавить новые функции или последовательности сопоставления, но не может изменить или удалить существующие функции или последовательности сопоставления, потому что те функции и/или последовательности сопоставления могли бы использоваться в другом месте в работающем в настоящее время SQL-операторе. Чтобы загрузить расширение, которое изменяет или удаляет функции или последовательности сопоставления, используйте sqlite3_load_extension() C API.

Из соображений безопасности загрузка расширений отключена по умолчанию и должна быть позволена предшествующим sqlite3_enable_load_extension() .

lower(X)

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

ltrim(X)
ltrim(X,Y)

ltrim(X,Y) возвращает последовательность, сформированную, удаляя все знаки, которые появляются в Y с левой стороны X. Если аргумент Y опущен, ltrim(X) удаляет пробелы с левой стороны X.

max(X,Y,...)

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

min(X,Y,...)

Мультиаргументная min() возвращает аргумент с минимальным значением. Мультиаргументная min() ищет свои аргументы слева направо для аргумента, который определяет функцию сопоставления для всех сравнений строк. Если ни один из аргументов max() не определяет функцию сопоставления, то функция сопоставления BINARY используется. Обратите внимание на то, что min() простая функция, когда она имеет 2 или больше аргумента, но работает как агрегатная, если дан только один аргумент.

nullif(X,Y)

nullif(X,Y) возвращает свой первый аргумент, если аргументы отличаются и NULL, если аргументы одинаковы. nullif(X,Y) проверяет свои слева направо в поисках аргумента, который определяет функцию сопоставления и использует ее для всех сравнений строк. Если никакой аргумент nullif() не определяет функцию сопоставления, функция сопоставления BINARY используется.

octet_length(X)

octet_length(X) возвращает число байтов в кодировании текстовой строки X. Если X = NULL, тогда octet_length(X) вернет NULL. Если X это BLOB, octet_length(X) работает как length(X) . Если X это числовое значение, то octet_length(X) вернет число байтов в текстовом предоставлении того числа.

Так как octet_length(X) вернет число байтов в X, а не количество знаков, возвращенное значение зависит от кодирования базы данных. octet_length() может дать различные ответы для той же самой входной строки, если кодирование базы данных UTF16 вместо UTF8.

Если аргументом X является столбец таблицы, и значение имеет текстовый тип или blob, octet_length(X) избегает читать содержание X с диска, поскольку длина в байтах может быть вычислена из метаданных. Таким образом, octet_length(X) эффективно, даже если X колонка содержит многомегабайтный текст или blob.

printf(FORMAT,...)

printf() это псевдоним для SQL-функции format(). SQL-функция format() первоначально названа printf(). Но название было позже изменено на format() для совместимости с другими ядрами базы данных. Имя printf() сохраняется как псевдоним, чтобы не нарушить устаревший код.

quote(X)

quote(X) возвращает текст литерала SQL, который является ее аргументом, подходящий для включения в SQL-оператор. Последовательности окружены одинарными кавычками с экранированием внутренних кавычек по мере необходимости. BLOB закодированы как шестнадцатеричные литералы. Последовательности с вложенными знаками NUL не могут быть представлены как строковые литералы в SQL, и следовательно буквальная возвращаемая строка усечена до первого NUL.

random()

random() вернет случайный integer от -9223372036854775808 до +9223372036854775807.

randomblob(N)

randomblob(N) возвращает N-байтный blob, содержащий псевдослучайные байты. Если N меньше 1, тогда возвращен 1-байтовый случайный blob.

Приложения могут произвести глобально уникальные идентификаторы, используя эту функцию вместе с hex() и/или lower():

hex(randomblob(16))

lower(hex(randomblob(16)))

replace(X,Y,Z)

replace(X,Y,Z) возвращает последовательность, сформированную, заменяя последовательностью Z каждое возникновение последовательности Y в последовательности X. Последовательность сопоставления BINARY используется для сравнений. Если Y пустая строка, тогда X возвращается неизменной. Если Z первоначально не последовательность, она брошена к последовательности UTF-8 до обработки.

round(X)
round(X,Y)

round(X,Y) возвращает значение с плавающей запятой X, округленную к Y цифрам направо от десятичной точки. Если аргумент Y опущен или отрицателен, он считается 0.

rtrim(X)
rtrim(X,Y)

rtrim(X,Y) возвращает последовательность, сформированную, удаляя все знаки, которые появляются справа от Y в X. Если аргумент Y опущен, rtrim(X) удаляет пробелы из правой стороны X.

sign(X)

sign(X) вернет -1, 0 или +1, если X это числовое значение, которое является отрицательным, нолем или положительным, соответственно. Если аргумент sign(X) = NULL или является последовательностью или blob, который не может быть без потерь преобразован в число, то sign(X) вернет NULL.

soundex(X)

soundex(X) возвращает последовательность, которая является кодированием soundex последовательности X. Последовательность "?000" возвращена, если аргумент NULL или не содержит буквенных символов ASCII. Эта функция опущена в SQLite по умолчанию. Это доступно только, если выбор времени компиляции SQLITE_SOUNDEX используется, когда SQLite собирается.

sqlite_compileoption_get(N)

SQL-функция sqlite_compileoption_get() это обертка вокруг функции C/C++ sqlite3_compileoption_get(). Возвращает N-ю опцию компиляции SQLite или NULL, если N вне диапазона. См. также compile_options pragma.

sqlite_compileoption_used(X)

SQL-функция sqlite_compileoption_used() это обертка вокруг функции C/C++ sqlite3_compileoption_used(). Когда аргументом X в sqlite_compileoption_used(X) является последовательность, которая является названием выбора времени компиляции, это возвращает true (1) или false (0) в зависимости от того, использовался ли тот выбор во время сборки.

sqlite_offset(X)

sqlite_offset(X) возвращает байтовое смещение в файле базы данных для начала записи, из которой было бы прочитано значение. Если X не колонка в обычной таблице, sqlite_offset(X) вернет NULL. Значение sqlite_offset(X) могло бы сослаться на оригинальную таблицу или на индекс, в зависимости от запроса. Если X обычно извлекалась бы из индекса, sqlite_offset(X) вернет смещение соответствующей записи индекса. Если X извлечен из оригинальной таблицы, sqlite_offset(X) вернет смещение записи таблицы.

SQL-функция sqlite_offset(X) доступна только, если SQLite строится, используя опцию сборки -DSQLITE_ENABLE_OFFSET_SQL_FUNC.

sqlite_source_id()

sqlite_source_id() вернет строку, которая определяет версию исходного кода, который использовался, чтобы построить библиотеку SQLite. Последовательность, возвращенная sqlite_source_id(), является датой и временем, которые сохранены в исходном коде, сопровождаемые хэшем SHA3-256 для той регистрации. Эта функция обертка SQL вокруг sqlite3_sourceid().

sqlite_version()

sqlite_version() возвращает строку версии для библиотеки SQLite, которая работает. Эта функция обертка SQL вокруг sqlite3_libversion().

substr(X,Y,Z)
substr(X,Y)
substring(X,Y,Z)
substring(X,Y)

substr(X,Y,Z) вернет подстроку входной строки X, которая начинается с Y-го символа и Z знаков в длину. Если Z опущен, тогда substr(X,Y) возвращает все знаки до конца последовательности X, начиная с Y-го. Крайний левый символ X является номером 1. Если Y отрицателен, первый символ подстроки найден, считая справа, а не слева. Если Z отрицателен, abs(Z) символов, предшествующих Y-му символу, возвращены. Если X последовательность, индексы знаков относятся к фактическим знакам UTF-8. Если X BLOB, индексы относятся к байтам.

"substring()" псевдоним для "substr()" с SQLite version 3.34.

total_changes()

total_changes() возвращает количество изменений строки INSERT, UPDATE или DELETE с тех пор, как текущее соединение с базой данных было открыто. Эта функция обертка вокруг sqlite3_total_changes64().

trim(X)
trim(X,Y)

trim(X,Y) возвращает последовательность, сформированную, удаляя все символы, которые появляются в Y от обоих концов X. Если аргумент Y опущен, trim(X) удаляет пробелы с обоих концов X.

typeof(X)

typeof(X) возвращает последовательность, которая указывает тип данных выражения X: "null", "integer", "real", "text" или "blob".

unhex(X)
unhex(X,Y)

unhex(X,Y) вернет BLOB, который является расшифровкой шестнадцатеричной строки X. Если X содержит какие-либо знаки, которые не являются шестнадцатеричными цифрами и которые не находятся в Y, то unhex(X,Y) вернет NULL. Если Y опущен, он, как понимают, пустая строка, следовательно X должна быть чистой шестнадцатеричной строкой. Все шестнадцатеричные цифры в X должны быть в парах с обеими цифрами каждой пары, начинающейся строго друг за другом, иначе unhex(X,Y) вернет NULL. Если любой параметр X или Y = NULL, unhex(X,Y) вернет NULL. X на входе может содержать произвольное соединение верхнего и нижнего регистров в шестнадцатеричных цифрах. У шестнадцатеричных цифр в Y нет влияния на трансляцию X. Только знаки в Y, которые не являются шестнадцатеричными цифрами, проигнорированы в X.

См. также: hex().

unicode(X)

unicode(X) возвращает числовую unicode кодовую точку, соответствующую первому символу последовательности X. Если аргументом unicode(X) не является последовательность, результат не определен.

unlikely(X)

unlikely(X) возвращает аргумент X без изменений. unlikely(X) ничего не делает, когда генератор кода оптимизирует так, чтобы это не потребляло циклов CPU во время выполнения (то есть, во время sqlite3_step()). Цель unlikely(X) это предоставить намек планировщику запроса, что аргументом X является булево значение, которое обычно не верно. unlikely(X) эквивалентна likelihood(X, 0.0625).

upper(X)

upper(X) возвращает копию входной строки X, в которой все строчные знаки ASCII преобразовываются в их заглавный эквивалент.

zeroblob(N)

zeroblob(N) вернет BLOB, состоящий из N байтов 0x00. SQLite управляет этими объектами очень эффективно. Объект может использоваться, чтобы зарезервировать пространство для BLOB, который позже написан, используя incremental BLOB I/O. Функция SQL осуществляется, используя sqlite3_result_zeroblob() из интерфейса C/C++.