Встроенные скалярные SQL-функции

1. Обзор

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

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) вызывает ошибку переполнения целого числа, поскольку эквивалентного положительного 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, если все аргументы равны NULL. Функция coalesce() должна иметь не менее двух аргументов.

concat(X,...)

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

concat_ws(SEP,X,...)

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

format(FORMAT,...)

Функция SQL format(FORMAT,...) работает так же, как функция C 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". Обратите внимание, что в функции glob() аргументы X и Y расположены в обратном порядке по сравнению с инфиксным оператором GLOB. Y — это строка, а X — шаблон. Например, следующие выражения эквивалентны:

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

Если интерфейс sqlite3_create_function() используется для замены функции glob(X,Y) альтернативной реализацией, оператор GLOB будет вызывать эту альтернативную реализацию.

hex(X)

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

Если аргумент X в "hex(X)" — целое число или число с плавающей запятой, то под фразой «интерпретирует свой аргумент как BLOB» подразумевается, что сначала двоичное число преобразуется в текстовое представление UTF8, а затем этот текст интерпретируется как BLOB. Поэтому "hex(12345678)" возвращает "3132333435363738", а не двоичное представление целого числа "0000000000BC614E".

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

ifnull(X,Y)

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

iif(B1,V1,...)
if(B1,V1,...)

Функция iif(B1,V1,...,BN,VN) принимает аргументы парами. Первый аргумент каждой пары — это логическое значение, а второй — значение, возвращаемое, если логическое значение истинно. Функция iif() возвращает значение, связанное с первым истинным логическим значением. Если число аргументов iif() нечётное, последний аргумент возвращается, если все предыдущие логические аргументы ложны. Если число аргументов чётное и все логические аргументы ложны, возвращается NULL. Функции iif() требуется не менее двух аргументов. Функция iif() фактически является краткой записью для выражения CASE. Например, функция iif(X,Y,Z) логически эквивалентна выражению CASE "CASE WHEN X THEN Y ELSE Z END" и генерирует тот же байткод. Функция if() — это просто альтернативное написание iif().

Функция iif() использует вычисление с коротким замыканием. Аргументы вычисляются только тогда, когда это необходимо для получения конечного результата. Например, если один из аргументов-значений требует затратных вычислений (например, сложного подзапроса), но соответствующее логическое значение ложно, эти вычисления не выполняются. Аналогично, логические аргументы, следующие за первым истинным аргументом, не вычисляются.

Изначально функция iif() требовала ровно три аргумента. Версия iif() с двумя аргументами и возможность записывать имя функции как "if()" появились в SQLite версии 3.48.0 (2025-01-14). Возможность принимать более трёх аргументов добавлена в SQLite версии 3.49.0 (2025-02-06).

instr(X,Y)

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

last_insert_rowid()

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

length(X)

Для строкового значения X функция length(X) возвращает количество кодовых точек Unicode (не байтов) во входной строке X до первого символа U+0000. Поскольку строки SQLite обычно не содержат символов NUL, функция length(X) обычно возвращает общее количество символов в строке X. Для значения BLOB функция 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() вызывается с тремя аргументами. В противном случае она вызывается только с двумя аргументами. Обратите внимание, что в функции like() параметры X и Y расположены в обратном порядке по сравнению с инфиксным оператором 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) ничего не делает: генератор кода оптимизирует её, поэтому во время выполнения она не расходует циклы ЦП (то есть при вызовах 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) ничего не делает: генератор кода оптимизирует её, поэтому во время выполнения она не расходует циклы ЦП (то есть при вызовах sqlite3_step()). Назначение функции likely(X) — подсказать планировщику запросов, что аргумент X является логическим значением, обычно истинным. Функция likely(X) эквивалентна likelihood(X,0.9375). См. также: unlikely(X).

load_extension(X)
load_extension(X,Y)

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

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

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

lower(X)

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

ltrim(X)
ltrim(X,Y)

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

max(X,Y,...)

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

min(X,Y,...)

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

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 — столбец таблицы, содержащий значение типа text или blob, функция octet_length(X) не считывает содержимое X с диска, поскольку длину в байтах можно вычислить по метаданным. Поэтому octet_length(X) работает эффективно, даже если X — столбец, содержащий текстовое значение или значение blob размером в несколько мегабайт.

printf(FORMAT,...)

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

quote(X)

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

Функция unistr_quote(X) работает как quote(X), но дополнительно экранирует управляющие символы.

random()

