DuckDB CLI 客户端提供点命令。要使用这些命令，请在行首输入一个点（.），紧接着输入您想要执行的命令名称。命令的其他参数应以空格分隔，放置在命令名称之后。如果参数中必须包含空格，可以使用单引号或双引号将该参数括起来。点命令必须在单行内输入，且点号前不能有空格。行尾无需分号。要查看可用命令，请使用 .help 命令。

点命令列表

使用 .help 命令

.help 文本可以通过传入字符串作为第一个参数进行过滤。

.help m

.maxrows COUNT           Sets the maximum number of rows for display (default: 40). Only for duckbox mode.
.maxwidth COUNT          Sets the maximum width in characters. 0 defaults to terminal width. Only for duckbox mode.
.mode MODE ?TABLE?       Set output mode

.output：将结果写入文件

默认情况下，DuckDB CLI 将结果发送到终端的标准输出。但是，可以使用 .output 或 .once 命令修改此行为。将所需的输出文件位置作为参数传入。.once 命令仅输出下一组结果，然后恢复为标准输出，而 .output 则会将所有后续输出重定向到该文件位置。请注意，每次结果都会覆盖该目标处的整个文件。要恢复为标准输出，请在不带文件参数的情况下输入 .output。

在此示例中，输出格式更改为 markdown，目标被指定为 Markdown 文件，然后 DuckDB 将 SQL 语句的输出写入该文件。随后通过不带参数的 .output 将输出恢复为标准输出。

.mode markdown
.output my_results.md
SELECT 'taking flight' AS output_column;
.output
SELECT 'back to the terminal' AS displayed_column;

文件 my_results.md 随后将包含

| output_column |
|---------------|
| taking flight |

终端随后将显示

|   displayed_column   |
|----------------------|
| back to the terminal |

一种常见的输出格式是 CSV（逗号分隔值）。DuckDB 支持将数据导出为 CSV 或 Parquet 的 SQL 语法，但如果需要，也可以使用 CLI 特有命令来写入 CSV。

.mode csv
.once my_output_file.csv
SELECT 1 AS col_1, 2 AS col_2
UNION ALL
SELECT 10 AS col1, 20 AS col_2;

文件 my_output_file.csv 随后将包含

col_1,col_2
1,2
10,20

通过向 .once 命令传递特殊选项（标志），查询结果也可以发送到临时文件并自动在用户的默认程序中打开。使用 -e 标志处理文本文件（在默认文本编辑器中打开），或使用 -x 标志处理 CSV 文件（在默认电子表格编辑器中打开）。这对于更详细地检查查询结果非常有用，特别是在结果集较大的情况下。.excel 命令等同于 .once -x。

.once -e
SELECT 'quack' AS hello;

结果随后会在系统的默认文本编辑器中打开，例如

提示：macOS 用户可以使用 pbcopy 将结果复制到剪贴板，方法是使用 .once 通过管道输出到 pbcopy：.once |pbcopy

将其与 .headers off 和 .mode lines 选项结合使用会特别有效。

查询数据库架构

所有 DuckDB 客户端都支持使用 SQL 查询数据库架构，但 CLI 具有额外的点命令，可以更轻松地理解数据库内容。.tables 命令将返回数据库中的表列表。它带有一个可选参数，可根据 LIKE 模式过滤结果。

CREATE TABLE swimmers AS SELECT 'duck' AS animal;
CREATE TABLE fliers AS SELECT 'duck' AS animal;
CREATE TABLE walkers AS SELECT 'duck' AS animal;
.tables

fliers    swimmers  walkers

例如，要仅过滤包含 l 的表，请使用 LIKE 模式 %l%。

.tables %l%

fliers   walkers

.schema 命令将显示用于定义数据库架构的所有 SQL 语句。

.schema

CREATE TABLE fliers (animal VARCHAR);
CREATE TABLE swimmers (animal VARCHAR);
CREATE TABLE walkers (animal VARCHAR);

进度条

DuckDB CLI 客户端的进度条支持通过组件进行自定义。

.progress_bar 命令支持 --add 和 --clear 参数，用于添加和移除组件。

有关具体用法的详细信息，请参见下方的示例。

配置进度条显示

要检查进度条是否已启用

SELECT * FROM duckdb_settings() WHERE name = 'enable_progress_bar';

要检查显示进度条之前查询需要经过的当前最短时间（以毫秒为单位）

