# 元命令参考 介绍使用DWS数据库命令行交互工具登录数据库后，gsql所提供的元命令。所谓元命令就是在gsql里输入的任何以不带引号的反斜杠开头的命令。 #### 注意事项 - 一个gsql元命令的格式是反斜杠后面紧跟一个动词，然后是任意参数。参数命令动词和其他参数以任意个空白字符分隔。 - 要在参数里面包含空白，必须用单引号把它引起来。要在这样的参数里包含单引号，可以在前面加一个反斜杠。任何包含在单引号里的内容都会被进一步进行类似C语言的替换：\\n（新行）、\\t（制表符）、\\b（退格）、\\r（回车）、\\f（换页）、\\digits（八进制表示的字符）、\\xdigits（十六进制表示的字符）。 - 用""包围的内容被当做一个命令行传入shell。该命令的输出（删除了结尾的新行）被当做参数值。 - 如果不带引号的参数以冒号（:）开头，它会被当做一个gsql变量，并且该变量的值最终会成为真正的参数值。 - 有些命令以一个SQL标识的名称（比如一个表）为参数。这些参数遵循SQL语法关于双引号的规则：不带双引号的标识强制转换成小写，而双引号保护字母不进行大小写转换，并且允许在标识符中使用空白。在双引号中，成对的双引号在结果名字中分析成一个双引号。比如，FOO"BAR"BAZ解析成fooBARbaz；而"A weird"" name"解析成A weird" name。 - 对参数的分析在遇到另一个不带引号的反斜杠时停止。这里会认为是一个新的元命令的开始。特殊的双反斜杠序列（\\\\）标识参数的结尾并将继续分析后面的SQL语句（如果存在）。这样SQL和gsql命令可以自由地在一行里面混合。但是在任何情况下，一条元命令的参数不能延续超过行尾。 #### 元命令 元命令的详细说明请参见[表1]、[表2]、[表3]、[表4]、[表6]、[表8]、[表9]、[表10]和[表12]。 ![](https://support.huaweicloud.com/tg-dws/public_sys-resources/notice_3.0-zh-cn.png) 以下命令中所提到的FILE代表文件路径。此路径可以是绝对路径（如/home/gauss/file.txt），也可以是相对路径（file.txt，file.txt会默认在用户执行gsql命令所在的路径下创建）。 表1一般的元命令 | 参数 | 参数说明 | 取值范围 | |:---|:---|:---| | \\copyright | 显示DWS的版本和版权信息。 | - | | \\g \[FILE\] or ; | 执行查询（并将结果发送到文件或管道）。 | - | | \\h(\\help) \[NAME\] | 给出指定SQL语句的语法帮助。 | 如果没有给出NAME，gsql将列出可获得帮助的所有命令。如果NAME是一个星号（\*），则显示所有SQL语句的语法帮助。 | | \\parallel \[on \[num\]\|off\] | 控制并发执行开关。 - on：打开控制并发执行开关，且最大并发数为num。 - off：关闭控制并发执行开关。 说明： - 不支持事务中开启并发执行以及并发中开启事务。 - 不支持\\d这类元命令的并发。 - 并发select返回结果混乱问题，此为客户可接受，core、进程停止响应不可接受。 - 不推荐在并发中使用set语句，否则导致结果与预期不一致。 - 不支持在\\parallel中使用DISCARD命令。 - 不支持创建临时表！如需使用临时表，需要在开启parallel之前创建好，并在parallel内部使用。parallel内部不允许创建临时表。 - \\parallel执行时最多会启动num个独立的gsql进程连接服务器。 - \\parallel中所有作业的持续时间不能超过session_timeout，否则可能会导致并发执行过程中断连。 - \\parallel不支持对VOLATILE/GLOBAL全局临时表进行操作。 | num的默认值：1024。 须知： - 服务器能接受的最大连接数受max_connection及当前已有连接数限制。 - 设置num时请考虑服务器当前可接受的实际连接数合理指定。 | | \\q \[value\] | 退出gsql程序。在一个脚本文件里，只在脚本终止的时候执行。退出码可由value值决定。 | - | 表2查询缓存区元命令 | 参数 | 参数说明 | |:---|:---| | \\e \[FILE\] \[LINE\] | 使用外部编辑器编辑查询缓冲区（或者文件）。 | | \\ef \[FUNCNAME \[LINE\]\] | 使用外部编辑器编辑函数定义。如果指定了LINE（即行号），则光标会指到函数体的指定行。 | | \\p | 打印当前查询缓冲区到标准输出。 | | \\r | 重置（或清空）查询缓冲区。 | | \\w FILE | 将当前查询缓冲区输出到文件。 | 表3输入/输出元命令 | 参数 | 参数说明 | |:---|:---| | \\copy { table \[ ( column_list ) \] \| ( query ) } { from \| to } { filename \| stdin \| stdout \| pstdin \| pstdout } \[ with \] \[ binary \] \[ oids \] \[ delimiter \[ as \] 'character' \] \[ null \[ as \] 'string' \] \[ csv \[ header \] \[ quote \[ as \] 'character' \] \[ escape \[ as \] 'character' \] \[ force quote column_list \| \* \] \[ force not null column_list \] \] | 在任何gsql客户端登录数据库成功后可以执行导入导出数据， 这是一个运行SQL COPY命令的操作，但不是读取或写入指定文件的服务器，而是读取或写入文件，并在服务器和本地文件系统之间路由数据。 这意味着文件的可访问性和权限是本地用户的权限，而不是服务器的权限，并且不需要数据库初始化用户权限。 说明： \\COPY只适合小批量，格式良好的数据导入，容错能力较差。导入数据应优先选择GDS或COPY。 | | \\echo \[STRING\] | 把字符串写到标准输出。 | | \\i FILE | 从文件FILE中读取内容，并将其当作输入，执行查询。 | | \\i+ FILE KEY | 执行加密文件中的命令。 | | \\ir FILE | 和\\i类似，只是相对于存放当前脚本的路径。 | | \\ir+ FILE KEY | 和\\i+类似，只是相对于存放当前脚本的路径。 | | \\o \[FILE\] | 把所有的查询结果发送到文件里。 | | \\qecho \[STRING\] | 把字符串写到查询结果输出流里。 | ![](https://support.huaweicloud.com/tg-dws/public_sys-resources/note_3.0-zh-cn.png) [表4]中的选项S表示显示系统对象，+表示显示对象附加的描述信息。[PATTERN]用来指定要被显示的对象名称。 表4显示信息元命令 | 参数 | 参数说明 | 取值范围 | 示例 | |:---|:---|:---|:---| | \\d\[S+\] | 列出当前search_path中模式下所有的表、视图和序列。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。 | - | 列出当前search_path中模式下所有的表、视图和序列。 ``` \d ``` | | \\d\[S+\] NAME | 列出指定表结构、视图结构和索引的结构。 | - | 假设存在表a，列出指定表a的表结构。 ``` \dtable+ a ``` | | \\d+ \[PATTERN\] | 列出所有表、视图和索引。 | 如果声明了PATTERN，只显示名字匹配PATTERN的表、视图和索引。 | 列出所有名称以f开头的表、视图和索引。 ``` \d+ f* ``` | | \\da\[S\] \[PATTERN\] | 列出所有可用的聚集函数，以及它们操作的数据类型和返回值类型。 | 如果声明了PATTERN，只显示名字匹配PATTERN的聚集函数。 | 列出所有名称以f开头可用的聚集函数，以及它们操作的数据类型和返回值类型。 ``` \da f* ``` | | \\db\[+\] \[PATTERN\] | 列出所有可用的表空间。 | 如果声明了PATTERN，只显示名字匹配PATTERN的表空间。 | 列出所有名称以p开头的可用表空间。 ``` \db p* ``` | | \\dc\[S+\] \[PATTERN\] | 列出所有字符集之间的可用转换。 | 如果声明了PATTERN，只显示名字匹配PATTERN的转换。 | 列出所有字符集之间的可用转换。 ``` \dc * ``` | | \\dC\[+\] \[PATTERN\] | 列出所有类型转换。 | 如果声明了PATTERN，只显示名字匹配PATTERN的转换。 | 列出所有名称以c开头的类型转换。 ``` \dC c* ``` | | \\dd\[S\] \[PATTERN\] | 显示所有匹配PATTERN的描述。 | 如果没有给出参数，则显示所有可视对象。"对象"包括：聚集、函数、操作符、类型、关系(表、视图、索引、序列、大对象)、规则。 | 列出所有可视对象。 ``` \dd ``` | | \\ddp \[PATTERN\] | 显示所有默认的使用权限。 | 如果指定了PATTERN，只显示名字匹配PATTERN的使用权限。 | 列出所有默认的使用权限。 ``` \ddp ``` | | \\dD\[S+\] \[PATTERN\] | 列出所有可用域。 | 如果声明了PATTERN，只显示名字匹配PATTERN的域。 | 列出所有可用域。 ``` \dD ``` | | \\ded\[+\] \[PATTERN\] | 列出所有的Data Source对象。 | 如果声明了PATTERN，只显示名字匹配PATTERN的对象。 | 列出所有的Data Source对象。 ``` \ded ``` | | \\det\[+\] \[PATTERN\] | 列出所有的外部表。 | 如果声明了PATTERN，只显示名字匹配PATTERN的表。 | 列出所有的外部表。 ``` \det ``` | | \\des\[+\] \[PATTERN\] | 列出所有的外部服务器。 | 如果声明了PATTERN，只显示名字匹配PATTERN的服务器。 | 列出所有的外部服务器。 ``` \des ``` | | \\deu\[+\] \[PATTERN\] | 列出用户映射信息。 | 如果声明了PATTERN，只显示名字匹配PATTERN的信息。 | 列出用户映射信息。 ``` \deu ``` | | \\dew\[+\] \[PATTERN\] | 列出封装的外部数据。 | 如果声明了PATTERN，只显示名字匹配PATTERN的数据。 | 列出封装的外部数据。 ``` \dew ``` | | \\df\[antw\]\[S+\] \[PATTERN\] | 列出所有可用函数，以及它们的参数和返回的数据类型。a代表聚集函数，n代表普通函数，t代表触发器，w代表窗口函数。 | 如果声明了PATTERN，只显示名字匹配PATTERN的函数。 | 列出所有可用函数，以及它们的参数和返回的数据类型。 ``` \df ``` | | \\dF\[+\] \[PATTERN\] | 列出所有的文本搜索配置信息。 | 如果声明了PATTERN，只显示名字匹配PATTERN的配置信息。 | 列出所有的文本搜索配置信息。 ``` \dF+ ``` | | \\dFd\[+\] \[PATTERN\] | 列出所有的文本搜索字典。 | 如果声明了PATTERN，只显示名字匹配PATTERN的字典。 | 列出所有的文本搜索字典。 ``` \dFd ``` | | \\dFp\[+\] \[PATTERN\] | 列出所有的文本搜索分析器。 | 如果声明了PATTERN，只显示名字匹配PATTERN的分析器。 | 列出所有的文本搜索分析器。 ``` \dFp ``` | | \\dFt\[+\] \[PATTERN\] | 列出所有的文本搜索模板。 | 如果声明了PATTERN，只显示名字匹配PATTERN的模板。 | 列出所有的文本搜索模板。 ``` \dFt ``` | | \\dg\[+\] \[PATTERN\] | 列出所有数据库角色。 说明： 因为用户和群组的概念被统一为角色，所以这个命令等价于\\du。为了和以前兼容，所以保留两个命令。 | 如果指定了PATTERN，只显示名字匹配PATTERN的角色。 | 列出名字为'j_e'所有数据库角色。 ``` \dg j?e ``` | | \\dl | \\lo_list的别名，显示一个大对象的列表。 | - | 列出所有的大对象。 ``` \dl ``` | | \\dL\[S+\] \[PATTERN\] | 列出可用的程序语言。 | 如果指定了PATTERN，只列出名字匹配PATTERN的语言。 | 列出可用的程序语言。 ``` \dL ``` | | \\dn\[S+\] \[PATTERN\] | 列出所有的模式（名字空间）。 | 如果声明了PATTERN，只列出名字匹配PATTERN的模式名。缺省时，只列出用户创建的模式。 | 列出所有名称以d开头的模式以及相关信息。 ``` \dn+ d* ``` | | \\do\[S\] \[PATTERN\] | 列出所有可用的操作符，以及它们的操作数和返回的数据类型。 | 如果声明了PATTERN，只列出名字匹配PATTERN的操作符。缺省时，只列出用户创建的操作符。 | 列出所有可用的操作符，以及它们的操作数和返回的数据类型。 ``` \do ``` | | \\dO\[S+\] \[PATTERN\] | 列出排序规则。 | 如果声明了PATTERN，只列出名字匹配PATTERN的规则。缺省时，只列出用户创建的排序规则。 | 列出排序规则。 ``` \dO ``` | | \\dp \[PATTERN\] | 列出一列可用的表、视图以及相关的权限信息。 \\dp显示结果如下： ``` rolename=xxxx/yyyy --赋予一个角色的权限 ``` ``` =xxxx/yyyy --赋予public的权限 ``` xxxx表示赋予的权限，yyyy表示授予这个权限的角色。权限的参数说明请参见[表5]。 | 如果指定了PATTERN，只列出名字匹配PATTERN的表、视图。 | 列出一列可用的表、视图以及相关的权限信息。 ``` \dp ``` | | \\drds \[PATTERN1 \[PATTERN2\]\] | 列出所有修改过的配置参数。这些设置可以是针对角色的、针对数据库的或者同时针对两者的。PATTERN1和PATTERN2表示要列出的角色PATTERN和数据库PATTERN。 | 如果声明了PATTERN，只列出名字匹配PATTERN的规则。缺省或指定\*时，则会列出所有设置。 | 列出数据库所有修改过的配置参数。 ``` \drds * ``` | | \\dRp\[+\] \[PATTERN\] | 列出所有的发布。该元命令仅8.2.0.100及以上集群版本支持。 | 如果指定了PATTERN，只列出名字匹配PATTERN的发布。 | 列出所有的发布。 ``` \dRp ``` | | \\dRs\[+\] \[PATTERN\] | 列出所有的订阅。该元命令仅8.2.0.100及以上集群版本支持。 | 如果指定了PATTERN，只列出名字匹配PATTERN的订阅。 | 列出所有的订阅。 ``` \dRs ``` | | \\dT\[S+\] \[PATTERN\] | 列出所有的数据类型。 | 如果指定了PATTERN，只列出名字匹配PATTERN的类型。 | 列出所有的数据类型。 ``` \dT ``` | | \\du\[+\] \[PATTERN\] | 列出所有数据库角色。 说明： 因为用户和群组的概念被统一为角色，所以这个命令等价于\\dg。为了和以前兼容，所以保留两个命令。 | 如果指定了PATTERN，则只列出名字匹配PATTERN的角色。 | 列出所有数据库角色。 ``` \du ``` | | \\dE\[S+\] \[PATTERN\] \\di\[S+\] \[PATTERN\] \\ds\[S+\] \[PATTERN\] \\dt\[S+\] \[PATTERN\] \\dv\[S+\] \[PATTERN\] | 这一组命令，字母E，i，s，t和v分别代表着外部表，索引，序列，表和视图。可以以任意顺序指定其中一个或者它们的组合来列出这些对象。例如：\\dit列出所有的索引和表。在命令名称后面追加+，则每一个对象的物理尺寸以及相关的描述也会被列出。 说明： 本版本暂时不支持序列。 | 如果指定了PATTERN，只列出名称匹配该PATTERN的对象。默认情况下只会显示用户创建的对象。通过PATTERN或者S修饰符可以把系统对象包括在内。 | 列出所有的索引和视图。 ``` \div ``` | | \\dx\[+\] \[PATTERN\] | 列出安装数据库的扩展信息。 | 如果指定了PATTERN，则只列出名字匹配PATTERN的扩展信息。 | 列出安装数据库的扩展信息。 ``` \dx ``` | | \\l\[+\] | 列出服务器上所有数据库的名字、所有者、字符集编码以及使用权限。 | - | 列出服务器上所有数据库的名字、所有者、字符集编码以及使用权限。 ``` \l ``` | | \\sf\[+\] FUNCNAME | 显示函数的定义。 说明： 对于带圆括号的函数名，需要在函数名两端添加双引号，并且在双引号后面加上参数类型列表。参数类型列表两端添加圆括号。 | - | 假设存在函数function_a和函数名带圆括号的函数func()name，列出函数的定义。 ``` \sf function_a \sf "func()name"(argtype1, argtype2) ``` | | \\z \[PATTERN\] | 列出数据库中所有表、视图和序列，以及它们相关的访问特权。 | 如果给出任何pattern ，则被当成一个正则表达式，只显示匹配的表、视图、序列。 | 列出数据库中所有表、视图和序列，以及它们相关的访问特权。 ``` \z ``` | 表5权限的参数说明 | 参数 | 参数说明 | |:---|:---| | 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 | ANALYZE\|ANALYSE：允许分析表。 | | L | ALTER：允许修改表、模式或函数。 | | P | DROP：允许删除表、模式或函数。 | | v | VACUUM：允许对表执行VACUUM。 | | arwdDxtA, vLP | ALL PRIVILEGES：一次性给指定用户/角色赋予所有可赋予的权限。 vLP权限组为8.1.3及以上集群版本中新增表级权限ALTER/DROP/VACUUM，新增schema权限ALTER/DROP。 | | \* | 给前面权限的授权选项。 | 表6格式化元命令 | 参数 | 参数说明 | |:---|:---| | \\a | 对齐模式和非对齐模式之间的切换。 | | \\C \[STRING\] | 把正在打印的表的标题设置为一个查询的结果或者取消这样的设置。 | | \\f \[STRING\] | 对于不对齐的查询输出，显示或者设置域分隔符。 | | \\H | - 若当前模式为文本格式，则切换为HTML输出格式。 - 若当前模式为HTML格式，则切换回文本格式。 | | \\pset NAME \[VALUE\] | 设置影响查询结果表输出的选项。NAME的取值见[表7]。 | | \\t \[on\|off\] | 切换是否显示字段名的信息和行计数脚注。 | | \\T \[STRING\] | 指定在使用HTML输出格式时放在table标签里的属性。如果参数为空，不设置。 | | \\x \[on\|off\|auto\] | 切换扩展行格式。 | 表7可调节的打印选项 | 选项 | 选项说明 | 取值范围 | |:---|:---|:---| | border | value必须是一个数字。通常这个数字越大，表的边界就越宽，线就越多，但是这个取决于特定的格式。 | - 在HTML格式下，取值范围为大于0的整数。 - 在其他格式下，取值范围： - 0：无边框 - 1：内部分隔线 - 2：台架 | | expanded (或x) | 在正常和扩展格式之间切换。 | - 当打开扩展格式时，查询结果用两列显示，字段名称在左、数据在右。这个模式在数据无法放进通常的"水平"模式的屏幕时很有用。 - 在正常格式下，当查询输出的格式比屏幕宽时，用扩展格式。正常格式只对aligned和wrapped格式有用。 | | fieldsep | 声明域分隔符来实现非对齐输出。这样就可以创建其他程序希望的制表符或逗号分隔的输出。要设置制表符域分隔符，键入\\pset fieldsep '\\t'。缺省域分隔符是 '\|' (竖条符)。 | - | | fieldsep_zero | 声明域分隔符来实现非对齐输出到零字节。 | - | | footer | 用来切换脚注。 | - | | format | 设置输出格式。允许使用唯一缩写（这意味着一个字母就够了）。 | 取值范围： - unaligned：写一行的所有列在一条直线上，当前活动字段分隔符分隔。 - aligned：此格式是标准的，可读性最好的文本输出。 - wrapped：类似aligned，但是包装跨行的宽数据值，使其适应目标字段的宽度输出。 - html：把表输出为可用于文档里的对应标记语言。输出不是完整的文档。 - latex：把表输出为可用于文档里的对应标记语言。输出不是完整的文档。 - troff-ms：把表输出为可用于文档里的对应标记语言。输出不是完整的文档。 | | null | 打印一个字符串，用来代替一个null值。 | 缺省是什么都不打印，这样很容易和空字符串混淆。 | | numericlocale | 切换分隔小数点左边的数值的区域相关的分组符号。 | - on：显示指定的分隔符。 - off：不显示分隔符。 忽略此参数，显示默认的分隔符。 | | pager | 控制查询和gsql帮助输出的分页器。如果设置了环境变量PAGER，输出将被指向到指定程序，否则使用系统缺省。 | - on：当输出到终端且不适合屏幕显示时，使用分页器。 - off：不使用分页器。 - always：当输出到终端无论是否符合屏幕显示时，都使用分页器。 | | recordsep | 声明在非对齐输出格式时的记录分隔符。 | - | | recordsep_zero | 声明在非对齐输出到零字节时的记录分隔符。 | - | | tableattr（或T） | 声明放在html输出格式中HTML table标签的属性（例如：cellpadding或bgcolor）。注意：这里可能不需要声明border，因为已经在\\pset border里用过了。如果没有给出value，则不设置表的属性。 | - | | title | 为随后打印的表设置标题。这个可以用于给输出一个描述性标签。如果没有给出value，不设置标题。 | - | | tuples_only （或者t） | 在完全显示和只显示实际的表数据之间切换。完全显示将输出像列头、标题、各种脚注等信息。在tuples_only模式下，只显示实际的表数据。 | - | 表8连接元命令 | 参数 | 参数说明 | 取值范围 | |:---|:---|:---| | \\\[connect\] \[DBNAME\|- USER\|- HOST\|- PORT\|-\] | 连接到一个新的数据库（当前数据库为gaussdb）。当数据库名称长度超过63个字节时，默认前63个字节有效，连接到前63个字节对应的数据库，但是gsql的命令提示符中显示的数据库对象名仍为截断前的名称。 说明： 重新建立连接时，如果切换数据库登录用户，将可能会出现交互式输入，要求输入新用户的连接密码。该密码最长长度为999字节，受限于GUC参数password max length的最大值。 | - | | \\encoding \[ENCODING\] | 设置客户端字符编码格式。 | 不带参数时，显示当前的编码格式。 | | \\conninfo | 输出当前连接的数据库的信息。 | - | 表9操作系统元命令 | 参数 | 参数说明 | 取值范围 | |:---|:---|:---| | \\cd \[DIR\] | 切换当前的工作目录。 | 绝对路径或相对路径，且满足操作系统路径命名规则。 | | \\setenv NAME \[VALUE\] | 设置环境变量NAME为VALUE，如果没有给出VALUE值，则不设置环境变量。 | - | | \\timing \[on\|off\] | 以毫秒为单位显示每条SQL语句的执行时间。 | - on表示打开显示。 - off表示关闭显示。 | | \\! \[COMMAND\] | 返回到一个单独的Unix shell或者执行Unix命令COMMAND。 | - | 表10变量元命令 | 参数 | 参数说明 | |:---|:---| | \\prompt \[TEXT\] NAME | 提示用户用文本格式来指定变量名字。 | | \\set \[NAME \[VALUE\]\] | 设置内部变量NAME为VALUE或者如果给出了多于一个值，设置为所有这些值的连接结果。如果没有给出第二个参数，只设变量不设值。 有一些常用变量被gsql特殊对待，它们是一些选项设置，通常所有特殊对待的变量都是由大写字母组成(可能还有数字和下划线)。 [表11]是一个所有特殊对待的变量列表。 | | \\set-multi NAME \[VALUE\] \\end-multi | 设置内部变量NAME为VALUE，VALUE可以由多行字符串组成。\\set-multi使用时，第二个参数必须给出。可参考表下面的\\set-multi元命令使用示例。 说明： \\set-multi 和\\end-multi中出现的元命令会被忽略。 | | \\unset NAME | 不设置（或删除）gsql变量名。 | **\\set-multi元命令使用示例** 示例文件test.sql： ``` \set-multi multi_line_var select id,name from student; \end-multi \echo multi_line_var is "${multi_line_var}" \echo ------------------------- \echo result is ${multi_line_var} ``` gsql -d gaussdb -p 25308 --dynamic-param -f test.sql 执行结果： ``` multi_line_var is "select id,name from student; " ------------------------- result is id | name ----+------- 1 | Jack 2 | Tom 3 | Jerry 4 | Danny (4 rows) ``` 通过\\set-multi \\end-multi设置变量multi_line_var为一个SQL语句，并在后面通过动态变量解析获得这个变量。 示例文件test.sql： ``` \set-multi multi_line_var select 1 as id; select 2 as id; \end-multi \echo multi_line_var is "${multi_line_var}" \echo ------------------------- \echo result is ${multi_line_var} ``` gsql -d -p 25308 --dynamic-param -f test.sql 执行结果： ``` multi_line_var is "select 1 as id; select 2 as id;" ------------------------- result is id ---- 1 (1 row) id ---- 2 (1 row) ``` 通过\\set-multi \\end-multi设置变量multi_line_var为两个SQL语句，并在后面通过动态变量解析获得这个变量。因为变量中的内容以";"结尾，gsql发送SQL语句并获得打印执行结果。 表11\\set常用命令 | 名称 | 命令说明 | 取值范围 | |:---|:---|:---| | \\set VERBOSITY value | 这个选项可以设置为值default， verbose，terse之一以控制错误报告的冗余行。 | value取值范围：default， verbose，terse | | \\set ON_ERROR_STOP value | 如果设置了这个变量，脚本处理将马上停止。如果该脚本是从另外一个脚本调用的，那个脚本也会按同样的方式停止。如果最外层的脚本不是从一次交互的gsql会话中调用的而是用-f选项调用的，gsql将返回错误代码3，以示这个情况与致命错误条件的区别(错误代码为1)。 | value取值范围为：on/off，true/false，yes/no，1/0 | | \\set RETRY \[retry_times\] | 用于控制是否开启语句出错场景下的重试功能，参数retry_times用来指定最大重试次数，缺省值为5，取值范围为5-10。当重试功能已经开启时，再次执行\\set RETRY可以关闭该功能。 使用配置文件retry_errcodes.conf列举需要重试的错误码列表，该文件和gsql可执行程序位于同一级目录下。该配置文件为系统配置，非用户定义，不允许用户直接修改。 当前支持以下13类出错场景的重试： - YY001：TCP通信错误，Connection reset by peer（CN和DN间通信） - YY002：TCP通信错误，Connection reset by peer（DN和DN间通信） - YY003：锁超时，Lock wait timeout.../wait transaction xxx sync time exceed xxx - YY004：TCP通信错误，Connection timed out - YY005：SET命令发送失败，ERROR SET query - YY006：内存申请失败，memory is temporarily unavailable - YY007：通信库错误，Memory allocate error - YY008：通信库错误，No data in buffer - YY009：通信库错误，Close because release memory - YY010：通信库错误，TCP disconnect - YY011：通信库错误，SCTP disconnect - YY012：通信库错误，Stream closed by remote - YY013：通信库错误，Wait poll unknown error - YY014：快照非法，Snapshot invalid - YY015：连接获取错误，Connection receive wrong - 53200：内存耗尽，Out of memory - 08006：GTM出错，Connection failure - 08000：连接出现错误，和DN的通讯失败，Connection exception - 57P01：管理员关闭系统，Admin shutdown - XX003：关闭远程套接字，Stream remote close socket - XX009：重复查询，Duplicate query id - YY016：stream查询并发更新同一行，Stream concurrent update - CG003：内存分配错误， Allocate error - CG004：致命错误，Fatal error - F0011：临时文件读取错误，File error 同时，出错时gsql会查询所有CN/DN的连接状态，当状态异常时会sleep 1分钟再进行重试，能够覆盖大部分主备切换场景下的出错重试。 说明： 1. 不支持事务块中的语句错误重试； 2. 不支持通过ODBC、JDBC接口查询的出错重试； 3. 含有unlogged表的sql语句，不支持节点故障后的出错重试； 4. 当前不支持CN和GTM节点故障时，gsql客户端的出错重试； 5. gsql客户端本身出现的错误，不在重跑考虑范围之内； | retry_times取值范围为：5-10 | 表12大对象元命令 | 参数 | 参数说明 | |:---|:---| | \\lo_list | 显示一个目前存储在该数据库里的所有DWS大对象及其说明。 | 表13流程控制元命令 | 参数 | 参数说明 | 取值范围 | |:---|:---|:---| | \\if EXPR \\elif EXPR \\else \\endif | 这组元命令可实现可嵌套的条件块： - 条件块以\\if开始，\\endif结束。 - \\if和\\endif两者之间可以出现任意数量的\\elif子句，或单一的\\else子句。 - \\if和\\elif命令支持布尔表达式计算和字符串等值判断。 - \\elif不能出现在\\else和\\endif之间。 | - 布尔表达式计算和gsql原有方式保持一致：true/false、yes/no、on/off、1/0，其他被认为是true。 - 操作符和字符串之间必须使用空格。 - 支持数字比较和字符串比较，比较规则由固有变量COMPARE_STRATEGY控制（详见[表2](https://support.huaweicloud.com/tg-dws/dws_gsql_002.html#ZH-CN_TOPIC_0000002166775368__zh-cn_topic_0000002166615584_zh-cn_topic_0000001098650792_tb7d0ee8c8bbf4c2eb1f55dbe3ad2d5ee)）。默认比较规则中，使用单引号界定字符串和数字。不同规则使用示例详见[\\if条件块比较规则说明与示例]。 - 支持大小比较和等值判断，支持的操作符有：\<，\<=，\>，\>=，==，!=和\<\>。 | | \\goto LABEL \\label LABEL | 这组元命令可实现无条件跳转： - \\label元命令用于创建标签。 - \\goto元命令用于跳转，可实现向上跳转和向下跳转。 说明： - 交互模式不支持使用。 - \\label元命令不支持在\\if语句块中使用。 - \\goto \\label不建议在事务、PL/SQL等语句块中使用，避免出现不可预期结果。 | - LABEL大小写敏感。 - LABEL只能包含大小写字母、数字和下划线。 - LABEL最大长度限制为32（含'\\0'），如果超过长度限制，会截断使用，并输出告警信息。 - \\label后面的标签名如果在同一个session中重复出现，会报错。 | | \\for \\loop \\exit-for \\end-for | 这组元命令可实现循环： - 循环块以\\for开始，以\\end-for结束。 - \\for和\\loop之间为循环条件，只支持SQL语句，不支持变量迭代，例如\\for (i=0; i\<100; ++i)。 - 循环条件中出现多条SQL语句时，以最后一条SQL语句的执行结果为循环条件。作为循环条件的SQL语句不能以分号结尾。 - \\loop和\\end-for之间为循环体，可以使用\\exit-for退出循环。 - \\for循环块支持多层嵌套。 说明： - 交互模式不支持使用。 - 不支持在\\parallel中使用\\for循环块。 - \\for循环块不建议在事务、PL/SQL等语句块中使用，避免出现不可预期结果。 - \\label元命令不支持在\\for循环块中使用。 - \\for \\loop之间不支持使用匿名块。 | - | 流程控制元命令使用示例： - \\if条件块使用示例 示例文件test.sql： ``` SELECT 'Jack' AS "Name"; \if ${ERROR} \echo 'An error occurred in the SQL statement' \echo ${LAST_ERROR_MESSAGE} \elif '${Name}' == 'Jack' \echo 'I am Jack' \else \echo 'I am not Jack' \endif ``` gsql -d -p 25308 --dynamic-param -f test.sql 执行结果： ``` Name ------ Jack (1 row) I am Jack ``` 上面的执行结果表示，第一个SQL语句执行成功，并设置Name变量，所以进入\\elif分支，输出"I am Jack"。特殊变量ERROR和LAST_ERROR_MESSAGE的使用参见[表2](https://support.huaweicloud.com/tg-dws/dws_gsql_002.html#ZH-CN_TOPIC_0000002166775368__zh-cn_topic_0000002166615584_zh-cn_topic_0000001098650792_tb7d0ee8c8bbf4c2eb1f55dbe3ad2d5ee)。 - \\if条件块比较规则说明与示例 - default：默认的比较策略，只支持字符串或数字比较，不支持混合比较。单引号内的按照字符串处理，单引号外的按照数字处理。 示例文件test.sql： ``` \set Name 'Jack' \set ID 1002 -- 以单引号界定，在单引号内的使用字符串比较 \if '${Name}' != 'Jack' \echo 'I am not Jack' -- 没有单引号，使用数字比较 \elif ${ID} > 1000 \echo 'Jack\'id is bigger than 1000' \else \echo 'error' \endif ``` gsql -d -p 25308 --dynamic-param -f test.sql 执行结果： ``` Jack'id is bigger than 1000 ``` 如果使用操作符两侧，一侧使用了单引号，一侧未使用，认定为字符串和数字比较。不支持，则报错。 ``` postgres=> \set Name 'Jack' postgres=> \if ${Name} == 'Jack' ERROR: left[Jack] is a string without quote or number, and right['Jack'] is a string with quote, \if or \elif does not support this expression. WARNING: The input with quote is treated as a string, and the input without quote is treated as a number. postgres@> \endif ``` - natural：在default的基础上，包含动态变量的也按照字符串处理。当比较操作符有一侧是数字比较，尝试将另一侧转换为数字，然后比较。如果转换失败，报错且比较结果为假。 - 识别为字符串的条件有两个，满足任何一个即可。条件一，使用单引号，如'Jack'；条件二，字符串中包含动态变量（${VAR}和:VAR两种），不论变量是否存在，如${Name}_data。条件一和条件二同时满足，如'${Name}_data'。 - 无法识别为字符串的，尝试数字识别。如无法转换成数字，则报错，如1011Q1没有使用单引号、不包含动态变量且无法转换成数字。 - 如果比较符的两侧有一侧未识别为字符串或者数字，无法进行比较，则报错。 - 如果比较符的一侧识别为数字，按照数字比较，如果另一侧无法转换为数字，则报错。 - 如果比较符的两侧都识别为字符串，按照字符串比较。 字符串比较，示例文件test.sql： ``` \set COMPARE_STRATEGY natural SELECT 'Jack' AS "Name"; -- 与'${Name}' > 'Jack'效果等同 \if ${Name} == 'Jack' \echo 'I am Jack' \else \echo 'I am not Jack' \endif ``` gsql -d -p 25308 --dynamic-param -f test.sql 执行结果： ``` Name ------ Jack (1 row) I am Jack ``` 数字比较，示例文件test.sql： ``` \set COMPARE_STRATEGY natural SELECT 1022 AS id; -- 如果使用${id} == '01022'，则结果是不等，因为两侧都是字符串，使用字符串比较，结果为不等 \if ${id} == 01022 \echo 'id is 1022' \else \echo 'id is not 1022' \endif ``` gsql -d -p 25308 --dynamic-param -f test.sql 执行结果： ``` id ------ 1022 (1 row) id is 1022 ``` 错误比较示例： ``` -- 操作符有一侧无法识别为字符串或数字 postgres=> \set COMPARE_STRATEGY natural postgres=> \if ${Id} > 123sd ERROR: The right[123sd] can not be treated as a string or a number. A numeric string should contain only digits and one decimal point, and a string should be enclosed in quote or contain dynamic variables, please check it. -- 操作符一侧数字无法正确转换 postgres=> \set COMPARE_STRATEGY natural postgres=> \if ${Id} <> 11101.1.1 ERROR: The right[11101.1.1] can not be treated as a string or a number. A numeric string should contain only digits and one decimal point, and a string should be enclosed in quote or contain dynamic variables, please check it. ``` - equal：只支持等值比较，所有情况按照字符串比较。 示例文件test.sql： ``` \set COMPARE_STRATEGY equal SELECT 'Jack' AS "Name"; \if ${ERROR} \echo 'An error occurred in the SQL statement' -- equal比较规则下只支持字符串等值判断，大小比较直接报错，无定界符。下面的效果与${Name} == Jack等价 \elif '${Name}' == 'Jack' \echo 'I am Jack' \else \echo 'I am not Jack' \endif ``` gsql -d -p 25308 --dynamic-param -f test.sql 执行结果： ``` Name ------ Jack (1 row) I am Jack ``` - \\goto \\label跳转示例 示例文件test.sql： ``` \set Name Tom \goto TEST_LABEL SELECT 'Jack' AS "Name"; \label TEST_LABEL \echo ${Name} ``` gsql -d -p 25308 --dynamic-param -f test.sql 执行结果： ``` Tom ``` 上面的执行结果表示，\\goto元命令实现跳转，直接执行\\echo命令，没有对变量Name重新赋值。 - \\if条件块和\\goto \\label结合使用示例 示例文件test.sql： ``` \set Count 1 \label LOOP \if ${Count} != 3 SELECT ${Count} + 1 AS "Count"; \goto LOOP \endif \echo Count = ${Count} ``` gsql -d -p 25308 --dynamic-param -f test.sql 执行结果： ``` Count ------- 2 (1 row) Count ------- 3 (1 row) Count = 3 ``` 上面的执行结果表示，通过\\if条件块和\\goto \\label的结合实现简单的循环。 - \\for循环块使用示例 为了展示该功能，示例数据如下： ``` create table student (id int, name varchar(32)); insert into student values (1, 'Jack'); insert into student values (2, 'Tom'); insert into student values (3, 'Jerry'); insert into student values (4, 'Danny'); create table course (class_id int, class_day varchar(5), student_id int); insert into course values (1004, 'Fri', 2); insert into course values (1003, 'Tue', 1); insert into course values (1003, 'Tue', 4); insert into course values (1002, 'Wed', 3); insert into course values (1001, 'Mon', 2); ``` \\for循环使用示例文件test.sql： ``` \for select id, name from student order by id limit 3 offset 0 \loop \echo -[ RECORD ]+----- \echo id '\t'| ${id} \echo name '\t'| ${name} \end-for ``` gsql -d -p 25308 --dynamic-param -f test.sql 执行结果： ``` -[ RECORD ]+----- id | 1 name | Jack -[ RECORD ]+----- id | 2 name | Tom -[ RECORD ]+----- id | 3 name | Jerry ``` 上面的执行结果表示，通过循环块对SQL语句的执行结果进行遍历，\\loop和\\end-for之间可以出现更多语句，实现复杂的逻辑。 如果作为循环条件的SQL语句执行失败或者结果集为空，\\loop和\\end-for之间的语句将不被执行。 示例文件test.sql： ``` \for select id, name from student_error order by id limit 3 offset 0 \loop \echo -[ RECORD ]+----- \echo id '\t'| ${id} \echo name '\t'| ${name} \end-for ``` gsql -d -p 25308 --dynamic-param -f test.sql 执行结果： ``` gsql:test.sql:3: ERROR: relation "student_error" does not exist LINE 1: select id, name from student_error order by id limit 3 offset... ^ ``` 上面的执行结果表示，student_error这个表不存在，所以SQL语句执行失败，\\loop和\\end-for之间的语句将不被执行。 - \\exit-for退出循环 示例文件test.sql： ``` \for select id, name from student order by id \loop \echo ${id} ${name} \if ${id} == 2 \echo find id(2), name is ${name} \exit-for \endif \end-for ``` gsql -d -p 25308 --dynamic-param -f test.sql 执行结果： ``` 1 Jack 2 Tom find id(2), name is Tom ``` 表student中的数据超过两行，当id=2时，使用\\exit-for退出循环，不再继续执行。这个过程中也有与\\if条件块的配合使用。 - \\for循环嵌套 示例文件test.sql： ``` \for select id, name from student order by id limit 2 offset 0 \loop \echo ${id} ${name} \for select class_id, class_day from course where student_id = ${id} order by class_id \loop \echo ' '${class_id}, ${class_day} \end-for \end-for ``` gsql -d -p 25308 --dynamic-param -f test.sql 执行结果： ``` 1 Jack 1003, Tue 2 Tom 1001, Mon 1004, Fri ``` 通过两层循环获得Jack、Tom相关的course表中的信息。 #### PATTERN 很多\\d命令都可以用一个PATTERN参数来指定要被显示的对象名称。在最简单的情况下，PATTERN正好就是该对象的准确名称。在PATTERN中的字符通常会被变成小写形式（就像在SQL名称中那样），例如\\dt FOO将会显示名为foo的表。就像在SQL名称中那样，把PATTERN放在双引号中可以阻止它被转换成小写形式。如果需要在一个PATTERN中包括一个真正的双引号字符，则需要把它写成两个相邻的双引号，这同样是符合SQL引用标识符的规则。例如，\\dt "FOO""BAR"将显示名为FOO"BAR（不是foo"bar）的表。和普通的SQL名称规则不同，不能只在PATTERN的一部分周围放上双引号，例如\\dt FOO"FOO"BAR将会显示名为fooFOObar的表。 不使用PATTERN参数时，\\d命令会显示当前schema搜索路径中可见的全部对象------这等价于用\*作为PATTERN。所谓对象可见是指可以直接用名称引用该对象，而不需要用schema来进行限定。要查看数据库中所有的对象而不管它们的可见性，可以把\*.\*用作PATTERN。 如果放在一个PATTERN中，\*将匹配任意字符序列（包括空序列），而?会匹配任意的单个字符（这种记号方法就像 Unix shell 的文件名PATTERN一样）。例如，\\dt int\*会显示名称以int开始的表。但是如果被放在双引号内，\*和?就会失去这些特殊含义而变成普通的字符。 包含一个点号（.）的PATTERN被解释为一个schema名称模式后面跟上一个对象名称模式。例如，\\dt foo\*.\*bar\*会显示名称以foo开始的schema中所有名称包括bar的表。如果没有出现点号，那么模式将只匹配当前schema搜索路径中可见的对象。同样，双引号内的点号会失去其特殊含义并且变成普通的字符。 高级用户可以使用字符类等正则表达式记法，如\[0-9\]可以匹配任意数字。所有的正则表达式特殊字符都按照《开发指南》中的POSIX正则表达式所说的工作。以下字符除外： - .会按照上面所说的作为一种分隔符。 - \*会被翻译成正则表达式记号.\*。 - ?会被翻译成.。 - $则按字面意思匹配。 根据需要，可以通过书写?、(*R* +\|)、(*R* \|)和*R* ?来分别模拟PATTERN字符.、*R* \*和*R*?。$不需要作为一个正则表达式字符，因为PATTERN必须匹配整个名称，而不是像正则表达式的常规用法那样解释（换句话说，$会被自动地追加到PATTERN上）。如果不希望该PATTERN的匹配位置被固定，可以在开头或者结尾写上\*。注意在双引号内，所有的正则表达式特殊字符会失去其特殊含义并且按照其字面意思进行匹配。另外，在操作符名称PATTERN中（即\\do的PATTERN参数），正则表达式特殊字符也按照字面意思进行匹配。