实用函数 – DuckDB 数据库

搜索快捷键 cmd + k | ctrl + k

文档 / SQL / 函数

实用函数

标量实用函数

以下函数难以归入特定函数类型，但普遍有用。

名称	描述
`alias(column)`	返回列的名称。
`can_cast_implicitly(source_value, target_value)`	是否可以从源值类型隐式转换为目标值类型。
`checkpoint(database)`	在不中断事务的情况下，将 WAL 与（可选）数据库的文件同步。
`coalesce(expr, ...)`	返回第一个评估结果为非`NULL`值的表达式。接受一个或多个参数。每个表达式可以是列、字面值、函数结果或其他许多类型。
`constant_or_null(arg1, arg2)`	如果 `arg2` 为 `NULL`，则返回 `NULL`。否则，返回 `arg1`。
`count_if(x)`	聚合函数；如果 `x` 为 `true` 或非零数字，则行计数为 1，否则为 0。
`create_sort_key(parameters...)`	根据一组输入参数和排序限定符构造一个可二进制比较的排序键。
`current_catalog()`	返回当前活动目录的名称。默认为内存。
`current_database()`	返回当前活动数据库的名称。
`current_query()`	将当前查询作为字符串返回。
`current_schema()`	返回当前活动模式的名称。默认为主模式。
`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`。
`icu_sort_key(string, collator)`	根据特定区域设置对特殊字符进行排序的代理排序键。校对参数是可选的。仅当安装了 ICU 扩展时可用。
`if(a, b, c)`	三元条件运算符。
`ifnull(expr, other)`	coalesce 的两参数版本。
`is_histogram_other_bin(arg)`	当 `arg` 是其数据类型中的“包罗万象元素”（用于 `histogram_exact` 函数），且等于其数据类型中的“最右边界”（用于 `histogram` 函数）时，返回 `true`。
`md5(string)`	以 `VARCHAR` 形式返回 `string` 的 MD5 哈希值。
`md5_number(string)`	以 `UHUGEINT` 形式返回 `string` 的 MD5 哈希值。
`md5_number_lower(string)`	以 `UBIGINT` 形式返回 `string` 的 MD5 哈希值的低 64 位段。
`md5_number_upper(string)`	以 `UBIGINT` 形式返回 `string` 的 MD5 哈希值的高 64 位段。
`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_literal``)`	表函数，解析并执行`query_string_literal`中定义的查询。只允许字面字符串。警告：此函数允许调用任意查询，可能更改数据库状态。
`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` 值。如果当前事务尚未分配标识符，则会分配一个新的。
`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 值中提取时间戳。
`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`值的表达式。接受一个或多个参数。每个表达式可以是列、字面值、函数结果或其他许多类型。
示例	`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()`

描述	返回当前活动目录的名称。默认为内存。
示例	`current_catalog()`
结果	`memory`

`current_database()`

描述	返回当前活动数据库的名称。
示例	`current_database()`
结果	`memory`

`current_query()`

描述	将当前查询作为字符串返回。
示例	`current_query()`
结果	`SELECT current_query();`

`current_schema()`

描述	返回当前活动模式的名称。默认为主模式。
示例	`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`。
示例	`hash('🦆')`
结果	`2595805878642663834`

`icu_sort_key(string, 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` 函数），且等于其数据类型中的“最右边界”（用于 `histogram` 函数）时，返回 `true`。
示例	`is_histogram_other_bin('')`
结果	`true`

`md5(string)`

描述	以 `VARCHAR` 形式返回 `string` 的 MD5 哈希值。
示例	`md5('abc')`
结果	`900150983cd24fb0d6963f7d28e17f72`

`md5_number(string)`

描述	以 `UHUGEINT` 形式返回 `string` 的 MD5 哈希值。
示例	`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_literal)`

描述	表函数，解析并执行 `query_string_literal` 中定义的查询。只允许字面字符串。警告：此函数允许调用任意查询，可能更改数据库状态。
示例	`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` 值。如果当前事务尚未分配标识符，则会分配一个新的。
示例	`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 值中提取时间戳。
示例	`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'`

关于此页面

本文中