SELECT * FROM duckdb_settings() WHERE name = 'progress_bar_time';

要将显示进度条的最短时间设置为 100 毫秒

SET progress_bar_time = 100;

将该进度条组件设置为红色文本，并在进度条上显示当前时间

.progress_bar --add "{align:right}{min_size:20}{color:red}Time: {sql:select (current_time::varchar).split('.')[1]}{color:reset} "

.progress_bar --add 命令是累加的，执行多次 --add 调用将在进度条上堆叠更多组件。

将该进度条组件设置为蓝色文本，并在进度条上显示文件缓存 RAM 使用情况

.progress_bar --add "{align:right}{min_size:20}{color:blue}External Cache Usage: {sql:select format_bytes(memory_usage_bytes) from duckdb_memory() where tag='EXTERNAL_FILE_CACHE'}{color:reset};

重置所有现有的进度条组件

.progress_bar --clear

语法高亮

DuckDB CLI 客户端有一个用于 SQL 查询的语法高亮器，另一个用于 duckbox 格式的结果表。

配置查询语法高亮

默认情况下，shell 包含对语法高亮的支持。CLI 的语法高亮可以使用以下命令进行配置。

关闭高亮显示

.highlight off

开启高亮显示

.highlight on

配置用于高亮显示常量的颜色

.constant [red|green|yellow|blue|magenta|cyan|white|brightblack|brightred|brightgreen|brightyellow|brightblue|brightmagenta|brightcyan|brightwhite]

.constantcode terminal_code

例如

.constantcode 033[31m

配置用于高亮显示关键字的颜色

.keyword [red|green|yellow|blue|magenta|cyan|white|brightblack|brightred|brightgreen|brightyellow|brightblue|brightmagenta|brightcyan|brightwhite]

.keywordcode terminal_code

例如

.keywordcode 033[31m

配置结果语法高亮

默认情况下，结果高亮会进行一些小修改

• 加粗列名。
• NULL 值显示为灰色。
• 布局元素显示为灰色。

每个组件的高亮显示可以使用 .highlight_colors 命令进行自定义。例如

.highlight_colors layout red
.highlight_colors column_type yellow
.highlight_colors column_name yellow bold_underline
.highlight_colors numeric_value cyan underline
.highlight_colors temporal_value red bold
.highlight_colors string_value green bold
.highlight_colors footer gray

可以使用 .highlight_results off 禁用结果高亮。

简写

DuckDB 的 CLI 允许使用点命令的简写。一旦字符序列可以明确补全为某个点命令或参数，CLI 就会（静默地）自动补全它们。例如

.mo ma

等同于

.mode markdown

提示：避免在 SQL 脚本中使用简写，以提高可读性并确保脚本的未来兼容性。

从 CSV 导入数据

弃用：此功能仅出于兼容性原因包含在内，未来可能会被移除。请使用 read_csv 函数或 COPY 语句来加载 CSV 文件。

DuckDB 支持直接查询或导入 CSV 文件的 SQL 语法，但如果需要，也可以使用 CLI 特有命令来导入 CSV。.import 命令接受两个参数，并支持多个选项。第一个参数是 CSV 文件的路径，第二个是待创建的 DuckDB 表名。由于 DuckDB 比 SQLite（DuckDB CLI 基于此构建）需要更严格的类型定义，因此在执行 .import 命令之前，必须先创建目标表。要自动检测架构并从 CSV 创建表，请参见导入文档中的 read_csv 示例。

在此示例中，通过切换到 CSV 模式并设置输出文件位置来生成 CSV 文件

.mode csv
.output import_example.csv
SELECT 1 AS col_1, 2 AS col_2 UNION ALL SELECT 10 AS col1, 20 AS col_2;

CSV 编写完成后，可以使用所需的架构创建表并导入 CSV。输出重置回终端，以避免继续编辑上述指定的输出文件。--skip N 选项用于忽略第一行数据，因为它是一个表头行，且表已经以正确的列名创建完毕。

.mode csv
.output
CREATE TABLE test_table (col_1 INTEGER, col_2 INTEGER);
.import import_example.csv test_table --skip 1

请注意，.import 命令在确定要导入数据的结构时会利用当前的 .mode 和 .separator 设置。--csv 选项可用于覆盖该行为。

.import import_example.csv test_table --skip 1 --csv