KingbaseES_ksql工具用户指南及参考.pdf
KingbaseES ksql 工具用户指南及参考 金仓数据库管理系统 KingbaseES 文档版本：V9（V009R001C001B0024） 发布日期：2023 年 10 月 12 日 北京人大金仓信息技术股份有限公司 目 目 录 录 第 1 章 前言 1 1.1 适用读者 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.2 相关文档 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 1.3 术语 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 1.4 手册约定 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 第 2 章 Ksql 快速启动 4 Ksql 概述 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 Ksql 命令行架构 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.2 Ksql 先决条件 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.3 启动 Ksql 命令行 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.4 连接目标数据库 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.5 执行一个查询 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.6 退出 Ksql . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.1 2.1.1 第 3 章 Ksql 入门 3.1 配置 Ksql . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.1.1 Ksql 环境变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.1.2 配置文件 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.1.3 注解 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 给 Windows 用户的注解 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 启动 Ksql . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 登录用户名和密码 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 更改密码 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.2.2 连接到数据库 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.2.3 有关启动 Ksql . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 3.2.3.1 启动 Ksql 命令行 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 3.2.3.2 退出 Ksql 命令行 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Ksql 程序语法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 option 选项 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 3.1.3.1 3.2 8 3.2.1 3.2.1.1 3.2.4 3.2.4.1 I 目 第 4 章 使用 Ksql 录 20 Ksql 基础 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 输入和执行命令 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 执行命令 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 4.1.2 列出表的定义 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 4.1.3 列出 PL/SQL 定义 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 4.1.4 列出模式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 4.1.4.1 概述 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 4.1.4.2 列出模式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 运行 SQL 命令 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 4.1.5.1 理解 SQL 命令语法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 4.1.5.2 将 SQL 命令换分为单独的行 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 4.1.5.3 结束 SQL 命令 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 运行 PL/SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 创建存储过程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 运行 Ksql 命令 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 理解 Ksql 命令语法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 4.1.7.1.1 元命令概述 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 4.1.7.1.2 命令格式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 4.1.7.1.3 命令行编辑 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 4.1.7.1.4 命令提示符 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 4.1.8 变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 4.1.9 停止正在运行的任务 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 4.1.10 运行操作系统命令 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 4.1.11 自动保存对数据库的更改 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 4.1.12 显示详细错误信息 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 4.1.12.1 Oracle 兼容 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Ksql 执行脚本 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 启动 Ksql 时运行一个脚本 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 4.3 SQL 中插入变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 4.4 格式化 Ksql 输出 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 4.4.1 设置输出格式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 4.4.2 定义打印的标题 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 4.4.3 存储和打印查询结果 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 4.4.4 \r 显示风格 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 4.5 生成 HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 4.6 Ksql 调优 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 4.6.1 统计 SQL 执行时间 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 4.6.2 输出执行计划 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 Ksql 安全 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 创建和控制角色 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 4.1 4.1.1 4.1.1.1 4.1.5 4.1.6 4.1.6.1 4.1.7 4.1.7.1 4.2 4.2.1 4.7 4.7.1 II 目 第 5 章 Ksql 命令参考 录 45 5.1 a . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 5.2 c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 5.3 C. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 5.4 directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 5.5 conninfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 5.6 copy command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 5.7 copyright . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 5.8 crosstabview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 5.9 d[S+] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 5.10 da[S] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 5.11 dA[+] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 5.12 db[+] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 5.13 dc[S+] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 5.14 dC[+] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 5.15 dd[S] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 5.16 dD[S+] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 5.18 dE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 5.19 des[+] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 5.20 det[+] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 5.21 deu[+] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 5.22 dew[+] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 5.23 df . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 5.24 dF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 5.25 dFd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 5.26 dFp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 5.27 dFt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 5.28 dg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 5.29 dl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 5.30 dL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 5.31 dn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 5.32 do[S+] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 5.33 dO[S+] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 5.34 dp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 5.35 dP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 5.36 drds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 5.37 dRp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 5.38 dRs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 5.39 dT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 5.40 du . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 5.41 dx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 5.17 ddp III 目 录 5.42 dy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 5.43 e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 5.44 echo text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 5.45 ef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 5.46 encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 5.47 errverbose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 5.48 ev . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 5.49 f . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 5.50 g . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 5.51 gdesc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 5.52 gexec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 5.53 gset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 5.54 gx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 5.55 h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 5.56 H . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 5.57 i . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 5.58 if . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 5.59 ir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 5.60 l . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 5.61 lo_export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 5.62 lo_import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 5.63 lo_list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 5.64 lo_unlink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 5.65 o . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 5.66 p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 5.67 password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 5.68 prompt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 5.69 pset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 5.70 q . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 5.71 qecho text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 5.72 r . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 5.73 s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 5.74 set name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 5.75 setenv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 5.76 sf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 5.77 sv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 5.78 t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 5.79 T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 5.80 timing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 5.81 unset name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 5.82 w . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 5.83 watch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 IV 目 录 5.84 x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 5.85 z . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 5.86 ! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 5.87 ? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 5.88 反斜线分号 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 版权声明 74 服务周期承诺 75 V 第 1 章 前言 1 第 章 前言 本文档介绍了 ksql 及其用途，并描述了每个 ksql 命令。 前言部分包含以下主题： • 适用读者 • 相关文档 • 术语 • 手册约定 1.1 适用读者 KingbaseES ksql 工具用户指南及参考面向所有使用 KingbaseES 的用户，主要是数据库管理员和应用程序开发 人员。 ksql 语言很容易使用。例如重新设置显查询显示的标题信息, 输入以下命令： -- set title \pset title 'Query Result' -- select SELECT * FROM t1 LIMIT 2; Query Result a | b ---+--1 | 1 2 | 2 (2 rows) 1 第 1 章 前言 1.2 相关文档 有关更多信息，请参阅以下资源： • KingbaseES 数据库概念 • KingbaseES SQL 参考手册 • KingbaseES PL/SQL 参考手册 • KingbaseES 错误代码参考手册 1.3 术语 1.4 手册约定 本文档中可能出现“注意、提示、警告、另请参阅”等标志，它们所代表的含义如下： 注意: 用于突出重要/关键信息、最佳实践等。 提示: 用于突出小窍门、捷径等。 警告: 用于传递设备或环境安全警示信息，若不避免，可能会导致设备损坏、数据丢失、设备性能降低或其 它不可预知的结果。 另请参阅: 用于突出参考、参阅等。 以下程序代码书写约定适用于本文档： 符号 说明 [] 表示包含一个或多个可选项。不需要输入中括号本身。 {} 表示包含两个以上（含两个）的候选，必须在其中选取一个。不需要输入花括号本身。 | 分割中括号或者花括号中的两个或两个以上选项。不需要输入“|”本身。 见续表 2 第 1 章 前言 表 1.4.1 – 续表 符号 说明 ... 表示其之前的元素可以被重复。 斜体 表示占位符或者需要提供特定值的变量。 大写 表示系统提供的元素，以便与用户定义的元素相互区分。除出现在方括号中的元素外，应当按 照顺序逐字输入。当然，部分元素在系统中是大小写不敏感的，因此用户可以根据系统说明以 小写形式输入。 小写 表示由用户提供的元素。 3 第 2 章 KSQL 快速启动 2 第 章 Ksql 快速启动 本部分包含以下内容： • Ksql 概述 • Ksql 先决条件 • 启动 Ksql 命令行 • 连接目标数据库 • 执行一个查询 • 退出 Ksql 2.1 Ksql 概述 Ksql 是 KingbaseES 基于终端的前端。提供交互式查询，通过文件输入或者命令行输入，得到查询结果。此外， Ksql 还提供一些元命令和多种类似 shell 的特性来为编写脚本和自动化多种任务提供便利。 注意: KingbaseES 的 V9 版本为兼容 V7 版本的 isql 用法，实际上是 ksql 的拷贝，所以使用 isql 连接数据库后仍显 示 ksql 的相关信息。 2.1.1 Ksql 命令行架构 Ksql 命令行使用了一个两层模型，其中包括： • 客户端 (用户命令行接口) • 数据库 (KingbaseES 数据库) Ksql 客户端 命令行用户界面基于字符终端实现。 4 第 2 章 KSQL 快速启动 KingbaseES 数据库 KingbaseES 数据库使用基于消息的协议在 Ksql 客户端和后端之间通信，协议支持 TCP/IP 和 Unix 套接 字。 2.2 Ksql 先决条件 Ksql 是 KingbaseES 数据库的一个组件，在安装 KingbaseES 数据库时，默认会安装 Ksql。 在运行 Ksql 之前还需要做什么呢？ • 安装 KingbaseES 数据库或 Ksql 客户端; • 获取目标数据库的名称、主机名和服务器的端口号以及用户名; • 确保连接的数据库已启动; 2.3 启动 Ksql 命令行 Ksql 是一个常规 KingbaseES 客户端应用。为了连接到数据库，你需要知道你的目标数据库的名称、主机名和 该服务器的端口号，以及用于连接数据库的用户名。可以通过命令行选项告知 Ksql 这些参数，分别是-d、-h、-p 以及-U 。如果发现一个参数不属于任何选项，它将被解释为数据库名称（如果已经给出数据库名称，就解释为用户 名）。这些选项并非都是必须的，它们都有可用的默认值。如果省略主机名，Ksql 将连接到本地主机上的服务器， 或通过 TCP/IP 连接到主机上的 localhost。默认端口号则在编译时决定。由于数据库服务器使用相同的默认值， 大多数情况下你将不必指定端口。默认的用户名和数据库名与操作系统用户名相同。 当默认值不是很符合实际时，可以把环境变量 KINGBASE_DATABASE 、KINGBASE_HOST 、KINGBASE_PORT 以及 KINGBASE_USER 设置为适当的值。用一个 ~/.kbpass 文件来避免定期输入密码也很方便。 另一种指定连接参数的方法是用一个“conninfo“* 字符串或者一个 URI，它可以被用来替代数据库名。这种机制 可以让我们对连接具有很广的控制权。例如： $ ksql "service=myservice sslmode=require" $ ksql kingbase://dbmaster:5433/mydb?sslmode=require 如果由于任何原因（例如权限不足、服务器没有在目标主机上运行等）导致连接无法建立，Ksql 将返回一个错 误并且终止。 如果标准输入和标准输出都是一个终端，那么 Ksql 会把客户端编码设置成“auto”，这会使 Ksql 从区域 设置（Linux 系统上的 LC_CTYPE 环境变量）中检测合适的客户端编码。如果这样不起作用，可以使用环境变量 KINGBASE_CLIENTENCODING 覆盖客户端编码。 5 第 2 章 KSQL 快速启动 2.4 连接目标数据库 在 Linux 或者 Windows 终端输入 Ksql 命令： $ ksql -p 54320 -d test ksql (V9.0) Type "help" for help. 2.5 执行一个查询 在正常操作时，Ksql 会提供一个提示符，该提示符是 Ksql 当前连接到的数据库名称后面跟上字符串 =#。例 如： $ ksql testdb ksql (V9.0) Type "help" for help. testdb=# 在提示符下，用户可以键入 SQL 命令。正常情况下，当碰到一个表示命令终结的分号时，输入的行会被发送给 服务器。一行的结束并不表示命令的完结。因此，为了清晰，可以把命令散布在多个行上。如果命令被发送并且执行 而不产生错误，该命令的结果将会显示在屏幕上。例如： test=# select a, b from t1; a | b ---+--1 | 2 3 | 4 (2 rows) 如果不受信任的用户能够访问没有采用 安全使用模式的数据库，通过从 search_path 删除公共可写的模式来开 始会话。可以在连接字符串加入 options=-csearch_path= 或者在其他 SQL 命令之前发出 SELECT sys_catalog. set_config('search_path', '', false)。这种考虑并非专门针对 Ksql，它适用于每一种执行任意 SQL 命令的接 口。 只要执行命令，Ksql 还会测试 LISTEN 和 NOTIFY 产生的异步通知。 C 风格的注释块会被传给服务器处理并且移除，Ksql 会自己移除掉 SQL 标准的注释。 6 第 2 章 KSQL 快速启动 2.6 退出 Ksql 如果需要退出 Ksql 命令行，输入 \q 即可，Ksql 正常完成，它会向 shell 返回 0。如果它自身发生一个致命错误 （例如内存用完、找不到文件），它会返回 1。如果到服务器的连接出问题并且事务不是交互式的，它会返回 2。如 果在脚本中发生错误，它会返回 3 并且变量 ON_ERROR_STOP 会被设置。 7 第3章 3 第 章 KSQL 入门 Ksql 入门 上一章提供了您开始使用 Ksql 所需的信息。本章将提供配置信息和登录并运行 Ksql 所需的信息： • 配置 Ksql • 启动 Ksql 3.1 配置 Ksql 3.1.1 Ksql 环境变量 COLUMNS 如果\pset columns 为零，这个环境变量控制用于 wrapped 格式的宽度以及用来确定是否输出需要用到 分页器或者切换到扩展自动模式中的垂直格式的宽度。 KINGBASE_DATABASE KINGBASE_HOST KINGBASE_PORT KINGBASE_USER 默认连接参数。 SYS_COLOR 指定是否在诊断消息中使用颜色。可能的值是 always, auto, never. KSQL_EDITOR EDITOR VISUAL \e、\ef 以及\ev 命令所使用的编辑器。会按照列出的顺序检查这些变量，第一个被设置的将被使用。如 果都没有被设置，默认是使用 Linux 系统上的 vi 或者 Windows 系统上的 notepad.exe。 KSQL_EDITOR_LINENUMBER_ARG 当\e、\ef 或者\ev 带有一个行号参数时，这个变量指定用于传递起始行号给用户编辑器的命令行参数。 对于 Emacs 或者 vi 之类的编辑器，这个变量是一个加号。如果需要在选项名称和行号之间有空格，可以 在该变量的值中包括一个结尾的空格。例如： 8 第3章 KSQL 入门 KSQL_EDITOR_LINENUMBER_ARG='+' KSQL_EDITOR_LINENUMBER_ARG='--line ' 在 Unix 系统上默认是 +（对应于默认编辑器 vi，且对很多其他常见编辑器可用）。在 Windows 系统上 没有默认值。 KSQL_HISTORY 命令历史文件的替代位置。波浪线（~）扩展会被执行。 KSQL_PAGER PAGER 如果一个查询的结果在屏幕上放不下，它们会通过这个命令分页显示。典型的值是 more 或 less。通过 把 KSQL_PAGER 或 PAGER 设置为空字符串可以禁用分页器的使用，调整\pset 命令与分页器相关的选项 也能达到同样的效果。会按照列出的顺序检查这些变量，第一个被设置的将被使用。如果都没有被设置， 则大部分平台上默认使用 more，但在 Cygwin 上使用 less。 KSQLRC 用户的.ksqlrc 文件的替代位置。波浪线（~）扩展会被执行。 SHELL 被\! 命令执行的命令。 TMPDIR 存储临时文件的目录。默认是/tmp。 和大部分其他 KingbaseES 工具一样，这个工具也使用 libkci 所支持的环境变量。 3.1.2 配置文件 ksqlrc and ~/.ksqlrc 如果没有-X 选项，在连接到数据库后但在接收正常的命令之前，Ksql 会尝试依次从系统级的启动文件 （ksqlrc）和用户的个人启动文件（~/.ksqlrc）中读取并且执行命令。这些文件可以被用来设置客户端 或者服务器，通常是一些\set 和 SET 命令。 系统级的启动文件是 ksqlrc，它应该在安装好的 KingbaseES 的“系统配置”目录中，最可靠的定位方 法是运行 sys_config --sysconfdir。默认情况下，这个目录将是../etc/（相对于包含 KingbaseES 可 执行文件的目录）。可以通过 KCISYSCONFDIR 环境变量显式地设置这个目录的名称。 用户个人的启动文件是.ksqlrc，它应该在调用用户的主目录中。在 Windows 上，由于没有用户主目录的 概念，个人的启动文件是%APPDATA%\kingbase\ksqlrc.conf。用户启动文件的位置可以通过 KSQLRC 环 境变量设置。 9 第3章 KSQL 入门 系统级和用户个人的启动文件都可以弄成是针对特定 Ksql 版本的，方法是在文件名后面加上一个横线以 及 KingbaseES 的主、次版本号，例如 ~/.ksqlrc-9.2 或者 ~/.ksqlrc-9.2.5。版本最为匹配的文件会 优先于不那么匹配的文件读入。 .ksql_history 命 令 行 历 史 被 存 储 在 文 件 ~/.ksql_history 中， 或 者 是 Windows 的 文 件%APPDATA%\kingbase\ ksql_history 中。 历史文件的位置可以通过 HISTFILEKsql 变量或者 KSQL_HISTORY 环境变量明确的设置。 3.1.3 注解 • Ksql 和具有相同主版本或者更老的主版本服务器最为匹配。如果服务器的版本比 Ksql 本身要高，则反斜线命 令尤其容易失败。不过，\d 家族的反斜线命令应该可以和 V7 版本之后的服务器一起使用，但服务器的版本不 必比 ksql 本身新。运行 SQL 命令并且显示查询结果的一般功能应该也能和具有更新主版本的服务器一起使用， 但是并非在所有的情况下都能保证如此。 如果你想用 ksql 连接到多个具有不同主版本的服务器，推荐使用最新版本的 Ksql。或者，你可以为每一个主版 本保留一份 Ksql 拷贝，并且针对相应的服务器使用匹配的版本。但实际上，这种额外的麻烦是不必要的。 • 在 KingbaseES V8R2 之前，-c 选项表示-X（--no-ksqlrc），但现在不是这样了。 • 在 KingbaseES V7 之前，Ksql 允许一个单字母反斜线命令的第一个参数直接写在该命令后面，中间不需要空 格。现在则要求一些空格。 3.1.3.1 给 Windows 用户的注解 Ksql 是一个“控制台应用”。由于 Windows 的控制台窗口使用的是一种和系统中其他应用不同的编码，在 Ksql 中使用 8 位字符时要特别注意。如果 Ksql 检测到一个有问题的控制台代码页，它将会在启动时警告你。要更改控制 台代码页，有两件事是必要的： • 输入 cmd.exe /c chcp 1252 可以设置代码页（1252 是适用于德语的一个代码页，请在这里替换成你的值）。 如果正在使用 Cygwin，可以把这个命令放在/etc/profile 中。 • 把控制台字体设置为 Lucida Console，因为栅格字体无法与 ANSI 代码页一起使用。 Windows 环境下，如果给 Ksql 传入的参数使用引号包含起来时，建议使用双引号，因为有的 bash 不能正确的 识别单引号，可能导致执行结果报错。例如： ksql 'hostaddr=127.0.0.1 port=54321 user=system dbname=test' ksql: 警告: 忽略多余的命令行参数 "dbname=test" ksql: 警告: 忽略多余的命令行参数 "user=kingbase'" ksql: 错误: 无法连接到服务器：invalid connection option "'hostaddr" 10 第3章 KSQL 入门 -- successfully login ksql "hostaddr=127.0.0.1 port=54321 user=system dbname=test" Windows 环境下，如果传入给 Ksql 的参数不带 option 时，那么不带 option 的参数最多只能解析前 2 个，后面 的参数将被忽略且解析的顺序为数据库名和用户名。建议使用带有 option 的参数。例如： ksql test system -c "create table t1 (a int);" ksql: 警告: 忽略多余的命令行参数 "-c" ksql: 警告: 忽略多余的命令行参数 "create table t1 (a int);" 上面例子是不带 option 的参数放在前面，则后面的 -c 等参数被忽略没有被解析。 下面是正确使用的例子： ksql -d test -U system -c "create table t1 (a int);" 3.2 启动 Ksql 3.2.1 登录用户名和密码 当您启动 Ksql 时, 需要一个用户名和密码才能登录到 KingbaseES 数据库模式。您的用户名和密码是 KingbaseES 数据库授权的用户。 数据库管理员负责创建具有必要权限的数据库账户，并提供能够访问的用户名和密码。 您可以使用连接命令对不同的用户进行连接，用户名和密码必须对该数据库有效。例如，连接到 user1 用户： $ ksql -Uuser1 -d test -p54320 ksql (V9.0) Type "help" for help. 3.2.1.1 更改密码 在命令行界面中，您可以使用 \password [ username ] 命令修改密码。 3.2.2 连接到数据库 必须连接到 KingbaseES 数据库才能查询或修改该数据库中的数据。您可以连接到默认数据库或通过网络连接到 其他数据库。连接命令格式如下： • ksql [option...] [dbname [username]] 11 第3章 KSQL 入门 $ ksql -h 10.11.0.14 -Uuser1 -d test -p54320 Password for user user1: ksql (V9.0) Type "help" for help. Ksql 通过服务名连接命令 为了兼容 oralce, 达梦以及 KingbaseES V7 版本，需要增加 Ksql 对 service 文件的检查，通过文件中的信息找到 对应库并连接。 语法格式： ksql username[/password][@[//][host][:port/]servicename] 参数说明： • username: 表示用户名 • password: 表示用户密码 • servicename: 表示服务名称 • host: 表示网络地址 IP • port: 表示端口号 其中 host、port 和 servicename 等信息是在 sys_service.conf 文件中配置的内容。例如： [kingbase] host=192.168.0.1 dbname=test port=54321 其它可配置参数可参见《KingbaseES 客户端编程接口指南-DCI》中服务的配置方法与参数说明章节。 优先级说明： 由于 sys_service.conf 文件可能存在不同的位置，ksql 需要按照如下的顺序 (优先级依次降低) 寻找 sys_service.conf 并获取连接数据库的信息： • KINGBASE_SERVICEFILE 环境变量 • ~/.sys_service.conf • KINGBASE_SYSCONFDIR 环境变量 • SYSCONFDIR/sys_service.conf • /etc 使用服务名方式登录例子如下： • 用户名和密码中不含有 @、/或引号等特殊时，在终端可以直接输入，不需要被引号引起来，如下的登录方式： 12 第3章 KSQL 入门 $ ksql usr1/123456@127.0.0.1/serviceName1 • 用户名或密码中含有‘/’、@ 等特殊字符时，需要使用引号将其引起来，否则解析到的登录信息可能和预期不 符: -- failed login ksql usr/@abc/1234///56@127.0.0.1/serviceName1 ksql: error: could not connect to server: definition of service "abc/1234///56@127.0.0.1/serviceName1" not found. 通过报错信息可知，解析的 servicename 和预期不一致，导致登录失败。这种情况应该使用引号将用户名和密码 引起来。 -- successfully login ksql '"usr/@abc"/"1234///56"@127.0.0.1/serviceName1' • Service 信息中端口号和 Service name 可以包含在双引号中，但支持包含在单引号里,Host 不能包含在引号里 面。如下的登录方式： -- successfully login ksql 'usr1/123456@127.0.0.1:"54320"/"serviceName1"' -- failed login ksql "usr1/123456@127.0.0.1:'54320'/serviceName1" ksql: error: could not connect to server: definition of service "127.0.0.1:'54320'/serviceName1" not found. Port 如果包含在单引号中，service 信息将不能被正确的解析，导致登录失败。 -- failed login ksql 'usr1/123456@"127.0.0.1":54320/serviceName1' ksql: error: could not connect to server: definition of service ""127.0.0.1":54320/serviceName1" not found. Host 信息包含在引号里，service 信息不能被正确解析，导致登录失败。 限制与约束 • 如果用户的数据名字类似于”username/password@servicename” ,ksql 优先使用 servicename 的登录方式进行解 析命令行参数，结果可能和预期不符。建议使用 -d 参数明确指定数据库。例如，用户创建的数据库名为”test/ abc@sever1”。 • 如果用户名或者是用户密码包含 @ 或/等特殊字符，建议使用如下方式：’” username”/” password” @servicename’。 • 暂不支持用户名中带有引号和密码中带有 @ 的情况，否则，解析出来的信息可能与预期不符。 13 第3章 KSQL 入门 • Service 信息中，host 不能被包含在引号里，port 和 service name 可以包含在双引号里。 影响分析 如果用户的数据名字类似于”username/ password@servicename” ,ksql 优先使用 servicename 的登录方式进行 解析命令行参数，结果可能和预期不符。建议使用 -d 参数明确指定数据库。例如，用户创建的数据库名为”test/ abc@sever1”。 3.2.3 有关启动 Ksql 3.2.3.1 启动 Ksql 命令行 要开始使用 Ksql, 您必须首先了解如何启动和停止 Ksql。 • 请确保在您的计算机上已经安装了 Ksql； • 登录到操作系统 (如果需要)； • 输入连接到数据库的命令，然后按 Enter 键。例如： ksql -h 10.11.0.14 -Uuser1 -d test -p54320 • 根据提示输入密码后再按 ENTER 键。为了保护您的密码安全不会显示在屏幕上。 $ ksql -h 10.11.0.14 -Uuser1 -d test -p54320 Password for user user1: ksql (V9.0) Type "help" for help. Ksql 显示连接的 KingbaseES 数据版本以及如何获取帮助的命令。接下来，Ksql 将显示 Ksql 命令提示符： test=# Ksql 命令提示符指示 Ksql 已经准备好接受您的命令。 关于获取命令行帮助 若要访问 Ksql 命令的命令行帮助，在 SQL 命令提示符上输入 help 命令。例如： test=# help You are using ksql, the command-line interface to Kingbase. Type: \copyright for distribution terms \h for help with SQL commands \? for help with ksql commands \g or terminate with semicolon to execute query \q to quit 14 第3章 3.2.3.2 KSQL 入门 退出 Ksql 命令行 如果您因为用户名或密码无效或由于其他原因导致无法登录到 Ksql, 那么 Ksql 将返回相应的错误信息。 当您完成与 Ksql 相关的操作并返回到操作系统时, 在 Ksql 提示符下输入 \q 命令或 Ctrl+Z。 3.2.4 Ksql 程序语法 您可以使用操作系统提示符处的 Ksql 命令启动 Ksql 命令行： ksql [option...] [dbname [username]] 例如： ksql -p54320 -d test • 启动 Ksql 并连接到默认数据库： – 打开 UNIX 或 Windows 终端，输入 Ksql 命令。例如： $ ksql -p54320 -Uuser1 命令参数中不指定连接的数据库。 – Ksql 启动并连接到默认数据库。 ksql (V9.0) Type "help" for help. user1=# 现在，您可以开始在 SQL# 提示符下开始输入和执行 SQL、PL/SQL 和 Ksql 语句和命令。 3.2.4.1 option 选项 -a --echo-all 把所有非空输入行按照它们被读入的形式打印到标准输出（不适用于交互式行读取）。这等效于把变量 ECHO 设置为 all。 -A --no-align 切换到非对齐输出模式（默认输出模式是对齐的）。这等效于 \pset format unaligned。 -b --echo-errors 把失败的 SQL 命令打印到标准错误输出。这等效于把变量 ECHO 设置为 errors。 -B 15 第3章 KSQL 入门 用户登录时提供验证码功能。在尝试登录时，如果当前场景是需要输入密码的，则在输入密码后，弹出输 入验证码的提醒，用户按照显示的验证码正确输入后，则可正常连接数据库。验证码由四位随机的数字字 母混合组成，字母显示为大写，输入时不区分大小写。 -c command --command=command 指定 Ksql 执行一个给定的命令字符串 command。这个选项可以重复多次并且以任何顺序与-f 选项组合在 一起。当-c 或者-f 被指定时，Ksql 不会从标准输入读取命令，直到它处理完序列中所有的-c 和-f 选项 之后终止。 command 必须是一个服务器完全可解析的命令字符串（即不包含 Ksql 相关的特性）或者单个反斜线命 令。因此不能在一个-c 选项中混合 SQL 和 Ksql 元命令。要那样做，可以使用多个-c 选项或者把字符 串用管道输送到 Ksql 中，例如： ksql -c '\x' -c 'SELECT * FROM foo;' 或者 echo '\x \\ SELECT * FROM foo;' | Ksql （\\是分隔符元命令）。 每一个被传递给-c 的 SQL 命令字符串会被当做一个单独的请求发送给服务器。因此，即便该字符串包括 多个 SQL 命令，服务器也会把它当做一个事务来执行，除非在该字符串中有显式的 BEGIN/COMMIT 命令 把它划分成多个事务。此外，Ksql 只会打印出该字符串中最后一个 SQL 命令的结果。这和从文件中读取 同一字符串或者把同一字符串传给 Ksql 的标准输出时的行为不同，因为那两种情况下 Ksql 会独立地发送 每一个 SQL 命令。 由于这种行为，把多于一个 SQL 命令放在-c 字符串中通常会得到意料之外的结果。最好使用多个-c 命令 或者把多个命令输送给 Ksql 的标准输入，按照上文所说的使用 echo 或者通过一个 shell，例如： ksql < 10; 创建一个表： testdb=> CREATE TABLE my_table ( testdb(> first integer not null default 0, testdb(> second text) testdb-> ; CREATE TABLE 注意: 命令提示符的改变。 在本指南中，会发现大多数 SQL 命令都分为子句，每行一个句子。例如，上面的查询例子中，SELECT 和 FROM 子句被放置在不同的行上。许多人发现这种清晰可见的结构很有帮助，但您可以选择任何划分使命令更加的 易读。 23 第4章 4.1.5.3 使用 KSQL 结束 SQL 命令 可以通如下方式结束 SQL 命令： • 使用分号 (;) • 使用 \g 结束 • 使用 set SQLTERM 命令定义 SQL 命令结束符 一个分号 (;) 告诉 Ksql 您要运行该命令。在命令的最后一行的末尾输入分号，然后按 ENTER 键，Ksql 处理该 命令，将其发送到服务器并返回结果。如果在输入分号之前错误的按了 ENTER 键，Ksql 将提示输入命令的下一行 的行号。键入分号再次运行命令。例如： -- 分号结束符 SELECT * FROM parts ; pnum | pname ------+------11 | 22 | 33 | 44 | 55 | (5 rows) -- \set SQLTERM 定义 / 结束符 \set SQLTERM / select * from parts / pnum | pname ------+------11 | 22 | 33 | 44 | 55 | (5 rows) \set SQLTERM ; 4.1.6 运行 PL/SQL 您可以使用 PL/SQL 子程序来操作数据库的数据。有关 PL/SQL 语句的信息，请参考 KingbaseES 数据库 PL/ SQL 语言参考资料。Ksql 以与 SQL 命令相同的方式处理 PL/SQL 子程序，只是分号 (;) 不会终止并执行 PL/SQL。 在以下情况下，可以进入输入 PL/SQL 语句模式： 24 第4章 使用 KSQL • 可以键入一个用来创建存储过程的 SQL 命令 (例如，创建函数)。以这种方式进入 PL/SQL 模式后，键入要创 建的存储过程。 • 可以通过 set SQLTERM 指定一个结束符，在创建的存储过程结束后新的一行中键入指定的结束符来结束存储 过程的创建。 例如：创建并执行 test 函数 -- 创建名为 test 的函数 CREATE OR REPLACE FUNCTION test( ) RETURNS SETOF test1 AS $BODY$ BEGIN FOR i IN 1 .. 5 LOOP INSERT INTO test1 VALUES(i,1); END LOOP; RETURN QUERY SELECT * FROM test1; RETURN; END $BODY$ LANGUAGE plpgsql; -- 通过 \set SQLTERM 指定 / 结束符 \set SQLTERM / CREATE OR REPLACE FUNCTION test( ) RETURNS SETOF test1 AS BEGIN FOR i IN 1 .. 5 LOOP INSERT INTO test1 VALUES(i,1); END LOOP; RETURN QUERY SELECT * FROM test1; RETURN; END; / \set SQLTERM ; -- 执行 test 函数 SELECT * FROM test(); 4.1.6.1 创建存储过程 存储过程是 PL/SQL 函数、软件包或过程。若要创建存储过程，请使用以下的 SQL 创建命令： • CREATE FUNCTION 25 第4章 使用 KSQL • CREATE LIBRARY • CREATE PACKAGE • CREATE PACKAGE BODY • CREATE PROCEDURE • CREATE TRIGGER • CREATE TYPE • CREATE TYPE BODY 输入这些命令中的任何一个都可以使其处于 PL/SQL 模式，可以在其中输入 PL/SQL 子程序。有关更多的信息 参考 KingbaseES 数据库相应的章节。 要运行 SQL 命令创建的存储过程，可以使用下面的方式： • CALL FUNCTION NAME; • SELECT FUNCTION NAME; 例如：创建名为 test 的函数并执行 -- create table tb1 CREATE TABLE tb1( a int, b int ); -- insert values INSERT INTO tb1 VALUES(1,1); INSERT INTO tb1 VALUES(2,2); -- create type create type type_tb1 as (a int, b int); -- create test() function \set SQLTERM / CREATE OR REPLACE FUNCTION test( ) RETURNS SETOF type_tb1 AS BEGIN RETURN QUERY SELECT * FROM tb1; RETURN; END; / \set SQLTERM ; 26 第4章 使用 KSQL -- call test() SELECT test(); test ------(1,1) (2,2) (2 rows) 注意: 不是每种存储过程都能通过 SQL 命令执行，比如 CREATE TRIGGER 创建的触发器是通过创建时指定的触 发条件自动被触发执行的，并不能通过 SQL 命令执行。 4.1.7 运行 Ksql 命令 您可以使用 Ksql 命令操作 SQL 命令和 PL/SQL 块，并格式化和打印查询结果。Ksql 对 Ksql 命令的处理方式 不同于 SQL 命令或 PL/SQL。例如 输入 ksql 命令： -- 将结果格式为 html \pset format html 如果输入错误的内容，可以使用 Backspace 删除它们并重新输入。 输入以下查询，然后按 ENTER 键来运行它： -- 查询 SELECT * FROM tb1; select * from tb1; 27 第4章 使用 KSQL (2 rows)
4.1.7.1 理解 Ksql 命令语法 4.1.7.1.1 元命令概述 你输入到 Ksql 中的任何以未加引用的反斜线开始的东西都是一个 Ksql 元命令，它们由 Ksql 自行处理。这些命 令让 Ksql 对管理和编写脚本更有用。元命令常常被称作斜线或者反斜线命令。 4.1.7.1.2 命令格式 Ksql 命令的格式是用反斜线后面直接跟上一个命令动词，然后是一些参数。参数与命令动词和其他参数之间用 任意多个空白字符分隔开。 要在一个参数中包括空白，可以将它加上单引号。要在一个参数中包括一个单引号，则需要在文本中写上两个单 引号。任何包含在单引号中的内容都服从与 C 语言中\n（新行）、\t（制表符）、\b（退格）、\r（回车）、\f（换 页）、\digits（10 进制）以及\xdigits（16 进制）类似的替换规则。单引号内文本中的其他任何字符（不管它是什 么）前面的反斜线都没有实际意义（会被忽略）。 如果在一个参数中出现一个未加引号的冒号（:）后面跟着一个 Ksql 变量名，它会被该变量的值替换，如SQL 中 插入变量 中所述。在其中描述的形式:’variable_name’ 和:”variable_name” 也有同样的效果。:{?variable_name} 语 法允许测试一个变量是否被定义。它会被 TRUE 或 FALSE 替换。用一个反斜线转义该冒号可以防止它被替换。 在一个参数中，封闭在反引号（`）中的文本会被当做一个传递给 shell 的命令行。该命令的输出（移除任何拖尾 的新行）会替换反引号文本。在封闭在反引号的文本中，不会有特别的引号或者其他处理发生，:variable_name 的 出现除外，其中 variable_name 是一个会被其值替换的 Ksql 变量名。此外，Also,appearances of :’variable_name’ 的出现会被替换为该变量的值，而值会被适当地加以引用以变成一个单一 shell 命令参数（后一种形式几乎总是优 先，除非你非常确定变量中有什么）。因为回车和换行字符在所有的平台上都不能被安全地引用，:’variable_name’ 形式会打印一个错误消息并且在这类字符出现在值中时不替换该变量值。 有些命令把 SQL 标识符（例如一个表名）当作参数。这些参数遵循 SQL 的语法规则：无引号的字母被强制变为 小写，而双引号（"）可以保护字母避免大小写转换并且允许在标识符中包含空白。 在 双 引 号 内， 成 对 的 双 引 号 会 被 缩 减 为 结 果 名 称 中 的 单 个 双 引 号。 例 如，FOO"BAR"BAZ 会被解释成 fooBARbaz，而"A weird"" name" 会变成 A weird" name。 对参数的解析会在行尾或者碰到另一个未加引号的反斜线时停止。一个未加引号的反斜线被当做新元命令的开 始。特殊的序列\\（两个反斜线）表示参数结束并且应继续解析 SQL 命令（如果还有）。使用这种方法，SQL 命 令和 Ksql 命令可以被自由地混合在一行中。但是无论在何种情况中，元命令的参数都无法跨越一行。 很多元命令作用在当前查询缓冲区上。这就是一个缓冲区而已，它保存任何已经被键入但是还没有发送到服务器 执行的 SQL 命令文本。这将包括之前输入的行以及在该元命令同一行上出现在前面的任何文本。 28 第4章 使用 KSQL 4.1.7.1.3 命令行编辑 为了方便的进行编辑和检索，Ksql 支持 Readline 库。Ksql 退出时命令历史会被自动保存，而当 Ksql 启动时命 令历史会被重新载入。Ksql 也支持 tab 补全，不过补全逻辑绝不是一个 SQL 解析器。tab 补全产生的查询也可能会 受其他 SQL 命令干扰，例如 SET TRANSACTION ISOLATION LEVEL。如果出于某种原因不想用 tab 键补全，可以把 下面的代码放在主目录下的名为.inputrc 文件中关闭该特性： $if ksql set disable-completion on $endif （这不是 Ksql 特性而是 Readline 的特性。进一步的细节请阅读它的文档。） 4.1.7.1.4 命令提示符 Ksql 发出的提示符可以根据用户的喜好自定义。PROMPT1、PROMPT2 和 PROMPT3 这三个变量包含了描述提示符 外观的字符串和特殊转义序列。Prompt1 是当 Ksql 等待新命令时发出的常规提示符。Prompt 2 是在命令输入时需 要更多输入时发出的提示符，例如当命令没有被分号终止或者引用没有被关闭时就会发出这个提示符。在运行一个 SQL“COPY FROM STDIN“命令并且需要在终端上输入一个行值时，会发出 Prompt 3。 被选中的提示符变量会被原样打印，除非碰到一个百分号（%）。百分号的下一个字符会被特定的其他文本替 换。预定义好的替换有： %M 数据库服务器的完整主机名（带有域名），或者当该连接是建立在一个 Unix 域套接字上时则是 [local]，或者当 Unix 域套接字不在编译系统内的默认位置上时则是 [local:/dir/name]。 %m 数据库服务器的主机名称（在第一个点处截断），或者当连接建立在一个 Unix 域套接字上时是 [local]。 %> 数据库服务器正在监听的端口号。 %n 数据库会话的用户名（在数据库会话期间，这个值可能会因为命令 SET SESSION AUTHORIZATION 的结果 而改变）。 %/ 当前数据库的名称。 %~ 和%/类似，但是如果数据库是默认数据库时输出是 ~（波浪线）。 %# 29 第4章 使用 KSQL 如果会话用户时一个数据库超级用户，则是 #，否则是一个>（在数据库会话期间，这个值可能会因为命 令 SET SESSION AUTHORIZATION 的结果而改变）。 %p 当前连接到的后端的进程 ID。 %R 在提示符 1 下通常是 =，但如果会话位于一个条件块的一个非活动分支中则是 @，如果会话处于单行模式 中则是 ^，如果会话从数据库断开连接（\connect 失败时会发生这种情况）则是!。在提示符 2 中，根据 为什么 Ksql 期待更多的输入，%R 会被一个相应的字符替换：如果命令还没有被终止是-，如果有一个未 完的注释则是 *，如果有一个未完的被引用字符串则是一个单引号，如果有一个未完的被引用 标识符则是一个双引号，如果有一个未完的美元引用字符串则是一个美元符号，如果有一个还没有被配对 的左圆括号则是 (。在提示符 3 中%R 不会产生任何东西。 %x 事务状态：当不在事务块中时是一个空字符串，在一个事务块中时是 *，在一个失败的事务块中时是!， 当事务状态是未判定时（例如因为没有连接）为?。 %l 当前语句中的行号，从 1 开始。 %digits 带有指定的八进制码的字符会被替换。 %:name: Ksql 变量 name 的值。详见变量 。 :literal:`%\command` command 的输出，类似于平常的“反引号”替换。 %[ ... %] 提示符可以包含终端控制字符，例如改变提示符文本的颜色、背景或者风格以及更改终端窗口标题的控制 字符。为了让 Readline 的行编辑特性正确工作，这些不可打印的控制字符必须被包裹在%[和%] 之间以指 定它们是不可见的。在提示附中可以出现多个这样的标识对。例如： testdb=> \set PROMPT1 '%[%033[1;33;40m%]%n@%/%R%[%033[0m%]%# ' 会导致一个在兼容 VT100 的彩色终端上的粗体（1;）的、黑底黄字（33;40）的提示符。 要在你的提示符中插入一个百分号，可以写成%%。提示符 1 和 2 的默认提示是'%/%R%# '，提示符 3 的提示是'>> '。 例如，现在我们把提示符改一改： testdb=> \set PROMPT1 '%n@%m %~%R%# ' peter@localhost testdb=> 30 第4章 使用 KSQL 注意: Windows 环境下不支持该功能。 变量 4.1.8 Ksql 提供了和普通 Unix 命令 shell 相似的变量替换特性。变量简单来说就是一对名称/值，其中值可以是任意长 度的任意字符串。名称必须由字母（包括非拉丁字母）、数字和下划线构成。 要设置一个变量，可以使用 Ksql 的元命令\set。例如： testdb=> \set foo bar 会设置 foo 为值 bar。要检索该变量的内容，可以在名称前放一个冒号，例如： testdb=> \echo :foo bar 这在常规 SQL 命令和元命令中均有效，下文的SQL 中插入变量 中有更多细节。 如果调用\set 时没有第二个参数，该变量会被设置为一个空字符串值。要重置（即删除）一个变量，可以使用 命令\unset。要显示所有变量的值，在调用\set 时不带任何参数即可。 注意: \set 的参数服从与其他命令相同的替换规则。因此可以构造有趣的引用，例如\set :foo 'something'以及 分别得到 Perl 或者 PHP 的“软链接”或者“可变变量”。这些构造出来的东西并没有什么用处。在另一方面，\set bar :foo 是一种很好的拷贝变量的方法。 有一些变量会被 Ksql 特殊对待。它们表示特定的选项设置，运行时这类选项设置可以通过修改该变量的值来改 变，或者在某些情况下它们表示 Ksql 的可更改的状态。按照惯例，所有被特殊对待的变量的名称由全部大写形式的 ASCII 字母（还有可能是数字和下划线）组成。为了确保未来最大的兼容性，最好避免使用这类变量名。 控制 Ksql 行为的变量通常不能被重置或者设置为无效值。允许\unset 命令，但它会被解释为将变量设置为它 的默认值。没有第二参数的\set 命令会被解释为将变量设置为 on（对于接受该值的控制变量），对不接受该值的 变量则会拒绝这个命令。此外，接受值 on 和 off 的控制变量也能接受其他常见的布尔值拼写方式，例如 true 和 false。 被特殊对待的变量是： AUTOCOMMIT 在被设置为 on（默认）时，每一个 SQL 命令在成功完成时会被自动提交。在这种模式中要推迟提交， 必须输入一个 BEGIN 或者 START TRANSACTION SQL 命令。当被设置为 off 或者被重置时，在显式发出 COMMIT 或者 END 之前，SQL 命令不会被提交。自动提交打开模式会为你发出一个隐式的 BEGIN，在任 何尚未在事务块中且本身即不是 BEGIN 或其他事务控制命令，也不是无法在事务块中执行的命令（例如 VACUUM）之前。 31 第4章 注意: 使用 KSQL 在自动提交关闭模式中，必须通过 ABORT 或者 ROLLBACK 显式地放弃任何失败的事务。还要记 住，如果退出会话时没有提交，则所有的工作都会丢失。 注意: 自动提交打开模式是 KingbaseES 的传统行为，但是自动提交关闭模式更接近于 SQL 的规范。如 果更喜欢自动提交关闭模式，可以在系统级的 ksqlrc 文件或者个人的 ~/.ksqlrc 文件中设置它。 COMP_KEYWORD_CASE 确定在补全一个 SQL 关键词时要使用的大小写形式。如果被设置为 lower 或者 upper，补全后的词将分 别是小写或者大写形式。如果被设置为 preserve-lower 或者 preserve-upper（默认），补全后的词将 会保持该词已输入部分的大小写形式，但是如果被补全的词还没有被输入，则它会被分别补全成小写或者 大写形式。 DBNAME 当前已连接的数据库名称。每次连接到一个数据库时都会设置该变量（包括程序启动时），但是可以被更 改或者重置。 ECHO 如果被设置为 all，所有非空输入行会被按照读入它们的样子打印到标准输出（不适用于交互式读取的 行）。要在程序开始时选择这种行为，可以使用开关-a。如果被设置为 queries，Ksql 会在发送每个查 询给服务器时将它们打印到标准输出。选择这种行为的开关是-e。如果被设置为 errors，那么只有失败 的查询会被显示在标准错误输出上。这种行为的开关是-b。如果被重置或者设置为 none（默认值）则不 会显示任何查询。 ECHO_HIDDEN 当这个变量被设置为 on 且一个反斜线命令查询数据库时，相应的查询会被先显示。这种特性可以帮助我 们学习 KingbaseES 的内部并且在自己的程序中提供类似的功能（要在程序开始时选择这种行为，可以使 用开关-E）。如果把这个变量设置为值 noexec，则对应的查询只会被显示而并不真正被发送给服务器执 行。默认值是 off。 ENCODING 当前的客户端字符集编码。每一次你连接到一个数据库（包括程序启动）时以及当你用\encoding 更改编 码时，这个变量都会被设置，但它可以被更改或者重置。 ERROR 如果上一个 SQL 查询失败则为 true，如果成功则是 false。另见 SQLSTATE。 FETCH_COUNT 如果这个变量被设置为一个大于零的整数值，SELECT 查询的结果会以一组一组的方式取出并且显示（而 不是像默认的那样把整个结果集拿到以后再显示），每一组就会包括这么多个行。因此，这种方式只会使 32 第4章 使用 KSQL 用有限的内存量，而不管整个结果集的大小。在启用这个特性时，通常会使用 100 到 1000 的设置。记住 在使用这种特性时，一个查询可能会在已经显示了一些行之后失败。 提示: 尽管可以把这种特性用于任何的输出格式，但是默认的 aligned 格式看起来会比较糟糕，因为 每一组的 FETCH_COUNT 个行将被单独格式化，这就会导致不同的行组的列宽不同。其他的输出格式会更 好。 HIDE_TABLEAM 如果将该变量设置为 true，则不会显示表的访问方法详细信息。这主要用于回归测试。 HISTCONTROL 如果这个变量被设置为 ignorespace，则以一个空格开始的行不会被放入到历史列表中。如果被设置为 值 ignoredups，则匹配之前的历史行的行不会被放入。值 ignoreboth 组合了上述两种值。如果被重置 或者被设置为 none（默认值），所有在交互模式中被读入的行都会保存在历史列表中。 HISTFILE 该文件名将被用于存储历史列表。如果被重设，文件名将从 KSQL_HISTORY 环境变量中取得。如果 该环境变量也没有被设置，则默认值是 ~/.ksql_history，在 Windows 上是%APPDATA%\kingbase\ ksql_history。例如， \set HISTFILE ~/.ksql_history- :DBNAME 放在 ~/.ksqlrc 中将会导致 Ksql 为每一个数据库维护一个单独的历史。 HISTSIZE 存储在命令历史中的最大命令数（默认值是 500）。如果被设置为一个负值，则不会应用限制。 HOST 当前连接到的数据库服务器端口。每次连接到一个数据库时都会设置该变量（包括程序启动时），但是可 以被更改或者重置。 IGNOREEOF 如果被设置为 1 或者更小，向一个 Ksql 的交互式会话发送一个 EOF 字符（通常是 Control+D）将会终 止应用。如果设置为一个较大的数值，则必须键入多个连续的 EOF 字符才能让交互式会话终止。如果该 变量被设置为一个非数值，则它会被解释为 10。默认值为 0。 LASTOID 最后被影响的 OID 的值，这可能会由 INSERT 或者\lo_import 命令返回。这个变量只保证在下一个 SQL 命令被显示完之前有效。由于 KingbaseES V9 版本服务器不再支持 OID 系统列，所以 LASTOID 在针对 这类服务器时在 INSERT 之后将始终是 0。 LAST_ERROR_MESSAGE LAST_ERROR_SQLSTATE 33 第4章 使用 KSQL 当前 Ksql 会话中最近一个失败查询的主错误消息和相关的 SQLSTATE 代码，如果在当前会话中没有发 生错误，则是一个空字符串和 00000。 ON_ERROR_ROLLBACK 当被设置为 on 时，如果事务块中的一个语句产生一个错误，该错误会被忽略并且该事务会继续。当被设 置为 interactive 时，只在交互式会话中忽略这类错误，而读取脚本文件时则不会忽略错误。当被重置 或者设置为 off（默认值）时，事务块中产生错误的一个语句会中止整个事务。错误回滚模式的工作原理 是在事务块的每个命令之前都为你发出一个隐式的 SAVEPOINT，然后在该命令失败时回滚到该保存点。 ON_ERROR_STOP 默认情况下，出现一个错误后命令处理会继续下去。当这个变量被设置为 on 后，出现错误后命令处理会 立即停止。在交互模式下，ksql 将会返回到命令提示符；否则，ksql 将会退出并且返回错误代码 3 来把这 种情况与致命错误区分开来，致命错误会被报告为错误代码 1。在两种情况下，任何当前正在运行的脚本 （顶层脚本以及任何它已经调用的其他脚本）将被立即中止。如果顶层命名字符串包含多个 SQL 命令， 将在当前命令处停止处理。 PORT 当前连接到的数据库服务器端口。每次连接到一个数据库时都会设置该变量（包括程序启动时），但是可 以被更改或者重置。 PROMPT1 PROMPT2 PROMPT3 这些变量指定 Ksql 发出的提示符的模样。见下文的 提示符。 QUIET 把这个变量设置为 on 等效于命令行选项-q。在交互模式下可能用处不大。 ROW_COUNT 上一个 SQL 查询返回的行数或者受影响的行数，如果该查询失败或者没有报告行计数则为 0。 SERVER_VERSION_NAME SERVER_VERSION_NUM 字符串形式的服务器版本号，例如 V8R2、10.1 或者 11beta1，以及数字形式的服务器版本号，例如 90602 或者 100001。每次你连接到一个数据库（包括程序启动）时，这些都会被设置，但可以被改变或 者重设。 SHOW_CONTEXT 这个变量可以被设置为值 never、errors 或者 always 来控制是否在来自服务器的消息中显示 “CONTEXT“域。 默 认 是 errors（表 示 在 错 误 消 息 中 显 示 上 下 文， 但 在 通 知 和 警 告 消 息 中 不 显 示）。 当 VERBOSITY 被设置为 terse 或者 sqlstate 时，这个设置无效（另见\errverbose，它可以用来得到刚 遇到的错误的详细信息）。 SINGLELINE 设置这个变量为 on 等效于命令行选项-S。 SINGLESTEP 34 第4章 使用 KSQL 设置这个变量为 on 等效于命令选项-s。 SQLSTATE 与上一个 SQL 查询的失败相关的错误代码（见 KingbaseES 错误代码)，如果上一个查询成功则为 00000。 USER 当前连接的数据库用户。每次连接到一个数据库时都会设置该变量（包括程序启动时），但是可以被更改 或者重置。 VERBOSITY 这个变量可以被设置为值 default、verbose、terse 或者 sqlstate 来控制错误报告的详细程度（另 见\errverbose，在想得到之前的错误的详细版本时使用）。 VERSION VERSION_NAME VERSION_NUM 这些变量在程序启动时被设置以反映 Ksql 的版本，分别是一个详细的字符串、一个短字符串（例如 V8R2、10.1 或者 11beta1）以及一个数字（例如 90602 或者 100001）。它们可以被更改或重设。 WHENEVER_SQLERROR 此变量为兼容 Oracle SQL*Plus 语法的 Whenever sqlerror 语法增加的变量，可以被设置为 continue（默 认）或者 exit。默认情况下，出现一个错误后命令处理会继续下去。当这个变量被设置为 exit 后，出 现错误后命令处理会立即停止，Ksql 将会退出并且返回错误代码 3 来把这种情况与致命错误区分开来， 致命错误会被报告为错误代码 1。任何当前正在运行的脚本（顶层脚本以及任何它已经调用的其他脚本） 将被立即中止。如果顶层命名字符串包含多个 SQL 命令，将在当前命令处停止处理。 4.1.9 停止正在运行的任务 假设您执行了一个结果集较大的查询任务，查询结果已经显示了一部分，但并不需要查看其余部分内容，这时可 以使用 Ctrl + C 命令，Ksql 将停止显示。 4.1.10 运行操作系统命令 可以从 Ksql 命令提示符中执行操作系统命令，当您想要执行诸如列出现有操作系统文件等任务时，这一点非常 的有用。 要运行操作系统命令，请输入 Ksql 命令 \! , 然后输入操作系统命令。例如： -- 查看当前所在位置的系统文件 test=# \! ls code data2 logfile ... 35 第4章 使用 KSQL 自动保存对数据库的更改 4.1.11 可以使用 SQL 数据库操作语言 (DML) 命令更新、插入和删除来指定您希望对存储在数据库中的数据信息所做 的更改，这些更改可以单独的使用，也可以在 PL/SQL 块中使用。在输入 SQL 提交命令或 SQL 数据库控制语言 (DCL) 或数据库定义语言 (DDL) 命令 (如创建表) 或使用自动提交功能之前，这些更改不会永久的保存。Ksql 自动 提交特性会导致 SQL DML 事务成功之后的更改被永久的保存到数据库。 您可以使用 Ksql 自动提交系统变量 AUTOCOMMIT 来控制自动提交功能。默认情况下，kingbase 数据库的自动提 交是开启的，也就是说任何一个 SQL 语句执行完成后，所做的数据修改都会被立刻提交，这种情况下每个语句都是 一个独立事务。 注意: 自动提交功能提交开启时，无法回滚对数据的修改。 查看自动提交功能是否开启 test=# \echo :AUTOCOMMIT on 设置自动提交功能开启或关闭 test=# \set AUTOCOMMIT on/off 显示详细错误信息 4.1.12 如果 Ksql 在命令中检测到错误，则会显示错误信息。您通常将能够单独从消息中找到如何纠正这个问题的方 式。例如： test=# SELECT * FROM t2; ERROR: relation "t2" does not exist LINE 1: SELECT * FROM t2; 可以使用 \errverbose 命令显示最近的服务器错误信息。例如： test=# \errverbose ERROR: 42P01: relation "t2" does not exist LINE 1: SELECT * FROM t2; ^ LOCATION: parserOpenTable, parse_relation.c:1244 4.1.12.1 Oracle 兼容 为兼容 Oracle SQL*Plus 工具的 Whenever sqlerror 语法功能，Ksql 也支持此语法。语法定义为： 36 第4章 WHENEVER SQLERROR { EXIT | CONTINUE 使用 KSQL } EXIT 选项：表示当遇到 SQL 错误、PLPGSQL 块错误、PLSQL 块错误或者错误的 Ksql 反斜线命令，将会退出 Ksql。 CONTINUE 选项（默认值）：表示当遇到 SQL 错误、PLPGSQL 块错误、PLSQL 块错误或者错误的 Ksql 反斜线命令，不会退出 Ksql。 4.2 Ksql 执行脚本 \i or \include filename 命令从文件 filename 读取输入并且把它当作从键盘输入的命令来执行。例如： 在操作系统当前目录中创建一个脚本文件 test.sql, 输入以下语句： CREATE TABLE t1 ( a int, b int ); INSERT INTO t1 VALUES(1,1); INSERT INTO t1 VALUES(2,2); SELECT * FROM t1; ksql 中输入以下命令执行 test.sql 文件： test=# \i test.sql CREATE TABLE INSERT 0 1 INSERT 0 1 a | b ---+--1 | 1 2 | 2 (2 rows) 4.2.1 启动 Ksql 时运行一个脚本 若要在启动 Ksql 时运行脚本，使用以下选项： • -f filename 从文件 filename 而不是标准输入中读取命令。（详见 option 选中 -f） 例如：按照 Ksql 命令，使用用户名，目标数据库以及将要执行的文件名字。例如： 37 第4章 使用 KSQL [test@kes_35_14 ~]$ ksql -p54320 -d test -f test.sql INSERT 0 1 INSERT 0 1 a | b ---+--1 | 1 2 | 2 1 | 1 2 | 2 1 | 1 2 | 2 (6 rows) 4.3 SQL 中插入变量 Ksql 变量的一个关键特性是可以把它们替换（“插入”）到常规 SQL 语句中，也可以把它们作为元命令的参 数。此外，Ksql 还提供了功能来确保被用作 SQL 文字和标识符的变量值会被正确地引用。插入一个值而不需要加引 用的语法是在变量名前面加上一个冒号（:）。例如: testdb=> \set foo 'my_table' testdb=> SELECT * FROM :foo; 将查询表 my_table。注意这可能会不安全：该变量的值会被按字面拷贝，因此它可能包含不平衡的引号甚至反 斜线命令。必须确保把它放在那里是有意义的。 当一个值被用作 SQL 文本或者标识符时，最安全的是把它加上引用。要引用一个变量的值作为 SQL 文本，可以 把变量名称放在单引号中并且在引号前面写一个冒号。要引用作为 SQL 标识符，则可以把变量名称放在双引号中并 且在引号前面写一个冒号。这种结构可以正确地处理变量值中嵌入的引号和其他特殊字符。之前的例子用这种方法写 会更安全： testdb=> \set foo 'my_table' testdb=> SELECT * FROM :"foo"; 在被引用的 SQL 文本和标识符中将不会执行变量插入。因此，一个诸如':foo'的结构不会从一个变量的值产生 一个被引用的文本（即便能够也会不安全，因为无法正确地处理嵌入在值中的引号）。 使用这种机制的一个例子是把一个文件的内容拷贝到一个表列中。首先把该文件载入到一个变量，然后把该变量 的值作为一个被引用的字符串插入： -- linux environment testdb=> \set content `cat my_file.txt` -- windows environment testdb=> \set content `type my_file.txt` 38 第4章 使用 KSQL testdb=> INSERT INTO my_table VALUES (:'content'); 注意: • 注意如果 my_file.txt 包含 NULL 字节，这样也不行。Ksql 不支持在变量值中嵌入 NULL 字节; • Windows 环境下应该使用 type 命令代替 Linux 环境下的 cat 命令; 因为冒号可以合法地出现在 SQL 命令中，一次明显的插入尝试（即:name、:'name'或者:"name"）不会被替 换，除非所提及的变量就是当前被设置的。在任何情况下，可以用一个反斜线对冒号进行转义以避免它被替换。 :{?name} 特殊语法根据该变量存在与否返回 TRUE 或者 FALSE，并且因此总是会被替换，除非分号被反斜线 转义。 变量的冒号语法对嵌入式查询语言（例如 ESQL）来说是标准的 SQL。用于数组切片和类型造型的冒号语法是 KingbaseES 扩展，它有时可能会与标准用法冲突。把一个变量值转义成 SQL 文本或者标识符的冒号引用语法是一种 Ksql 扩展。 4.4 格式化 Ksql 输出 4.4.1 设置输出格式 Ksql 支持 aligned、csv、html、asciidoc 等不同的输出格式，可以使用 \pset format 命令设置结果的输出格 式。例如： peter@localhost testdb=> \a \t \x Output format is aligned. Tuples only is off. Expanded display is on. peter@localhost testdb=> SELECT * FROM my_table; -[ RECORD 1 ]first | 1 second | one -[ RECORD 2 ]first | 2 second | two -[ RECORD 3 ]first | 3 second | three -[ RECORD 4 ]- 39 第4章 使用 KSQL first | 4 second | four 您可以用 \pset 命令以不同的方式显示表, 例如： peter@localhost testdb=> \pset border 2 Border style is 2. peter@localhost testdb=> SELECT * FROM my_table; +-------+--------+ | first | second | +-------+--------+ | 1 | one | | 2 | two | | 3 | three | | 4 | four | +-------+--------+ (4 rows) peter@localhost testdb=> \pset border 0 Border style is 0. peter@localhost testdb=> SELECT * FROM my_table; first second ----- ------ 1 one 2 two 3 three 4 four (4 rows) peter@localhost testdb=> \pset border 1 Border style is 1. peter@localhost testdb=> \pset format csv Output format is csv. peter@localhost testdb=> \pset tuples_only Tuples only is on. peter@localhost testdb=> SELECT second, first FROM my_table; one,1 two,2 three,3 four,4 peter@localhost testdb=> \pset format unaligned Output format is unaligned. peter@localhost testdb=> \pset fieldsep '\t' Field separator is " ". peter@localhost testdb=> SELECT second, first FROM my_table; 40 第4章 使用 KSQL one 1 two 2 three 3 four 4 4.4.2 定义打印的标题 设置用于任何后续被打印表的表标题，可以使用 title 命令。这可以用来给输出加上描述性的标签。如果没有给 出标题，这个标题会被复原。例如： test=# \pset title 'This is test function' Title is "This is test function". test=# select * from test(); This is test function a | b ---+--1 | 1 2 | 2 3 | 3 (3 rows) 4.4.3 存储和打印查询结果 要将查询结果存储到文件，可以在 Ksql 中输入 `\o or \out [ filename ] 命令（详见 \o）。例如： test=# \o a.txt test=# SELECT * FROM t1; test=# \o 提示: 更多有关输出格式的设置参考 \pset 命令。 4.4.4 \r 显示风格 当 Ksql 设置输出格式为 aligned 和 wrapped 时，如果已经连接到 ORACLE 模式的 KingbaseES 服务端，那 么对于\r(0x13 字节) 的显示将会兼容 Oracle 的显示风格，即遇到\r 会将光标插入符移到行首，后面输入的字符可能 会覆盖已经打印输出的字符。比如下面的用例： testdb=# create table tb(vc varchar(20)); CREATE TABLE 41 第4章 使用 KSQL testdb=# insert into tb values ('abc' || chr(13) || '12'); INSERT 0 1 testdb=# select * from tb; vc ----12c (1 row) testdb=# 而 Ksql 连接到 PG 模式的 KingbaseES 服务端时，将显示为\r 字符。依旧使用上面的用例输出结果如下为： testdb=# select * from tb; vc --------abc\r12 (1 row) testdb=# 注意: 在兼容 ORACLE 显示格式时的使用限制或已知问题： 1. 可能在某些字符集情况下会出现显示乱码的情况。 2. 某些包含\r 的列显示宽度可能会和其他列不一致。 4.5 生成 HTML 要想将查询结果生成 HTML 格式，可以使用以下的方式： • 使用 \pset format html • 使用 \H or \html 命令开启 HTML 查询输出格式，如果 HTML 格式已经开启，这会把它切换回默认的对齐文 本格式。 test=# \H Output format is html. (6 rows)
4.6 Ksql 调优 4.6.1 统计 SQL 执行时间 使用 Ksql 的 \timing 命令显示运行一个或多个命令块执行的时间。例如： test=# \timing on Timing is on. test=# SELECT * FROM t1; a | b ---+--1 | 1 2 | 2 1 | 1 2 | 2 1 | 1 2 | 2 (6 rows) Time: 1.767 ms 4.6.2 输出执行计划 使用 EXPLAIN 命令生成执行计划的输出。例如： test=# EXPLAIN SELECT * FROM t1 ORDER BY a; QUERY PLAN -----------------------------------------------------------Sort (cost=158.51..164.16 rows=2260 width=8) Sort Key: a 43 第4章 -> Seq Scan on t1 使用 KSQL (cost=0.00..32.60 rows=2260 width=8) (3 rows) Time: 1.115 ms 执行计划显示基于成本的行数估计 (基数)。一般来说，每个节点上的代价、基数和字节表示累积的结果。 4.7 Ksql 安全 4.7.1 创建和控制角色 您可以使用 SQL 命令来创建和控制对角色的访问，从而为数据库表提供安全性。通过创建一个角色，然后设定 访问的权限，可以确保只有特定的用户可以访问特定数据库的权限。 角色将与 SQL 的 CREATE、GRANT 和 SET 命令一起使用： • 若要创建角色，请使用 CREATE 命令。您可以使用或不使用密码创建角色 • 若要授予对角色的访问权限，请使用 GRANT 命令。通过这种方式，您可以控制与该角色相关联的权限 • 若要访问角色，请使用 SET ROLE 命令。如果您使用密码创建了该角色，则用户必须知道密码才能访问该角色 例如：创建名字为 USER1 的用户并设置对应的访问权限 -- CREATE user CREATE ROLE USER1 SUPERUSER PASSWORD '123456' login; -- GRANT PRIVILEGES GRANT ALL PRIVILEGES ON DATABASE test TO USER1; -- SET ROLE session_user | current_user --------------+-------------peter | peter SET ROLE 'paul'; SELECT SESSION_USER, CURRENT_USER; session_user | current_user --------------+-------------peter | paul 44 第4章 使用 KSQL 提示: 详细的命令请参考 KingbaseES SQL 语言参考手册。 45 第 5 章 KSQL 命令参考 5 第 章 Ksql 命令参考 本章包含了按字母顺序列出的 Ksql 命令的描述。每个描述了如何输入该命令的语法，并简要描述了该命令的基 本用途。 5.1 a \a 如果当前的表输出格式是非对齐的，则切换成对齐格式。如果不是非对齐格式，则设置成非对齐格式。保 留这个命令是为了向后兼容性。更一般的方案请见\pset。 例子： test# \a Output format is unaligned. test=# select * from t1; a|b|c|d 1|2|hello world!|3 4|5|bei jing huan ying nin|6 test=# \a Output format is aligned. test=# select * from t1; a | b | c | d ---+---+------------------------+--1 | 2 | hello world! | 3 4 | 5 | bei jing huan ying nin | 6 5.2 c \c or \connect [ -reuse-previous=on|off ] [ dbname [ username ] [ host ] [ port ] | conninfo ] 46 第 5 章 KSQL 命令参考 与一台 KingbaseES 服务器建立一个新连接。可以使用位置语法指定要使用的连接参数。 在省略了数据库名、用户、主机或者端口的命令中，新的连接将会重用之前一个连接的值。默认情况下， 前一个连接的值将会被重用，除非给出了一个 conninfo 串。给出第一个参数 -reuse-previous=on 或 者 -reuse-previous=off 可以覆盖默认行为。当这个命令既没有指定一个参数也没有重用它时，将使用 libkci 的默认值。把 dbname、username、host 或者 port 中的任何一个指定为-等价于省略该参数。如果 在原始连接的 conninfo 中指定了 hostaddr，则该地址将被新连接重用 (不考虑任何其他主机规范)。 如果新连接成功地被建立，之前的连接会被关闭。如果连接尝试失败（错误的用户名、访问被拒绝等）， 只有在 Ksql 处于交互模式的情况下才会保留之前的连接。当执行一个非交互式脚本时出现连接尝试失 败，处理将被立即停止，并且报出一个错误。这种区别一方面可以帮助用户发现打字错误，另一方面也可 以作为一种安全机制防止脚本在错误的数据库上执行动作。 例子： => \c mydb myuser host.dom 6432 => \c service=foo => \c "host=localhost port=54321 dbname=mydb connect_timeout=10 sslmode=disable" => \c kingbase://tom@localhost/mydb?application_name=myapp 5.3 C \C [ title ] 设置查询结果的任何表的标题，或者重置这类标题。这个命令等效于\pset title title（这个命令的名 称来自于“caption”，因为它之前只被用来在 HTML 表格中设置标题）。 5.4 directory \cd [ directory ] 把当前工作目录改为 directory。如果不带参数，则切换到当前用户的主目录。 提示: 要打印当前的工作目录，可以使用\! pwd。 注意: Windows 环境下，如果切换的目标目录建议使用引号引起来，否则目标目录不能被正确的解析。 例如： 47 第 5 章 KSQL 命令参考 ksql=# \cd 'C:\\Windows' ksql=# \! chdir C:\Windows 5.5 conninfo \conninfo 输出有关当前数据库连接的信息。 5.6 copy command \copy { table [ ( column_list ) ] | ( query ) } { from | to } { 'filename' | program 'command' | stdin | stdout | pstdin | pstdout } [ [ with ] ( option [, ...] ) ] 执行一次前端拷贝。这个操作会运行一个 SQL COPY 命令，不过不是服务器读取或者写入指定的文件， 而是由 Ksql 读写文件并且把数据从本地文件系统导向服务器。这意味着文件的可访问性和权限是本地用 户的而非服务器上的，并且不需要 SQL 超级用户特权。 当 program 被指定时，command 被 Ksql 执行并且传给 command 的数据或者从 command 传出的数据会在 服务器和客户端之间流动。同样地，执行特权是本地用户的而非服务器上的，并且不需要 SQL 超级用户 特权。 对于\copy ... from stdin，数据行从发出该命令的同一来源读取，一直到读到\. 或者数据流到达 EOF。这个选项可以用来填充内嵌在一个 SQL 脚本文件中的表。对于\copy ... to stdout，输出被发 送到与 Ksql 命令输出相同的位置，并且 COPY count 命令的状态不会被打印（因为它会被一个数据行搞 乱）。要读/写 Ksql 的标准输入或者输出而不管当前命令的来源或者\o 选项，可以写 from pstdin 或者 to pstdout。 这个命令的语法和 SQL COPY 命令类似。所有除开数据来源/目的地的选项都和 COPY 指定的一样。 因此，\copy 元命令由特殊的解析规则。与大部分其他元命令不同，该行的所有剩余部分总是会被当做\ copy 的参数，并且在参数中不会执行变量篡改以及反引号展开。 提示: 获得与\copy ... to 相同结果的另一种方法是使用 SQLCOPY ... TO STDOUT 命令并使用\g filename 或\ g | program 终止它。与 \copy 不同，此方法允许命令跨越多行; 此外，可以使用变量插 值和反引号扩展。 提示: 这些操作不如带有文件或程序数据源或目标的 SQL COPY 命令有效，因为所有数据都必须通过客户 48 第 5 章 KSQL 命令参考 端/服务器连接。对于大量数据，SQL 命令可能更可取。 5.7 copyright \copyright 显示 KingbaseES 的版权以及发布条款。 5.8 crosstabview \crosstabview [ colV [ colH [ colD [ sortcolH ] ] ] ] 执行当前的查询缓冲区（像\g 那样）并且在一个交叉表格子中显示结果。该查询必须返回至少三列。由 colV 标识的输出列会成为垂直页眉并且 colH 所标识的输出列会成为水平页眉。colD 标识显示在格子中 的输出列。sortcolH 标识用于水平页眉的可选的排序列。 每一个列说明可以是一个列编号（从 1 开始）或者一个列名。常用的 SQL 大小写折叠和引用规则适用于 列名。如果省略，colV 被当做列 1 并且 colH 被当做列 2。colH 必须和 colV 不同。如果没有指 colD， 那么在查询结果中必须正好有三列，并且 colV 和 colH 之外的那一列会被当做 colD。 垂直页眉显示为最左边的列，它包含列 colV 中找到的值，值的顺序和查询结果中的顺序相同，但是重复 值会被移除。 水平页眉显示为第一行，它包含列 colH 中找到的值，其中的重复值被移除。默认情况下，这些值会以查 询结果中相同的顺序出现。但是如果给出了可选的 sortcolH 参数，它标识一个值必须为整数编号的列， 并且来自 colH 的值将会根据相应的 sortcolH 值排序后出现在水平页眉中。 在交叉表格子中，对于 colH 的每一个可区分的值 x 以及 colV 的每一个可区分的值 y，位于交叉点 (x, y) 的单元包含 colH 值为 x 且 colV 值为 y 的查询结果行中 colD 列的值。如果没有这样的行，则该单 元为空。如果有多个这样的行，则会报告一个错误。 例如，可以用 crosstabview 命令以交叉表的形式显示查询结果： testdb=> SELECT first, second, first > 2 AS gt2 FROM my_table; first | second | gt2 -------+--------+----1 | one | f 2 | two | f 3 | three | t 4 | four | t (4 rows) testdb=> \crosstabview first second 49 第 5 章 KSQL 命令参考 first | one | two | three | four ------+-----+-----+-------+-----1 | f | | | 2 | | f | | 3 | | | t | 4 | | | | t (4 rows) 5.9 d[S+] \d[S+] [ pattern ] 对于每一个匹配 pattern 的关系（表、视图、物化视图、索引、序列或者外部表）或者组合类型，显示所 有的列、它们的类型、表空间（如果非默认表空间）以及任何诸如 NOT NULL 或者默认值的特殊属性。相 关的索引、约束、规则以及触发器也会被显示。对于外部表，还会显示相关的外部服务器（下文的 模式 中定义了“匹配模式”）。 对于某些类型的关系，\d 会为每一列显示额外的信息：对于序列会显示列值，对于索引显示被索引的表 达式，对于外部表显示外部数据包装器选项。 命令形式\d+ 是一样的，不过会显示更多信息：与该表的列相关的任何注释，表中是否存在 OID，如果关 系是视图则显示视图定义，非默认的 replica identity 设置。 默认情况下只会显示用户创建的对象，提供一个模式或者 S 修饰符可以把系统对象包括在内。 注意: 如果使用\d 但不带有 pattern 参数，它等价于\dtvmsE，后者将显示所有可见的表、视图、物化 视图、序列和外部表的列表。这纯粹是一种便利措施。 5.10 da[S] \da[S] [ pattern ] 列出聚集函数，以及它们的返回类型和它们所操作的数据类型。如果指定了 pattern ，只显示名称匹配 该模式的聚集。默认情况下只会显示用户创建的对象，提供一个模式或者 S 修饰符可以把系统对象包括 在内。 5.11 dA[+] \dA[+] [ pattern ] 50 第 5 章 KSQL 命令参考 列出访问方法。如果指定了 pattern ，只显示名称匹配该模式的访问方法。如果在命令名称后面追加 +， 则与访问方法相关的处理器函数和描述也会和访问方法本身一起被列出。 5.12 db[+] \db[+] [ pattern ] 列出表空间。如果指定了 pattern ，只显示名称匹配该模式的表空间。如果在命令名称后面追加 +，则 与表空间相关的选项、磁盘上的尺寸、权限以及描述也会和表空间本身一起被列出。 5.13 dc[S+] \dc[S+] [ pattern ] 列出字符集编码之间的转换。如果指定了 pattern ，只列出名称匹配该模式的转换。默认情况下只会显示 用户创建的对象，提供一个模式或者 S 修饰符可以把系统对象包括在内。如果在命令名称后面追加 +， 则每一个对象相关的描述也会被列出。 5.14 dC[+] \dC[+] [ pattern ] 列出类型转换。如果指定了 pattern ，只列出源类型和目标类型匹配该模式的转换。如果在命令名称后 面追加 +，则每一个对象相关的描述也会被列出。 5.15 dd[S] \dd[S] [ pattern ] 显示约束、操作符类、操作符族、规则以及触发器类型对象的描述。所有其他注释可以通过那些对象类型 相应的反斜线命令查看。 \dd 显示匹配 pattern 的对象的描述，如果没有给出参数则显示合适类型的可见对象的描述。但是在任一 种情况下都只列出具有描述的对象。默认情况下只会显示用户创建的对象，提供一个模式或者 S 修饰符 可以把系统对象包括在内。 对象的描述可以用 SQL 命令 COMMENT 创建。 51 第 5 章 KSQL 命令参考 5.16 dD[S+] \dD[S+] [ pattern ] 列出域。如果指定了 pattern ，只有名称匹配该模式的域会被显示。默认情况下，只有用户创建的对象会 被显示，可以提供一个模式或者 S 修饰符以包括系统对象。如果 + 被追加到命令名称上，每一个被列出 的对象会带有其相关的权限和描述。 5.17 ddp \ddp [ pattern ] 列出默认的访问特权设置。对那些默认特权设置已经被改变得与内建默认值不同的角色（以及模式，如果 适用），为每一个角色（以及模式）显示一项。如果指定了 pattern，只列出角色名称或者模式名称匹 配该模式的项。 ALTER DEFAULT PRIVILEGES 命令被用来设置默认访问特权。在 权限中解释了显示的特权的含义。 5.18 dE \dE[S+] [ pattern ] \di[S+] [ pattern ] \dm[S+] [ pattern ] \ds[S+] [ pattern ] \dt[S+] [ pattern ] \dv[S+] [ pattern ] 在这一组命令中，字母 E、i、m、s、t 和 v 分别对应着外部表、索引、物化视图、序列、表和视图。你 可以以任何顺序指定这些字母中的任意一个或者多个，这样可以得到这些类型的对象的列表。例如，\dit 会列出索引和表。如果在命令名称后面追加 +，则每一个对象的物理尺寸以及相关的描述也会被列出。如 果指定了 pattern，只列出名称匹配该模式的对象。默认情况下只会显示用户创建的对象，提供一个模式 或者 S 修饰符可以把系统对象包括在内。 5.19 des[+] \des[+] [ pattern ] 列出外部服务器（助记：“外部服务器”）。如果指定了 pattern，只列出名称匹配该模式的那些服务 器。如果使用了 \des+ 形式，将显示每个服务器的完整描述，包括该服务器的接入权限、类型、版本、 选项和描述。 52 第 5 章 KSQL 命令参考 5.20 det[+] \det[+] [ pattern ] 列出外部表（助记：“外部表”）。如果指定了 pattern，只列出表名称或者模式名称匹配该模式的项。 如果使用了 \det+ 选项，一般选项和外部表描述也会被显示。 5.21 deu[+] \deu[+] [ pattern ] 列出用户映射（助记：“外部用户”）。如果指定了 pattern，只列出用户名匹配该模式的那些映射。如 果使用了 \deu+ 形式，有关每个映射的额外信息也会被显示。 注意: \deu+ 可能也会显示远程用户的用户名和口令，所以要小心不要把它们泄露出去。 5.22 dew[+] \dew[+] [ pattern ] 列出外部数据包装器（助记：“外部包装器”）。如果指定了 pattern，只列出名称匹配该模式的那些外 部数据包装器。如果使用了\dew+ 形式，外部数据包装器的接入权限、选项和描述也会被显示。 5.23 df \df[anptwS+] [ pattern ] 列 出 函 数， 以 及 它 们 的 结 果 数 据 类 型、 参 数 数 据 类 型 和 函 数 类 型， 函 数 类 型 被 分 为 “agg”（聚 集）、“normal”、“procedure”、“trigger” 以 及 “window”。 如 果 要 只 显 示 指 定 类 型 的 函 数， 可以在该命令上增加相应的字母 a、n、p、t 或者 w。如果指定了 pattern，只显示名称匹配该模式的函 数。默认情况下只会显示用户创建的对象，提供一个模式或者 S 修饰符可以把系统对象包括在内。如果 使用了\df+ 形式，则有关每个函数的额外信息也会被显示，包括易失性、并行安全性、拥有者、安全性 分类、访问特权、语言、源代码和描述。 提示: 如果要查找接收指定数据类型参数或者返回指定类型值的函数，可以使用分页器的搜索能力来滚动 显示\df 输出。 53 第 5 章 KSQL 命令参考 5.24 dF \dF[+] [ pattern ] 列出文本搜索配置。如果指定了 pattern ，只显示名称匹配该模式的配置。如果使用了\dF+ 形式，每种 配置的完整描述也会被显示，包括底层的文本搜索解析器和用于每一种解析器记号类型的字典列表。 5.25 dFd \dFd[+] [ pattern ] 列出文本搜索字典。如果指定了 pattern ，只显示名称匹配该模式的字典。如果使用了\dFd+ 形式，有关 每一种选中的字典的额外信息也会被显示，包括底层的文本搜索模板和选项值。 5.26 dFp \dFp[+] [ pattern ] 列出文本搜索解析器。如果指定了 pattern ，只显示名称匹配该模式的解析器。如果使用了\dFp+ 形式， 每一种解析器的完整描述也会被显示，包括底层的函数和可识别的记号类型列表。 5.27 dFt \dFt[+] [ pattern ] 列出文本搜索模板。如果指定了 pattern ，只显示名称匹配该模式的模板。如果使用了\dFt+ 形式，每一 种模板有关的额外信息也会被显示，包括底层的函数名称。 5.28 dg \dg[S+] [ pattern ] 列出数据库角色（因为“用户”和“组”的概念已经被统一成“角色”，这个命令现在等价于\du）。默 认情况下只会显示用户创建的角色，提供一个模式或者 S 修饰符可以把系统角色包括在内。如果指定了 pattern ，只列出名称匹配该模式的那些角色。如果使用了\dg+ 形式，有关每种角色的额外信息也将被 显示，当前这种形式会为角色增加显示注释。 54 第 5 章 KSQL 命令参考 5.29 dl \dl 这是\lo_list 的一个别名，它显示大对象的列表。 5.30 dL \dL[S+] [ pattern ] 列出过程语言。如果指定了 pattern ，只列出名称匹配该模式的语言。默认情况下只会显示用户创建的 语言，提供一个模式或者 S 修饰符可以把系统对象包括在内。如果向命令名称追加 +，则每一种语言会 和它的调用处理器、验证器、访问特权以及它是否为系统对象一起列出。 5.31 dn \dn[S+] [ pattern ] 列出模式（名字空间）。如果指定了 pattern ，只列出名称匹配该模式的模式。默认情况下只会显示用 户创建的对象，提供一个模式或者 S 修饰符可以把系统对象包括在内。如果向命令名称追加 +，每个对 象会与它相关的权限及描述（如果有）一起被列出。 5.32 do[S+] \do[S+] [ pattern ] 列出操作符及其操作数和结果类型。如果指定了 pattern ，只列出名称匹配该模式的操作符。默认情况 下只会显示用户创建的对象，提供一个模式或者 S 修饰符可以把系统对象包括在内。如果向命令名称追 加 +，有关每个操作符的额外信息也将被显示，当前只包括底层函数的名称。 5.33 dO[S+] \dO[S+] [ pattern ] 列出排序规则。如果指定了 pattern ，只列出名称匹配该模式的排序规则。默认情况下只会显示用户创 建的对象，提供一个模式或者 S 修饰符可以把系统对象包括在内。如果向命令名称追加 +，每个排序规 则将和它相关的描述（如果有）一起被列出。注意只有可用于当前数据库编码的排序规则会被显示，因此 在同一个安装下的不同数据库中执行此命令可能会得到不同的结果。 55 第 5 章 KSQL 命令参考 5.34 dp \dp [ pattern ] 列出表、视图和序列，包括与它们相关的访问特权。如果指定了 pattern ，只列出名称匹配该模式的表、 视图以及序列。 GRANT 和 REVOKE 命令被用来设置访问特权。所显示的特权的含义在 权限中有介绍。 5.35 dP \dP[itn+] [ pattern ] 表分区的关系。如果指定了 pattern ，则只列出名称与模式匹配的条目。可以将修饰词 t(tables) 和 i(indexes) 附加到命令中，过滤要列表的关系类型。默认情况下，列出分区的表和索引。 如果使用了修饰符 n(“nested”)，或者指定了一个模式，那么就包含了非根分区关系，并且会显示一个 列，显示每个分区关系的父元素。 如果 + 被附加到命令名，每个关系分区的大小总和也会显示出来，同时还会显示关系的描述。如果将 n 与 + 合并，则会显示两个大小: 一个是直接连接的叶子分区的总大小，另一个是所有分区的总大小，包括 间接连接的子分区。 5.36 drds \drds [ role-pattern [database-pattern ] ] 列 出 已 定 义 的 配 置 设 置。 这 些 设 置 可 以 是 针 对 角 色 的、 针 对 数 据 库 的 或 者 同 时 针 对 两 者 的。 role-pattern 和 database-pattern 分别被用来选择要列出的角色和数据库。如果省略它们或者指 定了 *，则会列出所有设置，分别会包括针对角色和针对数据库的设置。 ALTER ROLE 以及 ALTER DATABASE 命令可以用来定义一个角色以及一个数据库的配置设置。 5.37 dRp 列出复制的 publication。如果指定有 pattern ，只有那些名称匹配该模式的 publication 会被列出。如果 + 被追加到命令的名称上，与每个 publication 相关的表也会被显示。 56 第 5 章 KSQL 命令参考 5.38 dRs \dRs[+] [ pattern ] 列出复制的订阅。如果指定有 pattern ，只有那些名字匹配该模式的订阅才会被列出。如果 + 被追加到 命令的名称上，订阅的额外属性会被显示。 5.39 dT \dT[S+] [ pattern ] 列出数据类型。如果指定了 pattern ，只列出名称匹配该模式的类型。如果向命令名称追加 +，每一种 类型、其内部名称和尺寸、允许的值（如果是一种 enum 类型）以及相关权限会被一同列出。默认情况下 只会显示用户创建的对象，提供一个模式或者 S 修饰符可以把系统对象包括在内。 5.40 du \du[S+] [ pattern ] 列出数据库角色（因为“用户”和“组”的概念已经被统一成“角色”，这个命令现在等价于\dg）。默 认情况下只会显示用户创建的角色，提供一个模式或者 S 修饰符可以把系统角色包括在内。如果指定了 pattern ，只列出名称匹配该模式的那些角色。如果使用了\du+ 形式，有关每一种角色的额外信息也会 被显示，当前只会多显示角色的注释。 需要注意的是，如果当前用户为超级用户，则显示所有用户信息。如果是非超级用户，则显示当前用户自 己的信息，不显示其他用户信息。 5.41 dx \dx[+] [ pattern ] 列出已安装的扩展。如果指定了 pattern ，只列出名称匹配该模式的那些扩展。如果使用了\dx+ 形式， 所有属于每个匹配扩展的对象会被列出。 5.42 dy \dy[+] [ pattern ] 57 第 5 章 KSQL 命令参考 列出事件触发器。如果指定了 pattern ，只列出名称匹配该模式的事件触发器。如果在命令名称后面加 上 +，还会为每个列出的对象显示其相关的描述。 5.43 e \e 或\edit [ filename ] [ line_number ] 如果指定了 filename，则它是被编辑的文件，在编辑器退出后，该文件的内容会被拷贝到当前查询缓冲 区中。如果没有给定 filename，当前查询缓冲区会被拷贝到一个临时文件中，并且接着以相同的方式编 辑。或者，如果当前查询缓冲区为空，则最近被执行的查询会被拷贝到一个临时文件并且以同样的方式编 辑。 然后会根据 Ksql 的一般规则重新解析查询缓冲区的新内容，把整个缓冲区当作一个单一行来处理。任何 完整的查询都会被立即执行，也就是说，如果查询缓冲区包含一个分号或者以一个分号结尾，则到分号处 为止的所有东西都会被执行。剩下的东西会在查询缓冲区中等待，输入分号或者\g 会把它发送出去，输 入\r 会通过清除查询缓冲区来取消它。把缓冲区当作单一行主要会影响元命令：缓冲区中在一个元命令 之后的任何东西都将被当作该元命令的参数，即便元命令之后的内容跨越多行也是如此。（因此不能以这 种方式来制作使用元命令的脚本。应该使用\i。） 如果指定了一个行号，Ksql 将会把游标（注意不是服务器端的游标）定位到文件或者查询缓冲区的指定 行上。注意如果给出了一个全是数字的参数，Ksql 就会假定它是行号而不是文件名。 提示: 关于如何配置以及自定义编辑器，请见 环境。 5.44 echo text \echo text [ ... ] 把参数打印到标准输出，参数之间用一个空格分隔，最后加上一个新行。这可以用来在脚本的输出中间混 入信息，例如： => \echo `date` Tue Oct 26 21:40:57 CEST 1999 如果第一个参数是一个没有加引号的-n，则不会加上最后的新行。 提示: 如果使用\o 命令来重定向查询的输出，你可能希望使用\qecho 来取代这个命令。 58 第 5 章 KSQL 命令参考 5.45 ef \ef [ function_description [ line_number ] ] 这个命令会以一个 CREATE OR REPLACE FUNCTION 或 CREATE OR REPLACE PROCEDURE 命令的形式取出 并且编辑指定函数或过程的定义。编辑的方式与\edit 完全相同。在编辑器退出后，更新过的命令将在查 询缓冲区中等待，可以键入分号或者\g 把它发出，也可以用\r 取消之。 目标函数可以单独用名称或者用名称和参数（例如 foo(integer, text)）来指定。如果有多于一个函数 具有同样的名称，则必须给出参数的类型。 如果没有指定函数，将会给出一个空白的 CREATE FUNCTION 模板来编辑。 如果指定了一个行号，Ksql 将把游标定位在该函数体的指定行上（注意函数体通常不是开始于文件的第 一行）。 和大部分其他元命令不同，该行的整个剩余部分总是会被当作\ef 的参数，并且在参数中不会执行变量篡 改以及反引号展开。 提示: 有关如何配置和自定义编辑器可见 环境。 5.46 encoding \encoding [ encoding ] 设置客户端字符集编码。如果没有参数，这个命令会显示当前的编码。 5.47 errverbose \errverbose 以最详细的程度重复最近的服务器错误消息，就好像 VERBOSITY 被设置为 verbose 且 SHOW_CONTEXT 被 设置为 always。 5.48 ev \ev [ view_name [ line_number ] ] 这个命令会以一个 CREATE OR REPLACE VIEW 的形式取出并且编辑指定函数的定义。编辑的方式与\edit 完全相同。在编辑器退出后，更新过的命令将在查询缓冲区中等待，可以键入分号或者\g 把它发出，也 可以用\r 取消之。 59 第 5 章 KSQL 命令参考 如果没有指定函数，将会给出一个空白的 CREATE VIEW 模板来编辑。 如果指定了一个行号，Ksql 将把游标定位在该视图定义的指定行上。 和大部分其他元命令不同，该行的整个剩余部分总是会被当作\ev 的参数，并且在参数中不会执行变量篡 改以及反引号展开。 5.49 f \f [ string ] 设置用于非对齐查询输出的域分隔符。默认值是竖线（|）。它等效于\pset fieldsep。 5.50 g \g [ filename ] \g [ |command ] 把当前查询缓冲区发送给服务器执行。如果给出一个参数，查询的输出将被写到提到的文件或者用管道导 向给定的 shell 命令，而不是按照惯常显示出来。只有该查询成功地返回零或更多个元组时才会写文件或 命令，如果查询失败或者不是一个数据返回 SQL 命令，则不会写文件或者导向 shell 命令。 如果当前查询缓冲区为空，则重新执行最近一次被发送的查询。除了这种行为之外，没有参数的\g 实际 上等效于一个分号。一个带有参数的\g 是\o 命令的一种“一次性”选择。 如果该参数以 | 开始，则该行的所有剩余部分总是会被当做要执行的 command，并且在参数中不会执行 变量篡改以及反引号展开。该行的剩余部分会被简单地按字面传给 shell。 5.51 gdesc \gdesc 显示当前查询缓冲区的结果的描述（即列名和数据类型）。查询不会被实际执行，不过，如果它含有某种 类型的语法错误，该错误将被以通常的方式报出。 如果当前查询缓冲区为空，则会描述最近被发送的查询。 5.52 gexec \gexec 60 第 5 章 KSQL 命令参考 把当前查询缓冲区发送到服务器，然后该查询输出（如果有）中的每一行的每一列都当作一个要被执行的 SQL 语句。例如，要在 my_table 的每一列上都创建一个索引： => SELECT format('create index on my_table(%I)', attname) -> FROM sys_attribute -> WHERE attrelid = 'my_table'::regclass AND attnum > 0 -> ORDER BY attnum -> \gexec CREATE INDEX CREATE INDEX CREATE INDEX CREATE INDEX 产生的查询会按照其所在行被返回的顺序执行，如果有多个列，则同一行中按照从左至右的顺序执 行。NULL 域会被忽略。产生的查询会被原样发送给服务器处理，因此它们即不能是 Ksql 元命令， 也不能包含 Ksql 变量引用。如果其中任何一个查询失败，剩余查询的执行将会继续，除非设置了 ON_ERROR_STOP。每个查询的执行都遵照 ECHO 的处理（在使用\gexec 时，通常建议设置 ECHO 为 all 或者 queries）。查询日志、单步模式、计时以及其他查询执行特性也适用于每一个生成的查询。 如果当前查询缓冲区为空，则会重新执行最近被发送的查询。 5.53 gset \gset [ prefix ] 把当前查询输入缓冲区发送给服务器并且将查询的输出存储在 Ksql 变量中（见 变量）。被执行的查询必 须只返回一行。该行的每一列会被存储到一个单独的变量中，变量和该列的名字一样。例如： => SELECT 'hello' AS var1, 10 AS var2 -> \gset => \echo :var1 :var2 hello 10 如果指定了一个 prefix，那么该字符串会被追加在该查询的输出列名称之前用来创建要使用的变量名： => SELECT 'hello' AS var1, 10 AS var2 -> \gset result_ => \echo :result_var1 :result_var2 hello 10 如果一个列的结果为 NULL，那么对应的变量会被重置而不是被设置。 如果查询失败或者没有返回一行，则不会有任何变量被更改。 如果当前查询缓冲区为空，则重新执行最近被发送的查询。 61 第 5 章 KSQL 命令参考 5.54 gx \gx [ filename ] \gx [ |command ] \gx 等效于\g，但会为这个查询强制扩展的输出模式。请参考\x。 5.55 h \h or \help [ command ] 给出指定 SQL 命令的语法帮助。如果没有指定 command，则 Ksql 会列出可以显示语法帮助的所有命令。 如果 command 是一个星号（*），则会显示所有 SQL 命令的语法帮助。 与大部分其他元命令不同，该行的所有剩余部分总是会被当做\help 的参数，并且在参数中不会执行变量 篡改以及反引号展开。 注意: 为了简化输入，由几个词构成的命令不需要被加上引号。因此，键入 “help alter table“是可以的。 5.56 H \H or \html 开启 HTML 查询输出格式。如果 HTML 格式已经开启，这会把它切换回默认的对齐文本格式。这个命令 是为了兼容性和方便，有关设置其他输出选项请见\pset。 5.57 i \i or \include filename 从文件 filename 读取输入并且把它当作从键盘输入的命令来执行。 如果 filename 是-（连字符），那么会一直读取标准输入直到碰到一个 EOF 指示符或者\q 元命令。 这可以用来把交互式输入与文件输入混杂。注意只有在最外层激活了 readline 行为的情况下才将会使用 readline 行为。 注意: 如果想在屏幕上看到被读入的行，必须把变量 ECHO 设置成 all。 62 第 5 章 KSQL 命令参考 5.58 if \if expression \elif expression \else \endif 这一组命令实现可嵌套的条件块。条件块必须以一个\if 开始并且以一个\endif 结束。两者之间可能有 任意数量的\elif 子句，后面也可能有选择地跟着一个单一的\else 子句。一般查询以及其他类型的反斜 线命令可以出现在这些命令之间构成条件块。 \if 和\elif 命令读取它们的参数并且将它们作为布尔表达式进行计算。如果表达式得到真则处理正常继 续下去，否则会跳过下面的行直到到达一个匹配的\elif、\else 或者\endif。一旦一个\if 或者\elif 测试成功，同一个块中后面的\elif 命令的参数将不会被计算但会被当作为假。跟在一个\else 后面的行 只有在先前的匹配的\if 或\elif 成功时才被处理。 就像任何其他反斜线命令参数一样，\if 或者\elif 命令的 expression 参数服从变量篡改以及反引号展 开。然后会像一个 on/off 选项变量的值一样来计算它。因此，对下列项无歧义、大小写无关的匹配都是有 效的值：true、false、1、0、on、off、yes、no。例如，t、T 以及 tR 都将被认为是真。 无法被正确计算为真或假的表达式将产生一个警告并且被当做假。 正在被跳过的行还是会被正常地解析以标识查询和反斜线命令，但是查询不会被发送到服务器，并且非条 件（\if、\elif、\else、\endif）反斜线命令会被忽略。条件命令会被检查以判断嵌套是否有效。被跳 过的行中的变量引用不会被展开，并且也不会执行反引号展开。 一个给定条件块中的所有反斜线命令必须出现在相同的源文件中。如果在所有的本地\if 块被关闭之前， 主输入文件或者一个\include 进来的文件上就达到了 EOF，则 Ksql 将产生一个错误。 这里是一个例子： -- 检查数据库中两个单独记录的存在性并且把结果存在单独的 Ksql 变量中 SELECT EXISTS(SELECT 1 FROM customer WHERE customer_id = 123) as is_customer, EXISTS(SELECT 1 FROM employee WHERE employee_id = 456) as is_employee \gset \if :is_customer SELECT * FROM customer WHERE customer_id = 123; \elif :is_employee \echo 'is not a customer but is an employee' SELECT * FROM employee WHERE employee_id = 456; \else \if yes \echo 'not a customer or employee' \else \echo 'this will never print' \endif \endif 63 第 5 章 KSQL 命令参考 5.59 ir \ir or \include_relative filename \ir 命令类似于\i，但是以不同的方式处理相对路径文件名。在交互模式中执行时，这两个命令的行为相 同。不过，当被从脚本中调用时，\ir 相对于脚本所在的目录而不是根据当前工作目录来解释文件名。 5.60 l \l[+] or \list[+] [ pattern ] 列出服务器中的数据库并且显示它们的名称、拥有者、字符集编码以及访问特权。如果指定了 pattern ， 则只列出名称匹配该模式的数据库。如果向命令名称追加 +，则还会显示数据库的尺寸、默认表空间以及 描述（尺寸信息只对当前用户能连接的数据库可用）。 5.61 lo_export \lo_export loid filename 从数据库中读取具有 OID loid 的大对象并且将它写入到 filename。注意这和服务器函数 lo_export 有 微妙的不同，后者会以运行数据库服务器的用户权限来执行并且运行在服务器的文件系统上。 提示: 使用\lo_list 可以找出大对象的 OID。 5.62 lo_import \lo_import filename [ comment ] 把该文件存储到 KingbaseES 大对象。可选地，它可以把给定的注释关联到该对象。例如： foo=> \lo_import '/home/peter/pictures/photo.xcf' 'a picture of me' lo_import 152801 该响应表示该大对象得到的对象 ID 是 152801，未来可以用这个 ID 来访问这个新创建的大对象。为了便 于阅读，推荐总是给每一个对象都关联人类可读的注释。OID 和注释都可以用\lo_list 命令查看。 注意这个命令和服务器端的 lo_import 有微妙的不同，因为它以本地文件系统上的本地用户的身份运 行，而不是服务器用户和文件系统。 64 第 5 章 KSQL 命令参考 5.63 lo_list \lo_list 显示当前存储在数据库中的所有 KingbaseES 大对象，同时显示它们的任何注释。 5.64 lo_unlink \lo_unlink loid 从数据库中删除 OID 为 loid 的大对象。 提示: 使用\lo_list 可以找出该大对象的 OID。 5.65 o \o or \out [ filename ] \o or \out [ |command ] 将查询结果保存到文件 filename 中或者用管道导向到 shell 命令 command。如果没有指定参数，查询输 出会被重置到标准输出。 如果该参数以 | 开始，则该行的所有剩余部分总是会被当做要执行的 command，并且在参数中不会执行 变量篡改以及反引号展开。该行的剩余部分会被简单地按字面传给 shell。 “查询结果”包括从数据库服务器得到的所有表、命令响应和提示，还有查询数据库的各种反斜线命令 （如\d）的输出，但不包括错误消息。 提示: 要在查询结果之间混入文本输出，可以使用\qecho。 5.66 p \p or \print 把当前查询缓冲区打印到标准输出。如果当前查询缓冲区为空，会打印最近被执行的查询。 65 第 5 章 KSQL 命令参考 5.67 password \password [ username ] 更改指定用户（默认情况下是当前用户）的口令。这个命令会提示要求输入新口令、对口令加密然后把加 密后的口令作为一个 ALTER ROLE 命令发送到服务器。这确保新口令不会以明文的形式出现在命令历史、 服务器日志或者其他地方。 5.68 prompt \prompt [ text ] name 提示用户提供一个文本用于分配给变量 name。可以指定一个可选的提示字符串 text（对于多个词组成 的提示，把文本包裹在单引号中）。 默认情况下，\prompt 使用终端进行输入和输出。不过，如果使用了-f 命令行开关，\prompt 会使用标准 输入和标准输出。 5.69 pset \pset [ option [ value ] ] 这个命令设置影响查询结果表输出的选项。option 表示要设置哪个选项。value 的语义取决于选中的选 项。对于某些选项，如果省略 value 会导致该选项值被切换或者被重置，具体是哪些选项可见特定选项 的描述。如果没有上面提到的那种行为，那么省略 value 只会导致当前设置被显示。 不带任何参数的\pset 显示所有打印选项的当前状态。 可调整的打印选项有： border value 必须是一个数字。通常，数字越大，表格就会有更多的边框和线条，但具体要看 是哪一种格式。在 HTML 格式中，这会直接被转换成 border=... 属性。在大部分其 他格式中，只有值 0（没有边框）、1（内部分隔线）和 2（表格边框）有意义，并且 2 以上的值会被视为与 border = 2 相同。latex 和 latex-longtable 格式会额外地允 许一个值 3 表示在数据行之间增加分隔线。 columns 为 wrapped 格式设置目标宽度，还有扩展自动模式中决定输出是否足够多到需要分页 器或者切换到垂直显示的宽度限制。零（默认）导致目标宽度由环境变量 COLUMNS 所 控制，如果没有设置 COLUMNS 则使用检测到的屏幕宽度。此外，如果 columns 为零则 wrapped 格式只影响屏幕输出。如果 columns 为非零则文件和管道输出也会被包裹成 该宽度。 66 第 5 章 KSQL 命令参考 csv_fieldsep 指定在 CSV 输出格式中使用的字段分隔符。如果分隔符出现在字段的值中，则该字段 将在双引号内输出，遵循标准的 CSV 规则。默认是逗号。 expanded (or x) 如果 value 被指定，它必须是 on 或者 off，它们分别会启用或者禁用扩展模式，也 可以是 auto。如果 value 被省略，则该命令会在开启和关闭设置之间切换。当扩展模 式被启用时，查询结果被显示在两列中，第一列是列名而第二列是列值。如果在通常的 “水平”模式中数据不适合屏幕，则可以用这种模式。在自动设置中，只要查询输出有 多于一列并且比屏幕宽，就会使用扩展模式。否则，将使用常规模式。只有在对齐格式 和 wrapped 格式中自动设置才有效。在其他格式中，它的行为总是像扩展模式被关闭 一样。 fieldsep 指定在非对齐输出格式中使用的域分隔符。用那种方式，用户可以创建 tab 或者分隔 的输出，这种形式其他程序可能更喜欢。要设置 tab 为域分隔符，可以键入 \pset fieldsep '\t' 。默认的域分隔符是 '|' （一个竖线）。 fieldsep_zero 把用在非对齐输出格式中的域分隔符设置为一个零字节。 footer 如果 value 被指定，它必须是 on 或者 off，它们分别会启用或者禁用表格页脚 ((n rows) 计数) 的显示。如果 value 被省略，则该命令会切换页脚显示为打开或者关闭。 format 设置输出格式为 aligned, asciidoc, csv, html, latex, latex-longtable, troff-ms, unaligned, 或者 wrapped 之一。也可以使用不造成歧义的缩写（这意味着一个字母就 够了）。 aligned 格式是标准的、人类可读的、格式化好的文本输出，这是默认格式。 unaligned 格式把一个数据行的所有列都写在一行上，之间用当前活动的域分隔符分 隔。这可用于生成意图由其他程序读取的输出，例如，制表符分隔或逗号分隔的格式。 但是，如果字段分隔符出现在列的值中，则不进行特殊处理; 因此，CSV 格式可能更适 合这样的目的。 csv format 写入用逗号分隔的列值，应用RFC4180中描述的引用规则。此输出兼容服务 器的 COPY 命令 CSV 格式。除非 tuples_only 参数 on，否则将生成具有列名的标题 行。标题和页脚不打印。每行以系统相关的行结束字符结束，对于类 unix 系统，它通 常是单个换行符 (\n)，对于 Microsoft Windows，它是一个回车符和换行序列 (\r\n)。 可以使用\pset csv_fieldsep 来选择除逗号之外的字段分隔符。 wrapped 格式和 aligned 相似，但是前者会把过宽的数据值分成多个行以便输出能够 适合目标行的宽度。目标行的宽度由 columns 选项决定。注意 Ksql 将不会尝试对列头 67 第 5 章 KSQL 命令参考 部标题进行换行，因此如果列头部需要的总宽度超过目标宽度，wrapped 格式的行为就 变得和 aligned 一样了。 asciidoc, html, latex, latex-longtable, 和 troff-ms 格式使用相应的标记语言 输出文档中包含的表。它们不是完整的文档! 这在 HTML 中可能不是必需的，但 是在 LaTeX 中必须有完整的文档包装。latex 格式需要 LaTeX 的 tabular 环境。 latex-longtable 格式需要 LaTeX longtable 和 booktabs 包。 linestyle 设置边框线的绘制样式为 ascii、old-ascii 或者 unicode 之一。允许不产生歧 义的缩写（这意味着一个字母就足够了）。默认的设置是 ascii。这个选项只影响 aligned 以及 wrapped 输出格式。 ascii 样式使用纯 ASCII 字符。数据中的新行使用一个 + 符号在右手边的空白处显 示。当在 wrapped 格式中包裹两行中间没有新行字符的数据时，会在第一行右手边空 白处显示一个点号（.），并且在下一行的左手边空白处也显示一个点号（.）。 old-ascii 样式使用纯 ASCII 字符，使用 KingbaseES V7 及更早版本中用过的格式化 样式。数据中的新行使用: 符号来代替左手边的列分隔符显示。在包裹两行中间没有新 行字符的数据时，会用一个; 符号取代左手边的列分隔符。 unicode 样式使用 Unicode 的方框绘制字符。数据中的新行会使用一个回车符号显示在 右手边的空白处。在包裹两行中间没有新行字符的数据时，会在第一行的右手边空白处 显示一个省略号，并且在下一行的左手边空白处也显示一个省略号。 当 border 设置大于零时，linestyle 选项也决定边框线用什么字符绘制。纯 ASCII 字符到处都可以使用，但是在识别 Unicode 字符的显示上使用 Unicode 字符会更好看。 null 设置要用来替代空值被打印的字符串。默认是什么也不打印，对于一个空字符串这很容 易弄错。例如，有人可能更想用\pset null '(null)'。 numericlocale 如果 value 被指定，它必须是 on 或者 off，它们将分别启用或者禁用一个与区域相 关的字符来分隔数字和左边的十进制标记。如果 value 被省略，该命令会在常规输出 和区域相关的数字输出之间切换。 pager 控制对查询和 Ksql 的帮助输出使用分页器程序。如果环境变量 KSQL_PAGER 或 PAGER 被设置，输出会被用管道输送到指定的程序。否则将使用与平台相关的默认分页器程序 （例如 more）。 如果 pager 选项被设为 off，则不会使用分页器程序。如果 pager 选项被设为 on， 则会在适当的时候使用分页器，即当输出到终端并且无法适合屏幕时就会使用分页器。 pager 选项也可以被设置为 always，这会导致对所有的终端输出都是用分页器而不管 输出是否适合屏幕。不带 value 的\pset pager 会切换分页器开、关状态。 68 第 5 章 KSQL 命令参考 pager_min_lines 如果 pager_min_lines 被设置为一个大于页面高度的数字，在至少这么多输出行被显 示之前都不会调用分页器程序。默认设置为 0。 recordsep 指定用在非对齐输出格式中的记录（行）分隔符。 recordsep_zero 把用在非对齐输出格式中的记录分隔符设置为一个零字节。 tableattr (or T) 在 HTML 格 式 中， 这 会 指 定 要 放 在 table 标 记 内 的 属 性。 例 如， 这 可 能 是 cellpadding 或者 bgcolor。注意你可能不想在这里指定 border，因为那由\pset border 负责。如果没有给出 value，则表属性会被重置。 在 latex-longtable 格式中，这个选项控制每个包含左对齐数据类型的列的宽度比 例。这个选项的值是一个由空格分隔的值列表，例如'0.2 0.2 0.6'。没有指定的输出 列会使用最后一个指定的值。 title (or C) 设置用于任何后续被打印表的表标题。这可以用来给输出加上描述性的标签。如果没有 给出 value，这个标题会被复原。 tuples_only (or t) 如果 value 被指定，它必须是 on 或者 off，这个选项将启用或者禁用只显示元组的 模式。如果 value 被省略，则该命令会在常规输出和只显示元组输出之间切换。常规 输出包括列头、标题以及多种页脚之类的额外信息。在只显示元组的模式中，只会显示 实际的表数据。 unicode_border_linestyle 设置 unicode 线型的边框绘制风格为 single 或者 double 之一。 unicode_column_linestyle 设置 unicode 线型的列绘制风格为 single 或者 double 之一。 unicode_header_linestyle 设置 unicode 线型的页眉绘制风格为 single 或者 double 之一。 这些不同格式的外观可以在 示例小节的图示中看到。 提示: \pset 有多种快捷命令。请参见\a、\C、\f、\H、\t、\T 以及\x。 69 第 5 章 KSQL 命令参考 5.70 q \q or \quit 退出 Ksql 程序。在一个脚本文件中，只有该脚本的执行会被终止。 5.71 qecho text \qecho text [ ... ] 这个命令和\echo 一样，不过输出将被写到\o 所设置的查询输出通道。 5.72 r \r or \reset 重置（清除）查询缓冲区。 5.73 s \s [ filename ] 打印 Ksql 的命令行历史到 filename。如果省略 filename，该历史会被写入到标准输出（如果适用则使 用分页器）。如果编译 Ksql 时没有加上 Readline 支持，则这个命令不可用。 5.74 set name \set [ name [ value [ ... ] ] ] 设置 Ksql 变量 name 为 value，如果给出了多于一个值，则把该变量的值设置为所有给出的值的串接。 如果只给了一个参数，该变量会被设置为空字符串值。要重置一个变量，可以使用\unset 命令。 不带任何参数的\set 显示所有当前设置的 Ksql 变量的名称和值。 合法的变量名可以包含字母、数字和下划线。详见下文的 变量。变量名是大小写敏感的。 某些变量是特殊的，它们控制 Ksql 的行为或者会被自动设置以反映连接状态。这些变量在下文的 变量中 记录。 70 第 5 章 KSQL 命令参考 注意: 这个命令和 SQL 命令 SET 无关。 5.75 setenv \setenv name [ value ] 把环境变量 name 设置为 value，如果没有提供 value，则会重置该环境变量。例如： testdb=> \setenv PAGER less testdb=> \setenv LESS -imx4F 5.76 sf \sf[+] function_description 这个命令以一个 CREATE OR REPLACE FUNCTION 命令或者 CREATE OR REPLACE PROCEDURE 命令取出并 且显示指定函数或者过程的定义。定义会被打印到当前的查询输出渠道，就像\o 所作的那样。 目标函数可以单独用名称指定，也可以用名称和参数指定，例如 foo(integer, text)。如果有多于一个 函数具有相同的名字，则必须给出参数的类型。 如果向命令名称追加 +，那么输出行会被编号，函数体的第一行会被编为 1。 与大部分其他元命令不同，该行的所有剩余部分总是会被当做\sf 的参数，并且在参数中不会执行变量篡 改以及反引号展开。 5.77 sv \sv[+] view_name 这个命令以一个 CREATE OR REPLACE VIEW 命令取出并且显示指定视图的定义。定义会被打印到当前的 查询输出渠道，就像\o 所作的那样。 如果在命令名称上追加 +，那么输出行会从 1 开始编号。 与大部分其他元命令不同，该行的所有剩余部分总是会被当做\sv 的参数，并且在参数中不会执行变量篡 改以及反引号展开。 71 第 5 章 KSQL 命令参考 5.78 t \t 切换输出列名标题和行计数页脚的显示。这个命令等效于\pset tuples_only，提供它只是为了使用方便 而已。 5.79 T \T table_options 指定在 HTML 输 出 格 式 中， 要 放 在 table 标 签 内 的 属 性。 这 个 命 令 等 效 于\pset tableattr table_options。 5.80 timing \timing [ on | off ] 如果给出一个参数，这个参数用来打开或者关闭对每个 SQL 语句执行时长的显示。如果没有参数，则在 打开和关闭之间切换。显示的数据以毫秒为单位，超过 1 秒的区间还会被显示为“分钟: 秒”的格式，如 果必要还会加上小时和日的字段。 5.81 unset name \unset name 重置（删除）Ksql 变量 name。 大部分控制 Ksql 行为的变量不能被重置，相反，\unset 命令会被解释为把它们设置为其默认值。请参考 下文的 变量。 5.82 w \w or \write filename \w or \write |command 把当前查询缓冲区写到文件 filename 或者用管道导出到 shell 命令 command。如果当前查询缓冲区为 空，则写最近被执行的查询。 如果参数以 | 开始，则该行的整个剩余部分会被当做要执行的 command，并且在参数中不会执行变量篡 改以及反引号展开。该行的剩余部分会被简单地按字面传递给 shell。 72 第 5 章 KSQL 命令参考 5.83 watch \watch [ seconds ] 反复执行当前的查询缓冲区（就像\g 那样）直到被中止或者查询失败。两次执行之间等待指定的秒数 （默认是 2 秒）。显示每个查询结果时带上一个由\pset title 字符串（如果有）、从查询开始起的时 间以及延时间隔组成的页眉。 如果当前查询缓冲区为空，则会重新执行最近被发送的查询。 5.84 x \x [ on | off | auto ] 设置或者切换扩展表格格式化模式。究其本身而言，这个命令等效于\pset expanded。 5.85 z \z [ pattern ] 列出表、视图和序列，以及它们相关的访问特权。如果指定了 pattern ，则只会列出名称匹配该模式的 表、视图和序列。 这是\dp（“display privileges”）的一个别名。 5.86 ! \! [ command ] 如果没有参数，就跳出到一个子 shell，当子 shell 退出时 Ksql 会继续。如果有一个参数，则执行 shell 命 令 command。 与大部分其他元命令不同，该行的所有剩余部分总是会被当做\! 的参数，并且在参数中不会执行变量篡 改以及反引号展开。该行的剩余部分会被简单地按字面传递给 shell。 5.87 ? \? [ topic ] 73 第 5 章 KSQL 命令参考 显示帮助信息。可选的 topic 参数（默认是 commands）选择解释 Ksql 的哪一部分：commands 表示 Ksql 的反斜线命令；options 表示可以传递给 Ksql 的命令行选项；而 variables 显示有关 Ksql 配置变量的 帮助。 5.88 反斜线分号 \; 反斜线分号并非和前述命令相同的元命令，它只是会把一个分号加入到查询缓冲区且不会进一步执行。 通常，只要 Ksql 达到了命令结束的分号，它就将分发一个 SQL 命令给服务器，即使在当前行上还留有更 多输入。因此，例如输入 select 1; select 2; select 3; 将导致三个 SQL 命令被逐个发送给服务器，在继续到下一个命令前会显示每一个命令的结果。不过，被 输入为\; 的分号将不会触发命令处理，这样在它之前的命令以及其后的命令实际上会被组合在一个请求 中发送给服务器。例如 select 1\; select 2\; select 3; 会导致在到达非反斜线分号时用一个单一的请求把三个 SQL 命令发送给服务器。服务器会把这样一个请 求当作单一的事务执行，除非该字符串中有显式的 BEGIN/COMMIT 命令把它划分成多个事务。Ksql 对每 个请求仅打印出它接收到的最后一个查询结果。在这个例子中，尽管所有三个 SELECT 确实都被执行了， 但 Ksql 只会打印出 3。 74 版权声明 版权声明 北京人大金仓信息技术股份有限公司（简称：人大金仓）版权所有，并保留对本手册及本声明的一切权利。 未得到人大金仓的书面许可，任何人不得以任何方式或形式对本手册内的任何部分进行复制、摘录、备份、修 改、传播、翻译成其他语言、将其全部或部分用于商业用途。 免责声明 本手册内容依据现有信息制作，由于产品版本升级或其他原因，其内容有可能变更。人大金仓保留在没有任何通 知或者提示的情况下对手册内容进行修改的权利。 本手册仅作为使用指导，人大金仓在编写本手册时已尽力保证其内容准确可靠，但并不确保手册内容完全没有错 误或遗漏，本手册中的所有信息也不构成任何明示或暗示的担保。 技术支持 • 人大金仓官方网站：http://www.kingbase.com.cn/ • 人大金仓文档中心：http://help.kingbase.com.cn/ • 全国服务热线：400-601-1188 • 人大金仓技术支持与反馈信箱：support@kingbase.com.cn 75 服务周期承诺 服务周期承诺 由于市场需求在不断变化，技术创新和发展的进程不断加剧，产品的版本更迭不可避免。人大金仓对于产品版本 生命周期的有效管理，有助于您提前规划项目，更好地从产品服务终止上过渡。 表 1: KingbaseES 产品生命周期里程碑 关键里程碑点 定义 产品发布日期 产品正式发布版本，即 GA（general availability）版本的发布日期。 停止销售日期 正式停止销售的日期，版本停止接受订单日。该日之后，产品将不再销售。 停止功能升级日期 在该日期之后，不再提供新特性和新硬件支持。但依旧提供错误修复、安全修复、功 能维护等服务。 停止功能维护日期 在该日期之后，不再维护功能，修复问题。但依旧提供安全修复等服务 停止安全维护日期 在该日期之后，不再发布补丁版本修复中高风险漏洞，仅提供有限的支持。 产品服务终止日期 停止提供产品服务和支持的日期。包括软件维护版本，缺陷修复，以及针对该产品的 所有服务支持（包括服务热线和远程/现场支持）。 服务周期策略 金仓数据库管理系统 KingbaseES 产品确保以下的服务周期： 1）产品自发布之日起至产品停止功能升级（包含新特性、新硬件支持）之日不少于 5 年。 2）产品停止功能升级之日起至产品停止功能维护（主要包括问题修复）之日不少于 4 年。 3）产品功能维护停止之日起至产品停止安全维护（包括中高风险漏洞修复）之日不少于 2 年。 服务终止策略 金仓数据库管理系统 KingbaseES 产品确保在销售后，至少提供 6 年的服务支持。 注意: 人大金仓将会综合各方因素来确定产品服务终止日期。并将在实际产品服务终止日期之前至少 90 天，通过公 76 服务周期承诺 开方式宣布产品服务终止日期。 77
KingbaseES_ksql工具用户指南及参考.pdf
