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

1. Обзор

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

вызов простой функции:

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

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

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

abs(X)

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

changes()

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

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

Функция char(X1,X2,...,XN) возвращает строку, составленную из символов, имеющих значения кодов Юникода целых чисел X1 до XN соответственно.

coalesce(X,Y,...)

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

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,...) работает как функция sqlite3_mprintf() на языке C и функция 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)" — целое или дробное число, то "интерпретирует свой аргумент как BLOB" означает, что двоичное число сначала преобразуется в текстовое представление UTF8, а затем этот текст интерпретируется как BLOB. Следовательно, "hex(12345678)" отображается как "3132333435363738", а не двоичное представление целого значения "0000000000BC614E".

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

ifnull(X,Y)

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

iif(X,Y,Z)

Функция iif(X,Y,Z) возвращает значение Y, если X истинно, и Z в противном случае. Функция iif(X,Y,Z) логически эквивалентна и генерирует тот же байткод, что и выражение CASE "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) возвращает значение, на единицу большее, чем количество байтов до первого вхождения 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 до первого символа U+0000. Поскольку строки 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) — это функция без действий, которую генератор кода оптимизирует, чтобы она не потребляла процессорных ресурсов во время выполнения (то есть во время вызовов 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) возвращает строку, полученную путем удаления всех символов, присутствующих в Y, из левой части X. Если аргумент Y опущен, ltrim(X) удаляет пробелы из левой части X.

max(X,Y,...)

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

min(X,Y,...)

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

printf(FORMAT,...)

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

quote(X)

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

random()

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

randomblob(N)

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

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

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

replace(X,Y,Z)

Функция replace(X,Y,Z) возвращает строку, образованную заменой каждой вхождения строки Y на строку Z в строке 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)

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

sqlite_compileoption_used(X)

Функция sqlite_compileoption_used() SQL является обёрткой вокруг функции sqlite3_compileoption_used() C/C++. Если аргумент 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) возвращает смещение до записи таблицы.

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

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

total_changes()

Функция total_changes() возвращает количество изменений строк, вызванных операторами INSERT, UPDATE или DELETE с момента открытия текущего подключения к базе данных. Эта функция является обёрткой вокруг C/C++ интерфейса 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) — это операция без эффекта, которую генератор кода оптимизирует, чтобы она не потребляла циклы процессора во время выполнения (то есть, во время вызовов sqlite3_step()). Цель функции unlikely(X) — дать подсказку планировщику запросов, что аргумент X — это булево значение, которое обычно не равно true. Функция unlikely(X) эквивалентна likelihood(X, 0.0625).

upper(X)

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

zeroblob(N)

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

Эта страница была последний раз изменена 26.09.2024 22:54:18 UTC