内置标量 SQL 函数

一、概述

下面显示的核心功能默认可用。日期和时间函数、聚合函数、窗口函数、数学函数和 JSON 函数分别记录。应用程序可以定义用 C 编写的附加函数，并使用sqlite3_create_function() API 添加到数据库引擎。

2.内置标量SQL函数说明

abs(X)

abs(X) 函数返回数字参数 X 的绝对值。如果 X 为 NULL，Abs(X) 返回 NULL。如果 X 是无法转换为数值的字符串或 blob，则 Abs(X) 返回 0.0。如果 X 是整数 -9223372036854775808，则 abs(X) 会抛出整数溢出错误，因为没有等效的正 64 位二进制补码值。

changes()

changes() 函数返回由最近完成的 INSERT、DELETE 或 UPDATE 语句更改、插入或删除的数据库行数，不包括较低级别触发器中的语句。changes() SQL 函数是sqlite3_changes64() C/C++ 函数的包装器，因此遵循相同的更改计数规则。

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

char(X1,X2,...,XN) 函数返回由具有整数 X1 到 XN 的 unicode 代码点值的字符组成的字符串。

coalesce(X,Y,...)

coalesce() 函数返回其第一个非 NULL 参数的副本，如果所有参数均为 NULL，则返回 NULL。Coalesce() 必须至少有 2 个参数。

format(FORMAT,...)

format(FORMAT,...) SQL 函数的工作方式类似于标准 C 库中的sqlite3_mprintf() C 语言函数和 printf() 函数。第一个参数是一个格式字符串，它指定如何使用从后续参数中获取的值来构造输出字符串。如果缺少 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 内容的大写十六进制呈现。

如果“hex( X )”中的参数X是整数或浮点数，则“将其参数解释为 BLOB”意味着首先将二进制数转换为 UTF8 文本表示形式，然后将该文本解释为 BLOB . 因此，“hex(12345678)”呈现为“3132333435363738”，而不是整数值“0000000000BC614E”的二进制表示。

ifnull(X,Y)

ifnull() 函数返回其第一个非 NULL 参数的副本，如果两个参数均为 NULL，则返回 NULL。Ifnull() 必须恰好有 2 个参数。ifnull() 函数等效于带有两个参数的coalesce() 。

iif(X,Y,Z)

如果 X 为真，则 iif(X,Y,Z) 函数返回值 Y，否则返回 Z。iif(X,Y,Z) 函数在逻辑上等同于并生成与 CASE 表达式“CASE WHEN X THEN Y ELSE Z END”相同的字节码。

instr(X,Y)

instr(X,Y) 函数查找字符串 X 中字符串 Y 的第一次出现，并返回前面字符数加 1，如果在 X 中找不到 Y，则返回 0。或者，如果 X 和 Y 都是 BLOB，则 instr (X,Y) 返回比第一次出现 Y 之前的字节数多一个，或者如果 Y 没有出现在 X 中的任何地方则返回 0。如果 instr(X,Y) 的参数 X 和 Y 都是非 NULL 并且是不是 BLOB，则两者都被解释为字符串。如果在 instr(X,Y) 中 X 或 Y 为 NULL，则结果为 NULL。

last_insert_rowid()

last_insert_rowid() 函数返回从调用该函数的数据库连接插入的最后一行的ROWID 。last_insert_rowid() SQL 函数是 sqlite3_last_insert_rowid() C/C++ 接口函数的包装器。

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 字符串的字节长度。

对于 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运算符，like() 函数中的 X 和 Y 参数是相反的。X 是模式，Y 是要匹配该模式的字符串。因此，以下表达式是等价的：

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

sqlite3_create_function()接口可用于覆盖 like() 函数，从而改变 LIKE运算符的操作。覆盖 like() 函数时，覆盖 like() 函数的两个和三个参数版本可能很重要。否则，可能会调用不同的代码来实现 LIKE运算符，具体取决于是否指定了 ESCAPE 子句。

likelihood(X,Y)

likelihood(X,Y) 函数返回参数 X 不变。likelihood(X,Y) 中的值 Y 必须是介于 0.0 和 1.0（含）之间的浮点常量。likelihood(X) 函数是代码生成器优化掉的空操作，因此它在运行时（即，在调用sqlite3_step()期间）不消耗 CPU 周期。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()期间）不消耗 CPU 周期。likely(X) 函数的目的是向查询规划器提供一个提示，即参数 X 是一个布尔值，通常为真。likely(X) 函数等同于likelihood (X,0.9375)。另见：不太可能（X）。

load_extension(X) load_extension(X,Y)

load_extension(X,Y) 函数使用入口点 Y 从名为 X 的共享库文件中加载SQLite 扩展。load_extension() 的结果始终为 NULL。如果省略 Y，则使用默认入口点名称。如果扩展未能正确加载或初始化，load_extension() 函数会引发异常。

