元命令参考

\copyright

显示GaussDB的版本和版权信息。

-

\g [FILE] or ;

执行查询（并将结果发送到文件或管道）。

-

\h(\help) [NAME]

给出指定SQL语句的语法帮助。

如果没有给出NAME，gsql将列出可获得帮助的所有命令。如果NAME是一个星号（*），则显示所有SQL语句的语法帮助。

\parallel [on [num]|off]

控制并发执行开关。

• on：打开控制并发执行开关，且最大并发数为num。num的默认值为1024。
• off：关闭控制并发执行开关。

-

\q

退出gsql程序。在一个脚本文件里，只在脚本终止时执行。

-

delimiter

delimiter命令用来为客户端设置一个分隔符。当用户设置分隔符后，gsql客户端识别到分隔符时，会立即将SQL语句发送到服务端执行，但是服务端仍然将“;”看作SQL语句分隔符，并相应的处理SQL语句。

SQL语句之间分隔符默认值为“;”。

设置的分隔符的级别是会话级别的，当切换数据库时分隔符会设置为默认值“;”。

• delimiter符号目前不是自由设定的，结束符范围有限制，目前接受大小写字母组合或特殊字符组合（~/!/@/#/^/&/`/?/+/-/*//（除号）/%/</>/=），其中常见的用法是“//”。
• 符号组合中尽量使用无歧义符号组合，特殊符号组合（注释符：“\*”、“--”，以加号“+”或减号“-”结尾的符号组合）目前不支持用于delimiter命名。
• delimiter长度范围为0~15字符。
• 用户如果想使用其他字符组合例如“adbc $$”，可以使用引号包含，例如delimiter "adbc $$"，但使用时也需要使用引号包含，例如：select 1"adbc $$"。

\e [FILE] [LINE]

使用外部编辑器编辑查询缓冲区（或者文件）。

\ef [FUNCNAME [LINE]]

使用外部编辑器编辑函数定义。如果指定了LINE（即行号），则光标会指到函数体的指定行。

\p

打印当前查询缓冲区到标准输出。

\r

重置（或清空）查询缓冲区。

\w FILE

将当前查询缓冲区输出到文件。

\copy { table [ ( column_list ) ] | ( query ) } { from | to } { filename | stdin | stdout | pstdin | pstdout } [copy parameter][parallel integer]

在任何gsql客户端登录数据库成功后可以执行导入导出数据，这是一个运行SQL COPY命令的操作，但不是读取或写入指定文件的服务器，而是读取或写入文件，并在服务器和本地文件系统之间路由数据。这意味着文件的可访问性和权限是本地用户的权限，而不是服务器的权限，并且不需要数据库初始化用户权限。

\echo [STRING]

把字符串写到标准输出。

prompt [STRING]

把字符串写到标准输出（等同于\echo）。

\i FILE

从文件FILE中读取内容，并将其当作输入，执行查询。

\i+ FILE KEY

执行加密文件中的命令。

\ir FILE

和\i类似，只是相对于存放当前脚本的路径。

\ir+ FILE KEY

和\i+类似，只是相对于存放当前脚本的路径。

\o [FILE]

把所有的查询结果发送到文件里。

\qecho [STRING]

把字符串写到查询结果输出流里。

\d[S+]

列出当前search_path中模式下所有的表、视图和序列。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。

-

列出当前search_path中模式下所有的表、视图和序列。

1

gaussdb=# \d

\d[S+] NAME

列出指定表、视图和索引的结构。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。

-

假设存在表a，列出指定表a的结构。

1

gaussdb=# \dtable+ a

\d+ [PATTERN]

列出所有表、视图和索引。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。如果声明了PATTERN，只显示名称匹配PATTERN的表、视图和索引。

-

列出所有名称以f开头的表、视图和索引。

1

gaussdb=# \d+ f*

\da[S] [PATTERN]

列出所有可用的聚集函数，以及它们操作的数据类型和返回值类型。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。如果声明了PATTERN，只显示名称匹配PATTERN的聚集函数。

-

列出所有名称以f开头可用的聚集函数，以及它们操作的数据类型和返回值类型。

1

gaussdb=# \da f*

\db[+] [PATTERN]

列出所有可用的表空间。如果声明了PATTERN，只显示名称匹配PATTERN的表空间。

-

列出所有名称以p开头的可用表空间。

1

gaussdb=# \db p*

\dc[S+] [PATTERN]

