标量实用函数
以下函数难以归类为特定的函数类型，但用途广泛。
| 名称 | 描述 |
|---|---|
alias(column) |
返回列的名称。 |
can_cast_implicitly(source_value, target_value) |
判断是否可以从源值的类型隐式转换为目标类型。 |
checkpoint(database) |
在不中断事务的情况下，为（可选的）数据库同步预写日志（WAL）与文件。 |
coalesce(expr, ...) |
返回第一个计算结果为非 NULL 的表达式。接受 1 个或多个参数。每个表达式可以是列、字面量值、函数结果或其他内容。 |
constant_or_null(arg1, arg2) |
如果 arg2 为 NULL，则返回 NULL。否则，返回 arg1。 |
count_if(x) |
聚合函数；如果 x 为 true 或非零数值，则行计为 1，否则计为 0。 |
create_sort_key(parameters...) |
基于一组输入参数和排序限定符构建二进制可比较的排序键。 |
current_catalog() |
返回当前活动目录（catalog）的名称。默认为 memory。 |
current_database() |
返回当前活动数据库的名称。 |
current_query() |
以字符串形式返回当前查询。 |
current_schema() |
返回当前活动模式（schema）的名称。默认为 main。 |
current_schemas(boolean) |
返回模式列表。传入参数 true 以包含隐式模式。 |
current_setting('setting_name') |
返回配置设置的当前值。 |
currval('sequence_name') |
返回序列的当前值。注意：在调用 currval 之前，必须至少调用一次 nextval。 |
error(message) |
抛出给定的错误 message。 |
equi_width_bins(min, max, bincount, nice := false) |
返回将区间 [min, max] 分割为 bin_count 个等长子区间的上边界（用于例如 histogram）。如果 nice = true，则 min、max 和 bincount 可能会被调整以产生更美观的结果。 |
force_checkpoint(database) |
同步（可选的）数据库的 WAL 与文件，并会中断事务。 |
gen_random_uuid() |
返回一个随机 UUID，例如：eeccb8c5-9943-b2bb-bb5e-222f4e14b687。 |
getenv(var) |
返回环境变量 var 的值。仅在 命令行客户端 中可用。 |
hash(value) |
返回 value 的哈希值（UBIGINT 类型）。所使用的哈希函数在不同的 DuckDB 版本间可能会发生变化。 |
icu_sort_key(string, collator) |
用于根据特定区域设置排序特殊字符的代理 排序键 (sort key)。Collator 参数是可选的。仅在安装了 ICU 扩展时可用。 |
if(a, b, c) |
三元条件运算符。 |
ifnull(expr, other) |
coalesce 的双参数版本。 |
is_histogram_other_bin(arg) |
当 arg 是 histogram_exact 函数目的下的数据类型“兜底元素”（catch-all element）时返回 true，该元素等于 histogram 函数目的下该数据类型的“最右边界”。 |
md5(string) |
将 string 的 MD5 哈希值作为 VARCHAR 返回。 |
md5_number(string) |
将 string 的 MD5 哈希值作为 UHUGEINT 返回。 |
md5_number_lower(string) |
将 string 的 MD5 哈希值的低 64 位片段作为 UBIGINT 返回。 |
md5_number_upper(string) |
将 string 的 MD5 哈希值的高 64 位片段作为 UBIGINT 返回。 |
nextval('sequence_name') |
返回序列的下一个值。 |
nullif(a, b) |
如果 a = b 则返回 NULL，否则返回 a。等同于 CASE WHEN a = b THEN NULL ELSE a END。 |
pg_typeof(expression) |
返回表达式结果数据类型的名称（小写）。为了与 PostgreSQL 兼容。 |
query(query_string) |
解析并执行 query_string 中定义的查询的表函数。仅允许使用常量字符串。警告：此函数允许调用任意查询，可能会改变数据库状态。 |
query_table(tbl_name) |
返回 tbl_name 中给定表的表函数。 |
query_table(tbl_names, [by_name]) |
返回 tbl_names 中给定表并集的表函数。如果可选参数 by_name 设置为 true，则使用 UNION ALL BY NAME 语义。 |
read_blob(source) |
将 source（文件名、文件名列表或 glob 模式）的内容作为 BLOB 返回。详见 read_blob 指南。 |
read_text(source) |
将 source（文件名、文件名列表或 glob 模式）的内容作为 VARCHAR 返回。首先会验证文件内容是否为有效的 UTF-8。如果 read_text 尝试读取包含无效 UTF-8 的文件，会抛出错误并建议改用 read_blob。详见 read_text 指南。 |
sha1(string) |
返回包含 string 的 SHA-1 哈希值的 VARCHAR。 |
sha256(string) |
返回包含 string 的 SHA-256 哈希值的 VARCHAR。 |
stats(expression) |
返回包含表达式统计信息的字符串。表达式可以是列、常量或 SQL 表达式。 |
txid_current() |
返回当前事务的标识符（BIGINT 值）。如果当前事务尚未分配 ID，则会分配一个新的。 |
typeof(expression) |
返回表达式结果的数据类型名称。 |
uuid() |
返回一个随机 UUID (UUIDv4)，例如：eeccb8c5-9943-b2bb-bb5e-222f4e14b687。 |
uuidv4() |
返回一个随机 UUID (UUIDv4)，例如：eeccb8c5-9943-b2bb-bb5e-222f4e14b687。 |
uuidv7() |
返回一个随机 UUIDv7，例如：81964ebe-00b1-7e1d-b0f9-43c29b6fb8f5。 |
uuid_extract_timestamp(uuidv7) |
从 UUIDv7 值中提取 TIMESTAMP WITH TIME ZONE。 |
uuid_extract_version(uuid) |
提取 UUID 版本（4 或 7）。 |
version() |
以特定格式返回当前活动的 DuckDB 版本。 |
alias(column)
| 描述 | 返回列的名称。 |
| 示例 | alias(column1) |
| 结果 | column1 |
can_cast_implicitly(source_value, target_value)
| 描述 | 判断是否可以从源值的类型隐式转换为目标类型。 |
| 示例 | can_cast_implicitly(1::BIGINT, 1::SMALLINT) |
| 结果 | false |
checkpoint(database)
| 描述 | 在不中断事务的情况下，为（可选的）数据库同步预写日志（WAL）与文件。 |
| 示例 | checkpoint(my_db) |
| 结果 | success Boolean |
coalesce(expr, ...)
| 描述 | 返回第一个计算结果为非 NULL 的表达式。接受 1 个或多个参数。每个表达式可以是列、字面量值、函数结果或其他内容。 |
| 示例 | coalesce(NULL, NULL, 'default_string') |
| 结果 | default_string |
constant_or_null(arg1, arg2)
| 描述 | 如果 arg2 为 NULL，则返回 NULL。否则，返回 arg1。 |
| 示例 | constant_or_null(42, NULL) |
| 结果 | NULL |
count_if(x)
| 描述 | 聚合函数；如果 x 为 true 或非零数值，则行计为 1，否则计为 0。 |
| 示例 | count_if(42) |
| 结果 | 1 |
create_sort_key(parameters...)
| 描述 | 基于一组输入参数和排序限定符构建二进制可比较的排序键。 |
| 示例 | create_sort_key('abc', 'ASC NULLS FIRST'); |
| 结果 | \x02bcd\x00 |
current_catalog()
| 描述 | 返回当前活动目录（catalog）的名称。默认为 memory。 |
| 示例 | current_catalog() |
| 结果 | memory |
current_database()
| 描述 | 返回当前活动数据库的名称。 |
| 示例 | current_database() |
| 结果 | memory |
current_query()
| 描述 | 以字符串形式返回当前查询。 |
| 示例 | current_query() |
| 结果 | SELECT current_query(); |
current_schema()
| 描述 | 返回当前活动模式（schema）的名称。默认为 main。 |
| 示例 | current_schema() |
| 结果 | main |
current_schemas(boolean)
| 描述 | 返回模式列表。传入参数 true 以包含隐式模式。 |
| 示例 | current_schemas(true) |
| 结果 | ['temp', 'main', 'pg_catalog'] |
current_setting('setting_name')
| 描述 | 返回配置设置的当前值。 |
| 示例 | current_setting('access_mode') |
| 结果 | automatic |
currval('sequence_name')
| 描述 | 返回序列的当前值。注意：在调用 currval 之前，必须至少调用一次 nextval。 |
| 示例 | currval('my_sequence_name') |
| 结果 | 1 |
error(message)
| 描述 | 抛出给定的错误 message。 |
| 示例 | error('access_mode') |
equi_width_bins(min, max, bincount, nice := false)
| 描述 | 返回将区间 [min, max] 分割为 bin_count 个等长子区间的上边界（用于例如 histogram）。如果 nice = true，则 min、max 和 bincount 可能会被调整以产生更美观的结果。 |
| 示例 | equi_width_bins(0.1, 2.7, 4, true) |
| 结果 | [0.5, 1.0, 1.5, 2.0, 2.5, 3.0] |
force_checkpoint(database)
| 描述 | 同步（可选的）数据库的 WAL 与文件，并会中断事务。 |
| 示例 | force_checkpoint(my_db) |
| 结果 | success Boolean |
gen_random_uuid()
| 描述 | 返回一个随机 UUID (UUIDv4)，例如：eeccb8c5-9943-b2bb-bb5e-222f4e14b687。 |
| 示例 | gen_random_uuid() |
| 结果 | various |
getenv(var)
| 描述 | 返回环境变量 var 的值。仅在 命令行客户端 中可用。 |
| 示例 | getenv('HOME') |
| 结果 | /path/to/user/home |
hash(value)
| 描述 | 返回 value 的哈希值（UBIGINT 类型）。所使用的哈希函数在不同的 DuckDB 版本间可能会发生变化。 |
| 示例 | hash('🦆') |
| 结果 | 2595805878642663834 |
icu_sort_key(string, collator)
| 描述 | 用于根据特定区域设置排序特殊字符的代理 排序键 (sort key)。Collator 参数是可选的。仅在安装了 ICU 扩展时可用。 |
| 示例 | icu_sort_key('ö', 'DE') |
| 结果 | 460145960106 |
if(a, b, c)
| 描述 | 三元条件运算符；如果 a 为真则返回 b，否则返回 c。等同于 CASE WHEN a THEN b ELSE c END。 |
| 示例 | if(2 > 1, 3, 4) |
| 结果 | 3 |
ifnull(expr, other)
| 描述 | coalesce 的双参数版本。 |
| 示例 | ifnull(NULL, 'default_string') |
| 结果 | default_string |
is_histogram_other_bin(arg)
| 描述 | 当 arg 是 histogram_exact 函数目的下的数据类型“兜底元素”（catch-all element）时返回 true，该元素等于 histogram 函数目的下该数据类型的“最右边界”。 |
| 示例 | is_histogram_other_bin('') |
| 结果 | true |
md5(string)
| 描述 | 将 string 的 MD5 哈希值作为 VARCHAR 返回。 |
| 示例 | md5('abc') |
| 结果 | 900150983cd24fb0d6963f7d28e17f72 |
md5_number(string)
| 描述 | 将 string 的 MD5 哈希值作为 UHUGEINT 返回。 |
| 示例 | md5_number('abc') |
| 结果 | 152195979970564155685860391459828531600 |
md5_number_lower(string)
| 描述 | 将 string 的 MD5 哈希值的低 8 字节作为 UBIGINT 返回。 |
| 示例 | md5_number_lower('abc') |
| 结果 | 8250560606382298838 |
md5_number_upper(string)
| 描述 | 将 string 的 MD5 哈希值的高 8 字节作为 UBIGINT 返回。
|
| 示例 | md5_number_upper('abc') |
| 结果 | 12704604231530709392 |
nextval('sequence_name')
| 描述 | 返回序列的下一个值。 |
| 示例 | nextval('my_sequence_name') |
| 结果 | 2 |
nullif(a, b)
| 描述 | 如果 a = b 则返回 NULL，否则返回 a。等同于 CASE WHEN a = b THEN NULL ELSE a END。 |
| 示例 | nullif(1+1, 2) |
| 结果 | NULL |
pg_typeof(expression)
| 描述 | 返回表达式结果数据类型的名称（小写）。为了与 PostgreSQL 兼容。 |
| 示例 | pg_typeof('abc') |
| 结果 | varchar |
query(query_string)
| 描述 | 解析并执行 query_string 中定义的查询的表函数。仅允许使用常量字符串。警告：此函数允许调用任意查询，可能会改变数据库状态。
|
| 示例 | query('SELECT 42 AS x') |
| 结果 | 42 |
query_table(tbl_name)
| 描述 | 返回 tbl_name 中给定表的表函数。 |
| 示例 | query_table('t1') |
| 结果 | (t1 的所有行) |
query_table(tbl_names, [by_name])
| 描述 | 返回 tbl_names 中给定表并集的表函数。如果可选的 by_name 参数设置为 true，则使用 UNION ALL BY NAME 语义。 |
| 示例 | query_table(['t1', 't2']) |
| 结果 | (两个表的并集) |
read_blob(source)
| 描述 | 将 source（文件名、文件名列表或 glob 模式）的内容作为 BLOB 返回。详见 read_blob 指南。 |
| 示例 | read_blob('hello.bin') |
| 结果 | hello\x0A |
read_text(source)
| 描述 | 将 source（文件名、文件名列表或 glob 模式）的内容作为 VARCHAR 返回。首先会验证文件内容是否为有效的 UTF-8。如果 read_text 尝试读取包含无效 UTF-8 的文件，会抛出错误并建议改用 read_blob。详见 read_text 指南。 |
| 示例 | read_text('hello.txt') |
| 结果 | hello\n |
sha1(string)
| 描述 | 返回包含 string 的 SHA-1 哈希值的 VARCHAR。 |
| 示例 | sha1('🦆') |
| 结果 | 949bf843dc338be348fb9525d1eb535d31241d76 |
sha256(string)
| 描述 | 返回包含 string 的 SHA-256 哈希值的 VARCHAR。 |
| 示例 | sha256('🦆') |
| 结果 | d7a5c5e0d1d94c32218539e7e47d4ba9c3c7b77d61332fb60d633dde89e473fb |
stats(expression)
| 描述 | 返回包含表达式统计信息的字符串。表达式可以是列、常量或 SQL 表达式。 |
| 示例 | stats(5) |
| 结果 | '[Min: 5, Max: 5][Has Null: false]' |
txid_current()
| 描述 | 返回当前事务的标识符（BIGINT 值）。如果当前事务尚未分配 ID，则会分配一个新的。 |
| 示例 | txid_current() |
| 结果 | various |
typeof(expression)
| 描述 | 返回表达式结果的数据类型名称。 |
| 示例 | typeof('abc') |
| 结果 | VARCHAR |
uuid()
| 描述 | 返回一个随机 UUID (UUIDv4)，例如：eeccb8c5-9943-b2bb-bb5e-222f4e14b687。 |
| 示例 | uuid() |
| 结果 | various |
uuidv4()
| 描述 | 返回一个随机 UUID (UUIDv4)，例如：eeccb8c5-9943-b2bb-bb5e-222f4e14b687。 |
| 示例 | uuidv4() |
| 结果 | various |
uuidv7()
| 描述 | 返回一个随机 UUIDv7，例如：81964ebe-00b1-7e1d-b0f9-43c29b6fb8f5。 |
| 示例 | uuidv7() |
| 结果 | various |
uuid_extract_timestamp(uuidv7)
| 描述 | 从 UUIDv7 值中提取 TIMESTAMP WITH TIME ZONE。 |
| 示例 | uuid_extract_timestamp(uuidv7()) |
| 结果 | 2025-04-19 15:51:20.07+00 |
uuid_extract_version(uuid)
| 描述 | 提取 UUID 版本（4 或 7）。 |
| 示例 | uuid_extract_version(uuidv7()) |
| 结果 | 7 |
version()
| 描述 | 以特定格式返回当前活动的 DuckDB 版本。 |
| 示例 | version() |
| 结果 | various |
实用表函数
表函数 在 FROM 子句中用于代替表。
| 名称 | 描述 |
|---|---|
glob(search_path) |
返回 search_path 指示位置下找到的文件名，列名为 file。search_path 可以包含 glob 模式匹配语法。 |
repeat_row(varargs, num_rows) |
返回一个包含 num_rows 行的表，每一行都包含 varargs 中定义的字段。 |
glob(search_path)
| 描述 | 返回 search_path 指示位置下找到的文件名，列名为 file。search_path 可以包含 glob 模式匹配语法。 |
| 示例 | glob('*') |
| 结果 | (文件名列表) |
repeat_row(varargs, num_rows)
| 描述 | 返回一个包含 num_rows 行的表，每一行都包含 varargs 中定义的字段。 |
| 示例 | repeat_row(1, 2, 'foo', num_rows = 3) |
| 结果 | 3 行 1, 2, 'foo' |