Функция random() возвращает псевдослучайное целое число в диапазоне от -9223372036854775807 до +9223372036854775807.

Функция random() намеренно не генерирует -9223372036854775808, чтобы её значение всегда можно было передать функции abs(). Функция random() работает таким образом начиная с версии 3.3.5 (примерно с 2006 года), однако в документации ошибочно указывалось, что -9223372036854775808 может быть результатом, вплоть до 2025-07-25.

randomblob(N)

Функция randomblob(N) возвращает BLOB размером N байт, содержащий псевдослучайные байты. Если N меньше 1, возвращается случайный BLOB размером 1 байт.

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

hex(randomblob(16))
lower(hex(randomblob(16)))

replace(X,Y,Z)

Функция replace(X,Y,Z) возвращает строку, полученную заменой каждого вхождения строки Y в строке X строкой Z. Для сравнений используется последовательность сортировки 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) возвращает строку, полученную удалением с правой стороны X всех символов, встречающихся в Y. Если аргумент 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. Если аргумент равен NULL или не содержит символов ASCII, обозначающих буквы, возвращается строка "?000". По умолчанию эта функция не включена в SQLite. Она доступна только в том случае, если при сборке SQLite используется параметр компиляции SQLITE_SOUNDEX.

sqlite_compileoption_get(N)

Функция SQL sqlite_compileoption_get() является обёрткой над функцией C/C++ sqlite3_compileoption_get(). Эта процедура возвращает N-й параметр компиляции, использованный при сборке SQLite, или NULL, если N выходит за допустимые пределы. См. также прагму compile_options.

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 для интерфейса C sqlite3_sourceid().

sqlite_version()

Функция sqlite_version() возвращает строку версии работающей библиотеки SQLite. Эта функция SQL является обёрткой интерфейса C 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) возвращает все символы от Y-го до конца строки X. Самый левый символ X имеет номер 1. Если Y отрицательно, первый символ подстроки определяется отсчётом справа налево, а не слева направо. Если Z отрицательно, возвращаются abs(Z) символов, предшествующих Y-му символу. Если X — строка, индексы символов соответствуют символам UTF-8. Если X — BLOB, индексы соответствуют байтам.

Начиная с версии SQLite 3.34, "substring()" является псевдонимом для "substr()".

total_changes()

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

trim(X)
trim(X,Y)

Функция trim(X,Y) возвращает строку, полученную удалением с обоих концов X всех символов, встречающихся в Y. Если аргумент 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. В X игнорируются только символы из Y, не являющиеся шестнадцатеричными цифрами.

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

unicode(X)

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

unistr(X)

Функция unistr(X) интерпретирует экранированные обратной косой чертой последовательности во входной строке X и возвращает новую строку, в которой эти последовательности заменены соответствующими символами Unicode. Эта функция, добавленная в SQLite версии 3.50.0 (2025-05-29), предназначена для работы так же, как в PostgreSQL, SQL Server и Oracle. В документации PostgreSQL сказано: "Символы Unicode можно задавать как \XXXX (4 шестнадцатеричные цифры), \+XXXXXX (6 шестнадцатеричных цифр), \uXXXX (4 шестнадцатеричные цифры) или \UXXXXXXXX (8 шестнадцатеричных цифр). Чтобы указать обратную косую черту, запишите две обратные косые черты. Все остальные символы воспринимаются буквально."

unistr_quote(X)

Функция unistr_quote(X) возвращает текст SQL-литерала или константного выражения, кодирующего значение аргумента X и пригодного для включения в инструкцию SQL. В большинстве случаев результат unistr_quote(X) идентичен quote(X). Однако, если X — текст, содержащий управляющие символы в диапазоне от U+0001 до U+001f, эти символы и все символы "\" в X экранируются с помощью экранирования обратной косой чертой в стиле JSON, а весь результат заключается в "unistr(..)". Благодаря этому полученный текст безопасно отображать на устройствах, интерпретирующих коды управления ANSI.

unlikely(X)

Функция unlikely(X) возвращает аргумент X без изменений. Функция unlikely(X) ничего не делает: генератор кода оптимизирует её, поэтому во время выполнения она не расходует циклы ЦП (то есть при вызовах 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 очень эффективно управляет такими zeroblob. Zeroblob можно использовать для резервирования места под BLOB, который позднее будет записан с помощью инкрементального ввода-вывода BLOB. Эта функция SQL реализована с помощью процедуры sqlite3_result_zeroblob() из интерфейса C/C++.

Последнее обновление этой страницы: 2026-02-18 11:56:50Z