列出所有字符集之间的可用转换。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。如果声明了PATTERN，只显示名称匹配PATTERN的转换。

-

列出所有字符集之间的可用转换。

1

gaussdb=# \dc *

\dC[+] [PATTERN]

列出所有类型转换。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。如果声明了PATTERN，只显示名称匹配PATTERN的转换。

PATTERN需要使用实际类型名，不能使用别名。

列出所有名称以c开头的类型转换。

1

gaussdb=# \dC c*

\dd[S] [PATTERN]

显示所有可视对象。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。如果声明了PATTERN，只显示名称匹配的对象。对象包括：聚集、函数、操作符、类型、关系（表、视图、索引、序列、大对象）、规则。

-

列出所有可视对象。

1

gaussdb=# \dd

\ddp [PATTERN]

显示所有默认的使用权限。如果指定了PATTERN，只显示名称匹配PATTERN的使用权限。

-

列出所有默认的使用权限。

1

gaussdb=# \ddp

\dD[S+] [PATTERN]

列出所有可用域。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。如果声明了PATTERN，只显示名称匹配PATTERN的域。

-

列出所有可用域。

1

gaussdb=# \dD

\det[+] [PATTERN]

列出所有的外部表。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。如果声明了PATTERN，只显示名称匹配PATTERN的表。

-

列出所有的外部表。

1

gaussdb=# \det

\des[+] [PATTERN]

列出所有的外部服务器。如果声明了PATTERN，只显示名称匹配PATTERN的服务器。

-

列出所有的外部服务器。

1

gaussdb=# \des

\deu[+] [PATTERN]

列出用户映射信息。如果声明了PATTERN，只显示名称匹配PATTERN的信息。

-

列出用户映射信息。

1

gaussdb=# \deu

\dew[+] [PATTERN]

列出封装的外部数据。如果声明了PATTERN，只显示名称匹配PATTERN的数据。

-

列出封装的外部数据。

1

gaussdb=# \dew

\df[antw][S+] [PATTERN]

列出所有可用函数，以及它们的参数和返回的数据类型。a代表聚集函数，n代表普通函数，t代表触发器，w代表窗口函数。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。如果声明了PATTERN，只显示名称匹配PATTERN的函数。

-

列出所有可用函数，以及它们的参数和返回的数据类型。

1

gaussdb=# \df

\dF[+] [PATTERN]

列出所有的文本搜索配置信息。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。如果声明了PATTERN，只显示名称匹配PATTERN的配置信息。

-

列出所有的文本搜索配置信息。

1

gaussdb=# \dF+

\dFd[+] [PATTERN]

列出所有的文本搜索字典。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。如果声明了PATTERN，只显示名称匹配PATTERN的字典。

-

列出所有的文本搜索字典。

1

gaussdb=# \dFd

\dFp[+] [PATTERN]

列出所有的文本搜索分析器。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。如果声明了PATTERN，只显示名称匹配PATTERN的分析器。

-

列出所有的文本搜索分析器。

1

gaussdb=# \dFp

\dFt[+] [PATTERN]

列出所有的文本搜索模板。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。如果声明了PATTERN，只显示名称匹配PATTERN的模板。

-

列出所有的文本搜索模板。

1

gaussdb=# \dFt

\dg[+] [PATTERN]

列出所有数据库角色。如果指定了PATTERN，只显示名称匹配PATTERN的角色。

-

列出名称为“j?e”所有数据库角色（“?”表示任一字符）。

1

gaussdb=# \dg j?e

\dl

\lo_list的别名，显示大对象的列表。

-

列出所有的大对象。

1

gaussdb=# \dl

\dL[S+] [PATTERN]

列出可用的程序语言。如果指定了PATTERN，只列出名称匹配PATTERN的语言。

-

列出可用的程序语言。

1

gaussdb=# \dL

\dm[S+] [PATTERN]

列出物化视图。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。如果指定了PATTERN，只列出名称匹配PATTERN的物化视图。

-

列出物化视图。

1

gaussdb=# \dm

\dn[S+] [PATTERN]

列出所有模式（名称空间）。如果向命令追加+，会列出每个模式相关的权限及描述。如果声明了PATTERN，只列出名称匹配PATTERN的模式名。缺省时，只列出用户创建的模式。

-

列出所有名称以d开头的模式以及相关信息。

1

gaussdb=# \dn+ d*

\do[S] [PATTERN]