如果扩展试图修改或删除 SQL 函数或整理顺序，load_extension() 函数将失败。该扩展可以添加新函数或整理序列，但不能修改或删除现有函数或整理序列，因为这些函数和/或整理序列可能会在当前运行的 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) 函数返回一个字符串，该字符串通过从 X 的左侧删除 Y 中出现的所有字符而形成。如果省略 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 整理函数。

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，则返回一个 1 字节的随机 blob。

提示：应用程序可以使用此函数与hex()和/或 lower()一起生成全局唯一标识符，如下所示：

十六进制（随机斑点（16））

较低（十六进制（随机斑点（16）））

replace(X,Y,Z)

replace(X,Y,Z) 函数返回一个字符串，该字符串通过用字符串 Z 替换字符串 X 中每次出现的字符串 Y 而形成。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)

如果参数 X 是一个分别为负、零或正的数值，则 sign(X) 函数返回 -1、0 或 +1。如果 sign(X) 的参数为 NULL 或者是不能无损转换为数字的字符串或 blob，则 sign(X) 返回 NULL。

soundex(X)

soundex(X) 函数返回一个字符串，它是字符串 X 的 soundex 编码。如果参数为 NULL 或不包含 ASCII 字母字符，则返回字符串“?000”。SQLite 默认省略了这个函数。只有在构建 SQLite 时使用了SQLITE_SOUNDEX编译时选项，它才可用。

sqlite_compileoption_get(N)

sqlite_compileoption_get() SQL 函数是 sqlite3_compileoption_get() C/C++ 函数的包装器。此例程返回用于构建 SQLite 的第 N 个编译时选项，如果 N 超出范围则返回 NULL。另请参阅compile_options pragma。

sqlite_compileoption_used(X)

sqlite_compileoption_used() SQL 函数是 sqlite3_compileoption_used() C/C++ 函数的包装器。当 sqlite_compileoption_used(X) 的参数 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 函数仅在使用-DSQLITE_ENABLE_OFFSET_SQL_FUNC编译时选项构建 SQLite 时可用。

sqlite_source_id()

sqlite_source_id() 函数返回一个字符串，用于标识用于构建 SQLite 库的源代码的特定版本。sqlite_source_id() 返回的字符串是签入源代码的日期和时间，后跟该签入的 SHA3-256 哈希值。此函数是sqlite3_sourceid() C 接口周围的 SQL 包装器。

sqlite_version()

sqlite_version() 函数返回正在运行的 SQLite 库的版本字符串。此函数是sqlite3_libversion() C 接口周围的 SQL 包装器。

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 为负，则返回第 Y 个字符之前的 abs(Z) 个字符。如果 X 是一个字符串，那么字符索引指的是实际的 UTF-8 字符。如果 X 是 BLOB，则索引指的是字节。

“substring()”是从 SQLite 版本 3.34 开始的“substr()”的别名。

total_changes()

total_changes() 函数返回自当前数据库连接打开以来由 INSERT、UPDATE 或 DELETE 语句引起的行更改数。此函数是sqlite3_total_changes64() C/C++ 接口的包装器。

trim(X) trim(X,Y)

trim(X,Y) 函数返回一个字符串，该字符串通过从 X 的两端删除 Y 中出现的任何和所有字符而形成。如果省略 Y 参数，trim(X) 将从 X 的两端删除空格。

typeof(X)

typeof(X) 函数返回一个字符串，指示表达式 X 的数据类型：“null”、“integer”、“real”、“text”或“blob”。

unicode(X)

unicode(X) 函数返回与字符串 X 的第一个字符对应的数字 unicode 代码点。如果 unicode(X) 的参数不是字符串，则结果未定义。

unlikely(X)

unlikely(X) 函数返回参数 X 不变。unlikely(X) 函数是代码生成器优化掉的空操作，因此它在运行时（即在调用sqlite3_step()期间）不消耗 CPU 周期。unlikely(X) 函数的目的是向查询规划器提供一个提示，即参数 X 是一个通常不为真的布尔值。unlikely(X) 函数等同于likelihood (X, 0.0625)。

upper(X)

upper(X) 函数返回输入字符串 X 的副本，其中所有小写 ASCII 字符都转换为对应的大写字符。

zeroblob(N)

zeroblob(N) 函数返回由 N 个字节的 0x00 组成的 BLOB。SQLite 非常有效地管理这些 zeroblob。Zeroblob 可用于为稍后使用增量 BLOB I/O写入的 BLOB 保留空间。此 SQL 函数是使用 C/C++ 接口中的sqlite3_result_zeroblob()例程实现的。