列出所有可用的操作符，以及它们的操作数和返回的数据类型。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。如果声明了PATTERN，只列出名称匹配PATTERN的操作符。缺省时，只列出用户创建的操作符。

-

列出所有可用的操作符，以及它们的操作数和返回的数据类型。

1

gaussdb=# \do

\dO[S+] [PATTERN]

列出排序规则。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。如果声明了PATTERN，只列出名称匹配PATTERN的规则。缺省时，只列出用户创建的规则。

-

列出排序规则。

1

gaussdb=# \dO

\dp [PATTERN]

列出可用的表、视图以及相关的权限信息。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。如果指定了PATTERN，只列出名称匹配PATTERN的表、视图。

-

列出可用的表、视图以及相关的权限信息。

1

gaussdb=# \dp

\dp显示结果如下：

rolename=xxxx/yyyy  --赋予一个角色的权限

=xxxx/yyyy  --赋予public的权限 

xxxx表示赋予的权限，yyyy表示授予这个权限的角色。权限的参数说明请参见表5。

\drds [PATTERN1 [PATTERN2]]

列出所有修改过的配置参数。这些设置可以是针对角色的、针对数据库的或者同时针对两者的。PATTERN1和PATTERN2表示要列出的角色PATTERN和数据库PATTERN。如果声明了PATTERN，只列出名称匹配PATTERN的规则。缺省或指定*时，则会列出所有设置。

-

列出数据库所有修改过的配置参数。

1

gaussdb=# \drds * dbname

\dT[S+] [PATTERN]

列出所有的数据类型。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。如果指定了PATTERN，只列出名称匹配PATTERN的类型。

-

列出所有的数据类型。

1

gaussdb=# \dT

\du[+] [PATTERN]

列出所有数据库角色。如果指定了PATTERN，则只列出名称匹配PATTERN的角色。

-

列出所有数据库角色。

1

gaussdb=# \du

\dE[S+] [PATTERN]

\di[S+] [PATTERN]

\ds[S+] [PATTERN]

\dt[S+] [PATTERN]

\dv[S+] [PATTERN]

这一组命令，字母E、i、s、t和v分别代表着外部表、索引、序列、表和视图。可以以任意顺序指定其中一个或者它们的组合来列出这些对象。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。例如：\dit列出所有的索引和表。在命令名称后面追加+，则每一个对象的物理尺寸以及相关的描述也会被列出。如果指定了PATTERN，只列出名称匹配该PATTERN的对象。默认情况下只会显示用户创建的对象。通过PATTERN或者S修饰符可以把系统对象包括在内。

-

列出所有的索引和视图。

1

gaussdb=# \div

\dx[+] [PATTERN]

列出安装数据库的扩展信息。如果指定了PATTERN，则只列出名称匹配PATTERN的扩展信息。

-

列出安装数据库的扩展信息。

1

gaussdb=# \dx

\l[+]

列出服务器上所有数据库的名称、所有者、字符集编码以及使用权限。

-

列出服务器上所有数据库的名称、所有者、字符集编码以及使用权限。

1

gaussdb=# \l

\sf[+] FUNCNAME

显示函数的定义。

-

假设存在函数function_a和函数名带圆括号的函数func()name，列出函数的定义。

1
2
3

gaussdb=# \sf function_a
gaussdb=# \sf 
"func()name"(argtype1, argtype2)

\z [PATTERN]

列出数据库中所有表、视图和序列，以及它们相关的访问特权。如果给出任何PATTERN，则被当成一个正则表达式，只显示匹配的表、视图、序列。

-

列出数据库中所有表、视图和序列，以及它们相关的访问特权。

1

gaussdb=# \z

r

SELECT：允许对指定的表、视图读取数据。

w

UPDATE：允许对指定表更新字段。

a

INSERT：允许对指定表插入数据。

d

DELETE：允许删除指定表中的数据。

D

TRUNCATE：允许清理指定表中的数据。

x

REFERENCES：允许创建外键约束。

t

TRIGGER：允许在指定表上创建触发器。

X

EXECUTE：允许使用指定的函数，以及利用这些函数实现的操作符。

U

USAGE：

• 对于过程语言，允许用户在创建函数时，指定过程语言。
• 对于模式，允许访问包含在指定模式中的对象。
• 对于序列，允许使用nextval函数。

C

CREATE：

• 对于数据库，允许在该数据库里创建新的模式。
• 对于模式，允许在该模式中创建新的对象。
• 对于表空间，允许在其中创建表，以及允许创建数据库和模式的时候把该表空间指定为其缺省表空间。

c

CONNECT：允许用户连接到指定的数据库。

T

TEMPORARY：允许创建临时表。

A

ALTER：允许用户修改指定对象的属性。

P

DROP：允许用户删除指定的对象。

m

COMMENT：允许用户定义或修改指定对象的注释。

i

INDEX：允许用户在指定表上创建索引。

v

VACUUM：允许用户对指定的表执行ANALYZE和VACUUM操作。

*

授权以上权限。

\a

对齐模式和非对齐模式之间的切换。

-

\C [STRING]

为表输出设置标题，或者取消标题（如果没有参数）。

任意字符串或空。

\f [STRING]

指定在非对齐输出模式下，用于分隔字段的字符或字符串。

任意字符串。

\H

标准输出和HTML表格格式输出之间的切换。

-

\pset NAME [VALUE]

设置影响查询结果表输出的选项。

NAME的取值见表7。

\t [on|off]

切换输出的表格格式。

• on：只显示数据行，不显示列标题和行计数。
• off：显示完整的表格，包括列标题和行计数。

\T [STRING]

指定在使用HTML输出格式时放在table标签里的属性。如果参数为空，表示不设置。

-

\x [on|off|auto]

切换扩展行显示模式。

• on：启用扩展显示模式，每个字段单独一行显示。
• off：禁用扩展显示模式，使用标准表格显示。
• auto：根据查询结果的宽度自动选择是否使用扩展显示模式。

border

用于控制表格输出时的边框样式。

• 在HTML格式下，取值范围为大于0的整数。
• 在其他格式下，取值范围：
  • 0：无边框，表格输出时不显示任何边框线。
  • 1：内部边框，显示列之间的分隔线，但不显示表格的外边框。
  • 2：完整边框，显示外边框和内部分隔线。

expanded (或x)

在正常和扩展格式之间切换。

• on：启用扩展显示模式，每个字段单独一行显示。
• off：禁用扩展显示模式，使用标准表格显示。标准格式只对aligned和wrapped格式有意义。
• auto：根据查询结果的宽度自动选择是否使用扩展显示模式。

fieldsep

用于控制在非对齐输出模式下，各个字段之间的分隔符。

可以设置为任意字符串。常见的取值包括','、'\t'、'|'等，如果不设置该选项，默认使用空格作为字段分隔符。

fieldsep_zero

用于设置未对齐输出模式下的字段分隔符为ASCII NUL字符。

-

footer

用于设置查询结果的页脚。

• on：显示页脚信息。
• off：不显示页脚信息。

format

控制查询结果的输出格式。

• unaligned（u）：以未对齐的形式显示，字段之间使用当前的字段分隔符分隔。
• aligned（a）：以对齐的表格形式显示。
• wrapped（w）：与aligned类似，但会自动换行过长的值。
• html（h）：以HTML表格格式显示。
• latex（l）：以LaTeX表格格式显示。
• troff-ms（t）：以troff ms宏格式显示。

null

用于设置NULL值的显示方式。

任意字符串。如果不设置该选项，默认使用空白字符来代替NULL值。

numericlocale

用于控制数字输出格式时是否使用当前系统的区域设置。

• on：数字输出时会使用当前系统的区域设置进行格式化。例如，在英语环境下，数字1,000.00会显示为1,000.00，在德语环境下会显示为1.000,00。
• off：数字输出时不使用区域设置，而是使用标准的数字格式，如1000.00。

pager

控制查询和gsql帮助输出的分页器。如果设置了环境变量PAGER，输出将被指向到指定程序，否则使用系统缺省。

• on：当输出到终端且不适合屏幕显示时，使用分页器。
• off：不使用分页器。
• always：当输出到终端无论是否符合屏幕显示时，都使用分页器。

recordsep

用于设置未对齐输出模式下的记录分隔符。

可以设置为任意字符串。常见的取值包括换行符(\n)、回车符(\r)、回车换行符(\r\n)等。如果不设置该选项，默认使用换行符(\n)作为记录分隔符。

recordsep_zero

用于设置未对齐输出模式下的记录分隔符为ASCII NUL字符。

-

tableattr（或T）

声明放在HTML输出格式中HTML table标签的属性。注意：如果已经使用\pset border命令，这里无需再设置border。

例如，bgcolor=#FFFFFF等。如果没有给出value，则表示不设置表的属性。

title

用于设置查询结果的标题。

可以设置为任意字符串，如果不设置该选项，查询结果将不会显示任何标题。

tuples_only（或t）

在完全显示和只显示实际的表数据之间切换。完全显示将输出像列头、标题、各种脚注等信息。在tuples_only模式下，只显示实际的表数据。

-

feedback

在是否输出结果行数之间切换。

-

\c[onnect] [DBNAME|- USER|- HOST|- PORT|-]

连接到一个新的数据库。当数据库名称长度超过63个字节时，默认前63个字节有效，连接到前63个字节对应的数据库，但是gsql的命令提示符中显示的数据库对象名仍为截断前的名称。

-

\encoding [ENCODING]

设置客户端字符编码格式。

不带参数时，显示当前的编码格式。

\conninfo

输出当前连接的数据库的信息。

-

\cd [DIR]

切换当前的工作目录。

绝对路径或相对路径，且满足操作系统路径命名规则。

\setenv NAME [VALUE]

设置环境变量NAME为VALUE，如果没有给出VALUE值，则不设置环境变量。

-

\timing [on|off]

以毫秒为单位显示每条SQL语句的执行时间（不包括屏显打印时间）。

• on：表示打开显示。
• off：表示关闭显示。

\! [COMMAND]

用于执行操作系统的命令。如果不跟任何参数，\!会直接打开一个独立的shell供用户交互。

-

\prompt [TEXT] NAME

用于提示用户输入一个值，并将其存储在一个gsql变量中。TEXT表示提示用户输入的文本，NAME表示要将输入值存储的gsql变量。示例如下：

gaussdb=#  \prompt 'Enter area name: ' area
Enter area name: Asia
gaussdb=#  SELECT * FROM HR.areaS WHERE area_name = :'area';
area_id | area_name
---------+-----------
3 | Asia
(1 row)

\set [NAME [VALUE]]

设置内部变量NAME为VALUE，如果给出了多于一个值，变量取值为所有值的连接结果。如果没有给出第二个参数，只设置变量不设置值。

有一些常用变量被gsql特殊对待，它们是一些选项设置，通常所有特殊对待的变量都是由大写字母组成（可能还有数字和下划线）。

表11是一个所有特殊对待的变量列表。

\unset NAME

不设置（或删除）gsql变量名。

\set VERBOSITY value

该选项控制错误报告的冗余行。

• default：返回严重且主要的错误文本及其位置，还包括详细的错误细节、错误提示（可能会跨越多行）。
• verbose：返回所有的错误信息。
• terse：仅返回严重且主要的错误文本以及文本位置（一般适合于单行错误信息）。

\set ON_ERROR_STOP value

如果设置了这个变量，脚本处理将马上停止。如果该脚本是从另外一个脚本调用的，另外一个脚本也会按同样的方式停止。如果最外层的脚本不是从一次交互的gsql会话中调用的而是用-f选项调用的，gsql将返回错误代码3，以示这个情况与致命错误条件的区别（错误代码为1）。

• on：命令执行错误时会立即停止，在交互模式下，gsql会立即返回已执行命令的结果。
• off：命令执行错误时将会跳过错误继续执行。

\set AUTOCOMMIT [on|off]

控制当前gsql连接的自动提交行为。默认情况下，gsql连接处于自动提交模式，每个单独的语句都被隐式提交。如果基于性能或者其它方面考虑，关闭自动提交时，需要用户自己显式发出COMMIT命令来保证事务的提交。例如，在指定的业务SQL执行完之后发送COMMIT语句显式提交，特别是gsql客户端退出之前务必保证所有的事务已经提交。

• on：表示打开自动提交。
• off：表示关闭自动提交。

\lo_list

显示目前存储在该数据库里的所有GaussDB大对象和提供给大对象的注释。

\send_token

全密态功能，传输密钥到服务端缓存，只在开启内存解密逃生通道的情况下使用。

\st

全密态功能，传输密钥到服务端缓存，只在开启内存解密逃生通道的情况下使用。

\clear_token

全密态功能，销毁服务端缓存的密钥，只在开启内存解密逃生通道的情况下使用。

\ct

全密态功能，销毁服务端缓存的密钥，只在开启内存解密逃生通道的情况下使用。

\key_info KEY_INFO

在全密态数据库特性中，设置访问外部密钥管理者的参数。