华为云用户手册

请求示例：普通追加写对象 POST /object?append&position=0 HTTP/1.1 Host: examplebucket.obs.cn-north-4.myhuaweicloud.com Expires: Wed, 27 Jun 2015 13:45:50 GMT Date: Wed, 08 Jul 2015 06:57:01 GMT Content-Type: image/jpg Content-Length: 1458 Authorization: OBS H4IPJX0TQTHTHEBQQCEC:kZoYNv66bsmc10+dcGKw5x2PRrk= [1458 bytes of object data]

请求示例：已启用版本控制 POST /object01?append&position=0 HTTP/1.1 Authorization: OBS H4IPJX0TQTHTHEBQQCEC:iqSPeUBl66PwXDApxjRKk6hlcN4= User-Agent: curl/7.29.0 Host: examplebucket.obs.region.myhuaweicloud.com Date: WED, 01 Jul 2015 02:37:22 GMT Content-Type: application/octet-stream [1458 bytes of object data]

响应示例：普通追加写对象 1 2 3 4 5 6 7 8 HTTP/1.1 200 OK Date: Wed, 27 Jun 2015 13:45:50 GMT ETag: "d41d8cd98f00b204e9800998ecf8427e" Content-Length: 0 Server: OBS x-obs-request-id: 8DF400000163D3F0FD2A03D2D30B0542 x-obs-id-2: 32AAAUgAIAABAAAQAAEAABAAAQAAEAABCTjCqTmsA1XRpIrmrJdvcEWvZyjbztdd x-obs-next-append-position: 1458

请求示例：带redirect和自定义头域追加写对象 用户存在桶examplebucket，对象obj001不存在，通过追加写接口创建新对象， 设置重定向头域"x-obs-website-redirect-location":"http://www.example.com/"，自定义头域"x-obs-meta-redirect":"redirect"，请求为 POST /obj001?append&position=0 HTTP/1.1 Host: examplebucket.obs.cn-north-4.myhuaweicloud.com Expires: Wed, 27 Jun 2015 13:45:50 GMT Date: Wed, 08 Jul 2015 06:57:01 GMT x-obs-website-redirect-location: http://www.example.com/ x-obs-meta-redirect: redirect Content-Length: 6 Authorization: OBS H4IPJX0TQTHTHEBQQCEC:kZoYNv66bsmc10+dcGKw5x2PRrk= [6 bytes of object data]

错误响应消息 如果本次追加上传使对象长度超过对象长度限制，OBS返回400 Bad Request，错误码为AppendTooLarge。 如果position的值和当前对象的原始长度不一致，OBS返回409 Conflict，错误码为PositionNotEqualToLength。 如果指定桶中存在相同对象键值的对象，对象类型非Appendable，OBS返回409 Conflict，错误码为ObjectNotAppendable。 如果对象追加写次数超过10000次，OBS返回409 Conflict，错误码为ObjectNotAppendable。 如果对象存储类型为COLD（归档存储）或DEEP_ARCHIVE（深度归档存储），则不能调用该接口，否则OBS返回409 Conflict，错误码为ObjectNotAppendable。 如果桶设置了跨区域复制配置，则不能调用该接口，否则OBS返回400 Bad Request，错误码为OperationNotSupported。 其他错误已包含在表2中。

功能介绍 追加写对象操作是指在指定桶内的一个对象尾追加上传数据，不存在相同对象键值的对象则创建新对象。 通过Append Object操作创建的Object类型为Appendable Object，而通过Put Object上传的Object是Normal Object。 用户上传的对象存储在桶中。用户必须对桶有WRITE权限，才可以在桶中上传对象。同一个桶中存储的对象名必须是唯一的。 为了确保数据在传输过程中没有遭到破坏，用户可以在请求消息头中加入Content-MD5参数，OBS收到上传数据后，会对数据进行MD5校验，如果不一致则返回出错信息。 该操作支持在创建Appendable对象时指定x-obs-acl参数，设置对象的权限控制策略。 该操作支持服务端加密功能。

请求消息参数 该请求需要在消息中指定参数，表明这是追加写上传，同时指定本次追加上传位置，参数的具体意义如表1所示 表1 请求消息参数 参数名称 描述 是否必选 append 表明这是以追加写方式上传。 类型：String 是 position 追加写位置。需要追加写的对象首次上传时就必须指定position为0，下次追加需要填写的position会在服务端本次上传成功返回消息的头域x-obs-next-append-position中携带。 类型：Integer 是

约束 每次追加上传都会更新该对象的最后修改时间。 服务端加密SSE-C方式，那么追加上传和初始化段一样，设置诸如x-obs-server-side-encryption之类的请求Header，后续追加上传也必须携带。 服务端加密SSE-KMS方式，有且只有第一次上传且桶内不存在同名对象时，才设置诸如x-obs-server-side-encryption之类的请求Header，后续追加上传不携带。 每次追加上传的长度不能超过对象长度上限5G的限制。 每个Appendable对象追加写次数最多为10000次。 如果对象存储类型为COLD（归档存储）或DEEP_ARCHIVE（深度归档存储），则不能调用该接口。 如果桶设置了跨区域复制配置，则不能调用该接口。 并行文件系统不支持追加写对象。

响应消息元素 该请求的响应通过消息元素返回已上传了的段信息，元素的具体含义如表2所示。 表2 响应消息元素 响应字段名称 描述 ListPartsResult 保存List Part请求结果的容器。 类型：Container 子节点： Bucket, Key, UploadId, PartNumberMarker,NextPartNumberMarker, MaxParts, IsTruncated, Part。 父节点：无。 Bucket Bucket名称。 类型：String 父节点：ListPartsResult。 EncodingType 对象Key的编码类型。如果请求中设置了encoding-type，那响应中的Key会被编码。 类型：String 父节点：ListPartsResult。 Key Object名称。 类型：String 父节点：ListPartsResult。 UploadId Upload任务ID。 类型：String 父节点：ListPartsResult。 Initiator Upload任务的创建者。 类型：Container 子节点：ID。 父节点：ListPartsResult。 Owner 和Initiator相同。 类型：Container 子节点: ID。 父节点: ListPartsResult。 ID 创建者的DomainId。 类型：String 父节点: Initiator、Owner。 StorageClass 存储类型。 类型：String 有效值： STANDARD | WARM | COLD 父节点：ListPartsResult。 PartNumberMarker 本次List结果的Part Number起始位置。 类型：Integer 父节点：ListPartsResult。 NextPartNumberMarker 如果本次没有返回全部结果，响应请求中将包含NextPartNumberMarker元素，用于标明接下来请求的PartNumberMarker值。 类型：Integer 父节点：ListPartsResult。 MaxParts 返回请求中最大的Part数目。 类型：Integer 父节点：ListPartsResult。 IsTruncated 标明是否本次返回的List Part结果列表被截断。“true”表示本次没有返回全部结果；“false”表示本次已经返回了全部结果。 类型：Boolean。 父节点：ListPartsResult。 Part 保存Part信息的容器。 类型：String 子节点：PartNumber, LastModified, ETag, Size。 父节点：ListPartsResult。 （PartNumber表示Part的数字。） PartNumber 已上传Part的编号。 类型：Integer 父节点：ListPartsResult.Part。 LastModified Part上传的时间。 类型：Date 父节点：ListPartsResult.part。 ETag 已上传段内容的ETag，是段内容的唯一标识，用于段合并时校验数据一致性。 类型：String 父节点：ListPartsResult.Part Size 已上传Part大小。 类型：Integer 父节点：ListPartsResult.Part。

请求消息参数 该请求通过请求消息参数指定多段上传任务以及列出的段数量，参数的具体含义如表1所示。 表1 请求消息参数 参数名称 描述 是否必选 uploadId 多段上传任务的id。 类型：String 默认值：无。 是 max-parts 规定在列举已上传段响应中的最大Part数目。 类型：Integer 默认值：1,000。 否 part-number -marker 指定List的起始位置，只有Part Number数目大于该参数的Part会被列出。 类型：Integer 默认值：无。 否 encoding-type 对响应中的Key进行指定类型的编码。如果Key包含xml 1.0标准不支持的控制字符，可通过设置encoding-type对响应中的Key进行编码。 类型：String 默认值：无。 可选值：url。 否

错误响应消息 如果AccessKey或签名无效，OBS返回403 Forbidden，错误码为AccessDenied。 如果请求的桶不存在，OBS返回404 Not Found，错误码为NoSuchBucket。 如果请求的多段上传任务不存在，OBS返回404 Not Found，错误码为NoSuchUpload。 OBS判断用户DomainId是否具有指定桶的读权限，如果没有权限，则OBS返回403 Forbidden，错误码为AccessDenied。 其他错误已经包含在表2中。

请求示例 1 2 3 4 5 6 GET /object02?uploadId=00000163D40171ED8DF4050919BD02B8 HTTP/1.1 User-Agent: curl/7.29.0 Host: examplebucket.obs.cn-north-4.myhuaweicloud.com Accept: */* Date: WED, 01 Jul 2015 05:20:35 GMT Authorization: OBS H4IPJX0TQTHTHEBQQCEC:xkABdSrBPrz5yqzuZdJnK5oL/yU=

修订记录 发布日期 修订记录 2024-04-02 第三十三次正式发布。 本次更新说明如下： 设置桶的加密配置接口丰富请求消息样式、请求和响应示例。 2024-03-22 第三十二次正式发布。 本次更新说明如下： 创建桶接口支持配置桶加密。 2024-02-19 第三十一次正式发布。 本次更新说明如下： 优化SSE-OBS加密方式相关描述。 2024-02-07 第三十次正式发布。 本次更新说明如下： PUT上传章节优化SSE-KMS加密方式相关参数描述。 2024-01-10 第二十九次正式发布。 本次更新说明如下： 服务端加密SSE-KMS方式章节新增默认密钥相关说明。 2024-01-05 第二十八次正式发布。 本次更新说明如下： 新增回调相关内容。 2023-12-25 第二十七次正式发布。 本次更新说明如下： 丰富多个接口请求和响应示例。 2023-11-13 第二十六次正式发布。 本次更新说明如下： 优化设置桶的网站配置参数描述。 2023-11-03 第二十五次正式发布。 本次更新说明如下： 刷新表1表格。 2023-09-28 第二十四次正式发布。 本次更新说明如下： 新增SSE-OBS服务端加密方式相关内容。 刷新获取账号、IAM用户、项目、用户组、区域、委托的名称和ID章节。 2023-06-28 第二十三次正式发布。 本次更新说明如下： 获取桶存量信息章节新增响应消息元素。 2023-06-21 第二十二次正式发布。 本次更新说明如下： 新增SM4加密算法相关内容。 2023-04-23 第二十一次正式发布。 本次更新说明如下： 新增WORM特性相关接口和说明。 2023-01-13 第二十次正式发布。 本次更新说明如下： 下线SMN通知功能。 2022-12-27 第十九次正式发布。 本次更新说明如下： 刷新深度归档存储（受限公测中）相关章节。 2021-08-11 第十八次正式发布。 本次更新说明如下： 获取桶列表接口新增响应消息头BucketType。 2021-07-19 第十七次正式发布。 本次更新说明如下： 新增消息头encoding-type，详细介绍参见如下接口： 列举桶内对象 批量删除对象 列举桶中已初始化多段任务 初始化上传段任务 列举已上传未合并的段 合并段 2021-07-09 第十六次正式发布。 本次更新说明如下： 新增自定义消息头x-obs-persistent-headers，涉及如下接口： PUT上传 POST上传 复制对象 追加写对象 初始化上传段任务 2020-09-10 第十五次正式发布。 本次更新说明如下： 新增Data+相关接口。 2020-06-30 第十四次正式发布。 本次更新说明如下： 新增镜像回源相关接口。 2020-01-20 第十三次正式发布。 本次更新说明如下： 更新“权限及授权项说明”的内容。 2019-12-25 第十二次正式发布。 本次更新说明如下： 新增桶加密相关接口。 2019-08-15 第十一次正式发布。 本次更新说明如下： 新增并行文件系统相关接口：修改写对象、截断对象、重命名对象。 创建桶接口的请求消息头中增加并行文件系统相关头域。 获取桶元数据接口的响应消息头中增加并行文件系统相关头域。 列举桶列表接口的请求消息头中增加x-obs-bucket-type头域。 2019-07-18 第十次正式发布。 本次更新说明如下： 新增归档对象直读相关接口：设置桶归档对象直读策略、获取桶归档对象直读策略、删除桶归档对象直读策略。 2019-07-01 第九次正式发布。 本次更新说明如下： 新增桶清单相关接口：设置桶清单、获取桶清单、列举桶清单、删除桶清单。 2019-06-12 第八次正式发布。 本次更新说明如下： 补充临时授权访问OBS的方法说明。 优化调整文档大纲。 2019-02-03 第七次正式发布。 本次更新说明如下： 修复部分易用性问题。 2019-01-18 第六次正式发布。 本次更新说明如下： 修复部分易用性问题。 2018-12-14 第五次正式发布。 本次更新说明如下： 上线对象存储服务新域名。 优化大纲。 新增修改对象元数据接口。 2018-10-19 第四次正式发布。 本次更新说明如下： 修复部分易用性问题。 2018-08-01 第三次正式发布。 本次更新说明如下： 修复部分易用性问题。 丰富部分接口的请求示例和响应示例。 2018-07-02 第二次正式发布。 本次更新说明如下： 修复部分易用性问题。 补充接口的请求示例和响应示例。 2018-06-08 第一次正式发布。

创建AI应用的自定义镜像规范 针对您本地开发的模型，在制作AI应用的自定义镜像时，需满足ModelArts定义的规范。 自定义镜像中不能包含恶意代码。 自定义镜像大小不超过50GB。 对于同步请求模式的AI应用，如果预测请求时延超过60s，会造成请求失败，甚至会有服务业务中断的风险，预测请求时延超过60s时，建议制作异步请求模式的镜像。 镜像对外接口 设置镜像的对外服务接口，推理接口需与config.json文件中apis定义的url一致，当镜像启动时可以直接访问。下面是mnist镜像的访问示例，该镜像内含mnist数据集训练的模型，可以识别手写数字。其中listen_ip为容器IP，您可以通过启动自定义镜像，在容器中获取容器IP。 请求示例 curl -X POST \ http://{listen_ip}:8080/ \ -F images=@seven.jpg 图1 listen_ip获取示例 返回示例 {"mnist_result": 7} （可选）健康检查接口 如果在滚动升级时要求不中断业务，那么必须在config.json文件中配置健康检查的接口，供ModelArts调用，在config.json文件中配置。当业务可提供正常服务时，健康检查接口返回健康状态，否则返回异常状态。 如果要实现无损滚动升级，必须配置健康检查接口。 自定义镜像如果需要在“在线服务”模块使用OBS外部存储挂载功能，需要新建一个OBS挂载专属目录如“/obs-mount/”，避免选择存量目录覆盖已有文件。OBS挂载仅开放对挂载目录文件新增、查看、修改功能不支持删除挂载目录文件对象，若需要删除文件请到OBS并行文件系统中手动删除。 健康检查接口示例如下。 URI GET /health 请求示例curl -X GET \ http://{listen_ip}:8080/health 响应示例 {"health": "true"} 状态码 表1 状态码 状态码 编码 状态码说明 200 OK 请求成功 日志文件输出 为保证日志内容可以正常显示，日志信息需要打印到标准输出。 镜像启动入口 如果需要部署批量服务，镜像的启动入口文件需要为“/home/run.sh”，采用CMD设置默认启动路径，例如Dockerfile如下： CMD ["sh", "/home/run.sh"] 镜像依赖组件 如果需要部署批量服务，镜像内需要安装python、jre/jdk、zip等组件包。 （可选）保持Http长链接，无损滚动升级 如果需要支持滚动升级的过程中不中断业务，那么需要将服务的Http的“keep-alive”参数设置为200s。以gunicorn服务框架为例，gunicorn缺省情形下不支持keep-alive，需要同时安装gevent并配置启动参数“--keep-alive 200 -k gevent”。不同服务框架参数设置有区别，请以实际情况为准。 （可选）处理SIGTERM信号，容器优雅退出 如果需要支持滚动升级的过程中不中断业务，那么需要在容器中捕获SIGTERM信号，并且在收到SIGTERM信号之后等待60秒再优雅退出容器。提前优雅退出容器可能会导致在滚动升级的过程中业务概率中断。要保证容器优雅退出，从收到SIGTERM信号开始，业务需要将收到的请求全部处理完毕再结束，这个处理时长最多不超过90秒。例如run.sh如下所示： #!/bin/bash gunicorn_pid="" handle_sigterm() { echo "Received SIGTERM, send SIGTERM to $gunicorn_pid" if [ $gunicorn_pid != "" ]; then sleep 60 kill -15 $gunicorn_pid # 传递 SIGTERM 给gunicorn进程 wait $gunicorn_pid # 等待gunicorn进程完全终止 fi } trap handle_sigterm TERM 父主题： 使用自定义镜像创建AI应用（推理部署）

可视化训练作业介绍 ModelArts支持在开发环境中开启TensorBoard和MindInsight可视化工具。在开发环境中通过小数据集训练调试算法，主要目的是验证算法收敛性、检查是否有训练过程中的问题，方便用户调测。 ModelArts可视化作业支持创建TensorBoard类型和MindInsight两种类型。 TensorBoard和MindInsight能够有效地展示训练作业在运行过程中的变化趋势以及训练中使用到的数据信息。 TensorBoard TensorBoard是一个可视化工具，能够有效地展示TensorFlow在运行过程中的计算图、各种指标随着时间的变化趋势以及训练中使用到的数据信息。TensorBoard相关概念请参考TensorBoard官网。 TensorBoard可视化训练作业，当前仅支持基于TensorFlow2.1、Pytorch1.4/1.8版本镜像，CPU/GPU规格的资源类型。请根据实际局点支持的镜像和资源规格选择使用。 MindInsight MindInsight能可视化展现出训练过程中的标量、图像、计算图以及模型超参等信息，同时提供训练看板、模型溯源、数据溯源、性能调试等功能，帮助您在更高效地训练调试模型。MindInsight当前支持基于MindSpore引擎的训练作业。MindInsight相关概念请参考MindSpore官网。 MindInsight可视化训练作业，当前支持的镜像如下，请根据实际局点支持的镜像和资源规格选择使用。 mindspore1.2.0版本，CPU/GPU规格的资源类型。 mindspore1.5.x以上版本，Ascend规格的资源类型。 您可以使用模型训练时产生的Summary文件在开发环境Notebook中创建可视化作业。 在开发环境中创建MindInsight可视化作业，请参见MindInsight可视化作业。 在开发环境中创建TensorBoard可视化作业，请参见TensorBoard可视化作业。 父主题： 可视化训练作业

亮点特性1：远程开发 - 支持本地IDE远程访问Notebook Notebook提供了远程开发功能，通过开启SSH连接，用户本地IDE可以远程连接到ModelArts的Notebook开发环境中，调试和运行代码。 对于使用本地IDE的开发者，由于本地资源限制，运行和调试环境大多使用团队公共搭建的服务器，并且是多人共用，这带来一定的环境搭建和维护成本。 而ModelArts的Notebook的优势是即开即用，它预先装好了不同的AI引擎，并且提供了非常多的可选规格，用户可以独占一个容器环境，不受其他人的干扰。只需简单配置，用户即可通过本地IDE连接到该环境进行运行和调试。 图1 本地IDE远程访问Notebook开发环境 ModelArts的Notebook可以视作是本地PC的延伸，均视作本地开发环境，其读取数据、训练、保存文件等操作与常规的本地训练一致。 对于习惯使用本地IDE的开发者，使用远程开发方式，不影响用户的编码习惯，并且可以方便快捷的使用云上的Notebook开发环境。 本地IDE当前支持VS Code、PyCharm、SSH工具。还有专门的插件PyCharm Toolkit和VS Code Toolkit，方便将云上资源作为本地的一个扩展。

亮点特性3：预置镜像 - 即开即用，优化配置，支持主流AI引擎 每个镜像预置的AI引擎和版本是固定的，在创建Notebook实例时明确AI引擎和版本，包括适配的芯片。 ModelArts开发环境给用户提供了一组预置镜像，主要包括PyTorch、TensorFlow、MindSpore系列。用户可以直接使用预置镜像启动Notebook实例，在实例中开发完成后，直接提交到ModelArts训练作业进行训练，而不需要做适配。 ModelArts开发环境提供的预置镜像版本是依据用户反馈和版本稳定性决定的。当用户的功能开发基于ModelArts提供的版本能够满足的时候，建议用户使用预置镜像，这些镜像经过充分的功能验证，并且已经预置了很多常用的安装包，用户无需花费过多的时间来配置环境即可使用。 ModelArts开发环境提供的预置镜像主要包含： 常用预置包，基于标准的Conda环境，预置了常用的AI引擎，例如PyTorch、MindSpore；常用的数据分析软件包，例如Pandas、Numpy等；常用的工具软件，例如cuda、cudnn等，满足AI开发常用需求。 预置Conda环境：每个预置镜像都会创建一个相对应的Conda环境和一个基础Conda环境python（不包含任何AI引擎），如预置MindSpore所对应的Conda环境如下： 用户可以根据是否使用AI引擎参与功能调试，选择不同的Conda环境。 Notebook：是一款Web应用，能够使用户在界面编写代码，并且将代码、数学方程和可视化内容组合到一个文档中。 JupyterLab插件：插件包括规格切换，分享案例到AI Gallery进行交流，停止实例等，提升用户体验。 支持SSH远程连接功能，通过SSH连接启动实例，在本地调试就可以操作实例，方便调试。 ModelArts开发环境提供的预置镜像支持功能开发后，直接提到ModelArts训练作业中进行训练。 为了简化操作，ModelArts的Notebook，同一个Notebook实例中支持不同引擎之间的切换。 不同Region支持的AI引擎不一样，请以控制台实际界面为准。

亮点特性4：提供在线的交互式开发调试工具JupyterLab ModelArts集成了基于开源的JupyterLab，可为您提供在线的交互式开发调试。您无需关注安装配置，在ModelArts管理控制台直接使用Notebook，编写和调测模型训练代码，然后基于该代码进行模型的训练。 JupyterLab是一个交互式的开发环境，是Jupyter Notebook的下一代产品，可以使用它编写Notebook、操作终端、编辑MarkDown文本、打开交互模式、查看csv文件及图片等功能。

Step7 远程调试 单击本地IDE右下角interpreter，选择Notebook的python解释器。 图9 选择Python解释器 像本地运行代码一样，直接单击运行按钮运行代码即可，此时虽然是在本地IDE点的运行按钮，实际上运行的是云端Notebook里的代码，日志可以回显在本地的日志窗口。 图10 查看运行日志 也可以单击本地IDE右上角的Run/Debug Configuration按钮来设置运行参数。 图11 设置运行参数（1） 选择远程连接到云上开发环境实例对应的Python解释器。 图12 设置运行参数（2） 当需要调试代码时，可以直接打断点，然后使用debug方式运行程序。 图13 使用debug方式运行程序 此时可以进入debug模式，代码运行暂停在该行，且可以查看变量的值。 图14 Debug模式下查看变量值

Step6 同步上传本地文件至Notebook 本地文件中的代码直接复制至本地IDE中即可，本地IDE中会自动同步至云上开发环境。 初始化同步： 在本地IDE的Project目录下，单击右键，选择“Deployment”，单击“Upload to xxx”（Notebook名称），将本地工程文件上传至指定的Notebook。 图7 同步本地文件至Notebook 后续同步: 只需修改代码后保存（ctrl+s），即可进行自动同步。 插件安装完成后在本地IDE中开启了“Automatic Upload”，本地目录中的文件会自动上传至云端开发环境Notebook。如果未开启，请参考下图开启自动上传。 图8 开启自动上传

相关操作 关闭MindInsight方式如下： 方式1：在开发环境JupyterLab中的“.ipynb”文件窗口中输入命令，关闭MindInsight。端口号在启动MindInsight中设置，默认使用8080，需要替换为实际开启MindInsight时的端口。 !mindinsight stop --port 8080 方式2：单击下方按钮进入MindInsight实例管理界面，该界面记录了所有启动的MindInsight实例，单击对应实例后面的SHUT DOWN即可停止该实例。 图8 单击SHUT DOWN停止实例 方式3：单击下方红框中的按钮可以关闭所有启动的MindInsight实例。 图9 关闭所有启动的MindInsight实例 方式4（不推荐）：直接在JupyterLab中上关闭MindInsight窗口，此方式仅是关闭MindInsight可视化窗口，并未关闭后台。

Step2 上传Summary数据 在开发环境中使用MindInsight可视化功能，需要用到Summary数据。 Summary数据可以直接传到开发环境的这个路径下/home/ma-user/work/，也可以放到OBS并行文件系统中。 Summary数据上传到Notebook路径/home/ma-user/work/下的方式，请参见上传数据至Notebook。 Summary数据如果是通过OBS并行文件系统挂载到Notebook中，请将模型训练时产生的Summary文件先上传到OBS并行文件系统，并确保OBS并行文件系统与ModelArts在同一区域。在Notebook中启动MindInsight时，Notebook会自动从挂载的OBS并行文件系统目录中读取Summary数据。

支持的功能 表1 ToolKit（latest）功能列表 支持的功能 说明 对应操作指导 SSH远程连接 支持SSH远程连接ModelArts的Notebook开发环境。 配置PyCharm ToolKit远程连接Notebook 训练模型 支持将本地开发的代码，快速提交至ModelArts并自动创建训练作业，在训练作业运行期间获取训练日志并展示到本地。 提交训练作业 停止训练作业 查看训练日志 OBS上传下载 上传本地文件或文件夹至OBS，从OBS下载文件或文件夹到本地。 在PyCharm中上传数据至Notebook

处理方法 查看弹性云服务器的状态。 运行中，请执行步骤 2。 关机，请执行步骤 4。 使用SSH密钥对登录弹性云服务器，检查私钥是否正确。 正确，请执行步骤 4。 错误，请使用正确的私钥再次执行解绑密钥对操作。 检查弹性云服务器的“/root/.ssh/authorized_keys”文件是否被修改过。 是，请恢复“/root/.ssh/authorized_keys”文件的原始内容。 否，请执行步骤 4。 查看ECS安全组22端口入方向是否对100.125.0.0/16开放，即允许100.125.0.0/16地址通过SSH远程连接到Linux弹性云服务器。 是，请执行步骤 5。 否，请添加如下安全组规则后再次执行解绑密钥对操作。 方向 协议/应用 端口 源地址 入方向 SSH（22） 22 100.125.0.0/16 请检查执行密钥对解绑操作的弹性云服务器是否可以正常开机、关机和登录使用等操作。 是，请再次执行解绑密钥对操作。 否，请执行步骤 6。 检查网络是否发生故障。 是，请联系技术支持工程师查看并定位原因。 否，请再次执行解绑密钥对操作。

处理方法 查看弹性云服务器的状态。 运行中，请执行步骤 2。 关机，请执行步骤 5。 使用密码登录弹性云服务器，检查密码是否正确。 正确，请执行步骤 4。 错误，请使用正确的密码再次执行绑定密钥对操作。 检查弹性云服务器的“/root/.ssh/authorized_keys”文件权限路径和属组是否被修改过。 是，请恢复至以下权限： 每级属组都是root:root权限。 .ssh权限为700。 authorized_keys权限为600。 否，请执行步骤 4。 检查弹性云服务器的“/root/.ssh/authorized_keys”文件是否被修改过。 是，请根据实际情况恢复“/root/.ssh/authorized_keys”文件的原始内容。 否，请执行步骤 5。 检查ECS安全组22端口入方向是否对100.125.0.0/16开放，即允许100.125.0.0/16地址通过SSH远程连接到Linux弹性云服务器。 是，请执行步骤 6。 否，请添加如下安全组规则后再次执行绑定密钥对操作。添加安全组规则具体操作请参见添加安全组规则。 方向 协议/应用 端口 源地址 入方向 SSH（22） 22 100.125.0.0/16 请检查执行密钥对绑定操作的弹性云服务器是否可以正常开机、关机和登录使用等操作。 是，请再次执行绑定密钥对操作。 否，请执行步骤 7。 检查网络是否发生故障。 是，请联系技术支持工程师查看并定位原因。 否，请再次执行绑定密钥对操作。

处理方法 使用SSH密钥对登录弹性云服务器，检查私钥是否正确。 正确，请执行步骤 2。 错误，请使用正确的私钥再次执行替换密钥对操作。 检查弹性云服务器的“/root/.ssh/authorized_keys”文件是否被修改过。 是，请根据实际情况恢复“/root/.ssh/authorized_keys”文件的原始内容。 否，请执行步骤 3。 查看ECS安全组22端口入方向是否对100.125.0.0/16开放，即允许100.125.0.0/16地址通过SSH远程连接到Linux弹性云服务器。 是，请执行步骤 4。 否，请添加如下安全组规则后再次执行替换密钥对操作。 方向 协议/应用 端口 源地址 入方向 SSH（22） 22 100.125.0.0/16 请检查执行密钥对替换操作的弹性云服务器是否可以正常开机、关机和登录使用等操作。 是，请再次执行替换密钥对操作。 否，请执行步骤 5。 检查网络是否发生故障。 是，请联系技术支持工程师查看并定位原因。 否，请再次执行替换密钥对操作。

处理方法 查看ECS安全组22端口入方向是否对100.125.0.0/16开放，即允许100.125.0.0/16地址通过SSH远程连接到Linux弹性云服务器。 是，请执行步骤 2。 否，请添加如下安全组规则后再次执行重置密钥对操作。 方向 协议/应用 端口 源地址 入方向 SSH（22） 22 100.125.0.0/16 请检查执行密钥对重置操作的弹性云服务器是否可以正常开机、关机和登录使用等操作。 是，请再次执行重置密钥对操作。 否，请执行步骤 3。 检查网络是否发生故障。 是，请联系技术支持工程师查看并定位原因。 否，请再次执行重置密钥对操作。

命令参考 详细的gsql参数请参见表1、表2、表3和表4。 表1 常用参数 参数 参数说明 取值范围 -c, --command=COMMAND 声明gsql要执行一条字符串命令然后退出。 - -d, --dbname=DBNAME 指定想要连接的数据库名称。 另外，gsql允许使用扩展的DBNAME，即'postgres[ql]://[user[:password]@][netloc][:port][,...][/dbname][?param1=value1&...]'或'[key=value] [...]'形式的连接串作为DBNAME，gsql将从连接串中解析连接信息，并优先使用这些信息。 注意： gsql使用扩展的DBNAME创建连接时，不支持指定replication参数。 字符串。 -f, --file=FILENAME 使用文件作为命令源而不是交互式输入。gsql将在处理完文件后结束。如果FILENAME是-（连字符），则从标准输入读取。 绝对路径或相对路径，且满足操作系统路径命名规则。 -l, --list 列出所有可用的数据库，然后退出。 - -v, --set, --variable=NAME=VALUE 设置gsql变量NAME为VALUE。 变量的示例和详细说明请参见变量。 - -X, --no-gsqlrc 不读取启动文件（系统范围的gsqlrc或者用户的~/.gsqlrc都不读取）。 说明： 启动文件默认为~/.gsqlrc，或通过PSQLRC环境变量指定。 - -1 ("one"), --single-transaction 当gsql使用-f选项执行脚本时，会在脚本的开头和结尾分别加上START TRANSACTION/COMMIT用以把整个脚本当作一个事务执行。这将保证该脚本完全执行成功，或者脚本无效。 说明： 如果脚本中已经使用了START TRANSACTION，COMMIT，ROLLBACK，则该选项无效。 - -?, --help 显示关于gsql命令行参数的帮助信息然后退出。 - -V, --version 打印gsql版本信息然后退出。 - 表2 输入和输出参数 参数 参数说明 取值范围 -a, --echo-all 在读取行时向标准输出打印所有内容。 注意： 使用此参数可能会暴露部分SQL语句中的敏感信息，如创建用户语句中的password信息等，请谨慎使用。 - -e, --echo-queries 把所有发送给服务器的查询同时回显到标准输出。 注意： 使用此参数可能会暴露部分SQL语句中的敏感信息，如创建用户语句中的password信息等，请谨慎使用。 - -E, --echo-hidden 回显由\d和其他反斜杠命令生成的实际查询。 - -k, --with-key=KEY 使用gsql对导入的加密文件进行解密。 须知： 对于本身就是shell命令中的关键字符如单引号（'）或双引号（"），Linux shell会检测输入的单引号（'）或双引号（"）是否匹配。如果不匹配，shell认为用户没有输入完毕，会一直等待用户输入，从而不会进入到gsql程序。 不支持解密导入存储过程和函数。 - -L, --log-file=FILENAME 除了正常的输出源之外，把所有查询输出记录到文件FILENAME中。 注意： 使用此参数可能会暴露部分SQL语句中的敏感信息，如创建用户语句中的password信息等，请谨慎使用。 此参数只保留查询结果到相应文件中，主要目标是为了查询结果能够更好更准确地被其他调用者（例如自动化运维脚本）解析；而不是保留gsql运行过程中的相关日志信息。 绝对路径或相对路径，且满足操作系统路径命名规则。 -m, --maintenance 允许在两阶段事务恢复期间连接数据库。 说明： 该选项是一个开发选项，禁止用户使用，只限专业技术人员使用，功能是：使用该选项时，gsql可以连接到备机，用于校验主备机数据的一致性。 - -n, --no-libedit 关闭命令行编辑。 - -o, --output=FILENAME 将所有查询输出重定向到文件FILENAME。 绝对路径或相对路径，且满足操作系统路径命名规则。 -q, --quiet 安静模式，执行时不会打印出额外信息。 缺省时gsql将打印许多其他输出信息。 -s, --single-step 单步模式运行。意味着每个查询在发往服务器之前都要提示用户，用这个选项也可以取消执行。此选项主要用于调试脚本。 注意： 使用此参数可能会暴露部分SQL语句中的敏感信息，如创建用户语句中的password信息等，请谨慎使用。 - -S, --single-line 单行运行模式，这时每个命令都将由换行符结束，像分号那样。 - -C，-C1, --enable-client-encryption=1 当使用-C参数连接本地数据库或者连接远程数据库时，可通过该选项打开密态数据库开关，此开关为密态等值查询基本能力开关。 - 表3 输出格式参数 参数 参数说明 取值范围 -A, --no-align 切换为非对齐输出模式。 缺省为对齐输出模式。 -F, --field-separator=STRING 设置域分隔符（默认为“|”）。 - -H, --html 打开HTML格式输出。 - -P, --pset=VAR[=ARG] 在命令行上以\pset的风格设置打印选项。 说明： 这里必须用等号而不是空格分隔名称和值。例如，把输出格式设置为LaTeX，可以键入-P format=latex - -R, --record-separator=STRING 设置记录分隔符。 - -r 开启在客户端操作中可以进行编辑的模式。 缺省为关闭。 -t, --tuples-only 只打印行。 - -T, --table-attr=TEXT 允许声明放在HTML table标签里的选项。 使用时请搭配参数“-H,--html”，指定为HTML格式输出。 - -x, --expanded 打开扩展表格式模式。 - -z, --field-separator-zero 设置非对齐输出模式的域分隔符为空。 使用时请搭配参数“-A, --no-align”，指定为非对齐输出模式。 - -0, --record-separator-zero 设置非对齐输出模式的记录分隔符为空。 使用时请搭配参数“-A, --no-align”，指定为非对齐输出模式。 - -2, --pipeline 使用管道传输密码，禁止在终端使用，必须和-c或者-f参数一起使用。 - -g, 打印来自文件的所有SQL。 - 表4 连接参数 参数 参数说明 取值范围 -h, --host=HOSTNAME 指定正在运行服务器的主机名、Unix域套接字的路径、或者域名。接受以“,”分割的字符串来指定多个主机地址，支持指定多个主机地址。 当指定多个主机地址时，默认情况下会自动选择主节点地址进行连接。可通过设置PGTARGETSESSIONATTRS环境变量的值来选择连接到不同类型的节点，变量与节点类型对应的关系如下： PGTARGETSESSIONATTRS环境变量的值--选择连接的节点类型 read-write--可读写的节点 read-only--只读节点 primary或者不设定--主节点 standby--备节点 prefer-standby--首选备节点，没有备节点则转为any any--不进行角色检查 说明： 当-h只指定一个域名，但是该域名对应多个IP时，无法触发自动选主功能。 如果省略主机名，gsql将通过Unix域套接字与本地主机的服务器相连，或者在没有Unix域套接字的机器上，通过TCP/IP与localhost连接。 -p, --port=PORT 指定数据库服务器的端口号。可以配置一个或多个，当配置一个时，所有的主机地址都使用同一个端口连接；当配置多个时，顺序与主机地址顺序相同，个数必须与主机地址数相等，当不相等时会报错。 可以通过port参数修改默认端口号。 默认端口可通过编译参数来指定，不指定的话默认为5432。 -U, --username=USERNAME 指定连接数据库的用户。 说明： 通过该参数指定用户连接数据库时，需要同时提供用户密码用以身份验证。您可以通过交换方式输入密码，或者通过-W参数指定密码。 用户名中包含有字符$，需要在字符$前增加转义字符才可成功连接数据库。 字符串，默认使用与当前操作系统用户同名的用户。 -W, --password=PASSWORD 当使用-U参数连接本地数据库或者连接远端数据库时，可通过该选项指定密码。 说明： 登录数据库主节点所在服务器后连接本地数据库主节点实例时，默认使用trust连接，会忽略此参数。 用户密码中包含特殊字符“\”和"`"时，需要增加转义字符才可成功连接数据库。 如果用户未输入该参数，但是数据库连接需要用户密码，这时将出现交互式输入，请用户输入当前连接的密码。该密码最长长度为999字节，受限于GUC参数password_max_length的最大值。 字符串。 父主题： gsql

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参数），正则表达式特殊字符也按照字面意思进行匹配。

元命令 元命令的详细说明请参见表1、表2、表3、表4、表6、表8、表9、表10、表12。 以下命令中所提到的FILE代表文件路径。此路径可以是绝对路径（如/home/gauss/file.txt），也可以是相对路径（file.txt，file.txt会默认在用户执行gsql命令所在的路径下创建）。 表1 一般的元命令 参数 参数说明 取值范围 \copyright 显示GaussDB的版本和版权信息。 - \g [FILE] or ; 执行查询（并将结果发送到文件或管道）。 - \h(\help) [NAME] 给出指定SQL语句的语法帮助。 如果没有给出NAME，gsql将列出可获得帮助的所有命令。如果NAME是一个星号（*），则显示所有SQL语句的语法帮助。 \parallel [on [num]|off] 控制并发执行开关。 on：打开控制并发执行开关，且最大并发数为num。 off：关闭控制并发执行开关。 说明： 不支持事务中开启并发执行以及并发中开启事务。 不支持\d这类元命令的并发。 并发select返回结果混乱问题，此为客户可接受，core、进程停止响应不可接受。 不推荐在并发中使用set语句，否则导致结果与预期不一致。 不支持创建临时表！如需使用临时表，需要在开启parallel之前创建好，并在parallel内部使用。parallel内部不允许创建临时表。 \parallel执行时最多会启动num个独立的gsql进程连接服务器。 \parallel中所有作业的持续时间不能超过session_timeout，否则可能会导致并发执行过程中断连。 在\parallel on 之后一条或多条命令，会等到\parallel off执行后才会执行，因而，\parallel on之后需要有对应的\parallel off，否则\parallel on后的命令都无法执行。 num的默认值：1024。 须知： 服务器能接受的最大连接数受max_connection及当前已有连接数限制。 设置num时请考虑服务器当前可接受的实际连接数合理指定。 \q 退出gsql程序。在一个脚本文件里，只在脚本终止的时候执行。 - 表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 }[LOAD] [LOAD_DISCARD 'string'] [ with ] [ binary ] [ oids ] [ delimiter [ as ] 'character' ] [ useeof ] [ null [ as ] 'string' ] [ csv [ header ] [ quote [ as ] 'character' ] [ escape [ as ] 'character' ] [ force quote column_list | * ] [ force not null column_list ] ] [parallel integer] 在任何gsql客户端登录数据库成功后可以执行导入导出数据，这是一个运行SQL COPY命令的操作，但不是读取或写入指定文件的服务器，而是读取或写入文件，并在服务器和本地文件系统之间路由数据。这意味着文件的可访问性和权限是本地用户的权限，而不是服务器的权限，并且不需要数据库初始化用户权限。 说明： \COPY只适合小批量，格式良好的数据导入，导入数据应优先选择GDS或COPY。 \COPY 可以指定数据导入时的客户端数量，从而实现数据文件的并行导入，目前并发数范围为[1, 8]。 \COPY并行导入目前存在以下约束：临时表的并行导入不支持、在事务内的并行导入不支持、对二进制文件的并行导入不支持、数据导入支持AES128加密时不支持以及COPY选项中存在EOL。在这些情况下，即使指定了parallel参数，仍然会走非并行流程。 \COPY的text格式和csv格式均支持header功能 其中LOAD功能为gs_loader进行语法转换后调用copy的标识，非主动调用功能。 其中LOAD_DISCARD功能为gs_loader解析后discard文件路径，非主动调用功能。 \echo [STRING] 把字符串写到标准输出。 \i FILE 从文件FILE中读取内容，并将其当作输入，执行查询。 \i+ FILE KEY 执行加密文件中的命令。 \ir FILE 和\i类似，只是相对于存放当前脚本的路径。 \ir+ FILE KEY 和\i+类似，只是相对于存放当前脚本的路径。 \o [FILE] 把所有的查询结果发送到文件里。 \qecho [STRING] 把字符串写到查询结果输出流里。 表4中的选项S表示显示系统对象，+表示显示对象附加的描述信息。PATTERN用来指定要被显示的对象名称。 表4 显示信息元命令 参数 参数说明 取值范围 示例 \d[S+] 列出当前search_path中模式下所有的表、视图和序列。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。 - 列出当前search_path中模式下所有的表、视图和序列。 1 gaussdb=# \d \d[S+] NAME 列出指定表、视图和索引的结构。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。 - 假设存在表a，列出指定表a的结构。 1 gaussdb=# \dtable+ a \d+ [PATTERN] 列出所有表、视图和索引。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。 如果声明了PATTERN，只显示名称匹配PATTERN的表、视图和索引。 列出所有名称以f开头的表、视图和索引。 1 gaussdb=# \d+ f* \da[S] [PATTERN] 列出所有可用的聚集函数，以及它们操作的数据类型和返回值类型。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。 如果声明了PATTERN，只显示名称匹配PATTERN的聚集函数。 列出所有名称以f开头可用的聚集函数，以及它们操作的数据类型和返回值类型。 1 gaussdb=# \da f* \db[+] [PATTERN] 列出所有可用的表空间。 如果声明了PATTERN，只显示名称匹配PATTERN的表空间。 列出所有名称以p开头的可用表空间。 1 gaussdb=# \db p* \dc[S+] [PATTERN] 列出所有字符集之间的可用转换。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。 如果声明了PATTERN，只显示名称匹配PATTERN的转换。 列出所有字符集之间的可用转换。 1 gaussdb=# \dc * \dC[+] [PATTERN] 列出所有类型转换。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。 PATTERN需要使用实际类型名，不能使用别名。 如果声明了PATTERN，只显示名称匹配PATTERN的转换。 列出所有名称以c开头的类型转换。 1 gaussdb=# \dC c* \dd[S] [PATTERN] 显示所有匹配PATTERN的描述。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。 如果没有给出参数，则显示所有可视对象。“对象”包括：聚集、函数、操作符、类型、关系(表、视图、索引、序列、大对象)、规则。 列出所有可视对象。 1 gaussdb=# \dd \ddp [PATTERN] 显示所有默认的使用权限。 如果指定了PATTERN，只显示名称匹配PATTERN的使用权限。 列出所有默认的使用权限。 1 gaussdb=# \ddp \dD[S+] [PATTERN] 列出所有可用域。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。 如果声明了PATTERN，只显示名称匹配PATTERN的域。 列出所有可用域。 1 gaussdb=# \dD \det[+] [PATTERN] 列出所有的外部表。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。 如果声明了PATTERN，只显示名称匹配PATTERN的表。 列出所有的外部表。 1 gaussdb=# \det \des[+] [PATTERN] 列出所有的外部服务器。 如果声明了PATTERN，只显示名称匹配PATTERN的服务器。 列出所有的外部服务器。 1 gaussdb=# \des \deu[+] [PATTERN] 列出用户映射信息。 如果声明了PATTERN，只显示名称匹配PATTERN的信息。 列出用户映射信息。 1 gaussdb=# \deu \dew[+] [PATTERN] 列出封装的外部数据。 如果声明了PATTERN，只显示名称匹配PATTERN的数据。 列出封装的外部数据。 1 gaussdb=# \dew \df[antw][S+] [PATTERN] 列出所有可用函数，以及它们的参数和返回的数据类型。a代表聚集函数，n代表普通函数，t代表触发器，w代表窗口函数。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。 如果声明了PATTERN，只显示名称匹配PATTERN的函数。 列出所有可用函数，以及它们的参数和返回的数据类型。 1 gaussdb=# \df \dF[+] [PATTERN] 列出所有的文本搜索配置信息。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。 如果声明了PATTERN，只显示名称匹配PATTERN的配置信息。 列出所有的文本搜索配置信息。 1 gaussdb=# \dF+ \dFd[+] [PATTERN] 列出所有的文本搜索字典。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。 如果声明了PATTERN，只显示名称匹配PATTERN的字典。 列出所有的文本搜索字典。 1 gaussdb=# \dFd \dFp[+] [PATTERN] 列出所有的文本搜索分析器。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。 如果声明了PATTERN，只显示名称匹配PATTERN的分析器。 列出所有的文本搜索分析器。 1 gaussdb=# \dFp \dFt[+] [PATTERN] 列出所有的文本搜索模板。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。 如果声明了PATTERN，只显示名称匹配PATTERN的模板。 列出所有的文本搜索模板。 1 gaussdb=# \dFt \dg[+] [PATTERN] 列出所有数据库角色。 说明： 因为用户和群组的概念被统一为角色，所以这个命令等价于\du。为了和以前兼容，所以保留两个命令。 如果指定了PATTERN，只显示名称匹配PATTERN的角色。 列出名称为“j?e”所有数据库角色（“?”表示任一字符）。 1 gaussdb=# \dg j?e \dl \lo_list的别名，显示一个大对象的列表。 - 列出所有的大对象。 1 gaussdb=# \dl \dL[S+] [PATTERN] 列出可用的程序语言。 如果指定了PATTERN，只列出名称匹配PATTERN的语言。 列出可用的程序语言。 1 gaussdb=# \dL \dm[S+] [PATTERN] 列出物化视图。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。 如果指定了PATTERN，只列出名称匹配PATTERN的物化视图。 列出物化视图。 1 gaussdb=# \dm \dn[S+] [PATTERN] 列出所有模式（名称空间）。如果向命令追加+，会列出每个模式相关的权限及描述。 如果声明了PATTERN，只列出名称匹配PATTERN的模式名。缺省时，只列出用户创建的模式。 列出所有名称以d开头的模式以及相关信息。 1 gaussdb=# \dn+ d* \do[S] [PATTERN] 列出所有可用的操作符，以及它们的操作数和返回的数据类型。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。 如果声明了PATTERN，只列出名称匹配PATTERN的操作符。缺省时，只列出用户创建的操作符。 列出所有可用的操作符，以及它们的操作数和返回的数据类型。 1 gaussdb=# \do \dO[S+] [PATTERN] 列出排序规则。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。 如果声明了PATTERN，只列出名称匹配PATTERN的规则。缺省时，只列出用户创建的规则。 列出排序规则。 1 gaussdb=# \dO \dp [PATTERN] 列出一列可用的表、视图以及相关的权限信息。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。 \dp显示结果如下： rolename=xxxx/yyyy --赋予一个角色的权限 =xxxx/yyyy --赋予public的权限 xxxx表示赋予的权限，yyyy表示授予这个权限的角色。权限的参数说明请参见表5。 如果指定了PATTERN，只列出名称匹配PATTERN的表、视图。 列出一列可用的表、视图以及相关的权限信息。 1 gaussdb=# \dp \drds [PATTERN1 [PATTERN2]] 列出所有修改过的配置参数。这些设置可以是针对角色的、针对数据库的或者同时针对两者的。PATTERN1和PATTERN2表示要列出的角色PATTERN和数据库PATTERN。 如果声明了PATTERN，只列出名称匹配PATTERN的规则。缺省或指定*时，则会列出所有设置。 列出数据库所有修改过的配置参数。 1 gaussdb=# \drds * dbname \dT[S+] [PATTERN] 列出所有的数据类型。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。 如果指定了PATTERN，只列出名称匹配PATTERN的类型。 列出所有的数据类型。 1 gaussdb=# \dT \du[+] [PATTERN] 列出所有数据库角色。 说明： 因为用户和群组的概念被统一为角色，所以这个命令等价于\dg。为了和以前兼容，所以保留两个命令。 如果指定了PATTERN，则只列出名称匹配PATTERN的角色。 列出所有数据库角色。 1 gaussdb=# \du \dE[S+] [PATTERN] \di[S+] [PATTERN] \ds[S+] [PATTERN] \dt[S+] [PATTERN] \dv[S+] [PATTERN] 这一组命令，字母E，i，s，t和v分别代表着外部表，索引，序列，表和视图。可以以任意顺序指定其中一个或者它们的组合来列出这些对象。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。例如：\dit列出所有的索引和表。在命令名称后面追加+，则每一个对象的物理尺寸以及相关的描述也会被列出。 如果指定了PATTERN，只列出名称匹配该PATTERN的对象。默认情况下只会显示用户创建的对象。通过PATTERN或者S修饰符可以把系统对象包括在内。 列出所有的索引和视图。 1 gaussdb=# \div \dx[+] [PATTERN] 列出安装数据库的扩展信息。 如果指定了PATTERN，则只列出名称匹配PATTERN的扩展信息。 列出安装数据库的扩展信息。 1 gaussdb=# \dx \l[+] 列出服务器上所有数据库的名称、所有者、字符集编码以及使用权限。 - 列出服务器上所有数据库的名称、所有者、字符集编码以及使用权限。 1 gaussdb=# \l \sf[+] FUNCNAME 显示函数的定义。 说明： 对于带圆括号的函数名，需要在函数名两端添加双引号，并且在双引号后面加上参数类型列表。参数类型列表两端添加圆括号。 - 假设存在函数function_a和函数名带圆括号的函数func()name，列出函数的定义。 1 2 3 gaussdb=# \sf function_a gaussdb=# \sf "func()name"(argtype1, argtype2) \z [PATTERN] 列出数据库中所有表、视图和序列，以及它们相关的访问特权。 如果给出任何pattern ，则被当成一个正则表达式，只显示匹配的表、视图、序列。 列出数据库中所有表、视图和序列，以及它们相关的访问特权。 1 gaussdb=# \z 表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 ALTER：允许用户修改指定对象的属性。 P DROP：允许用户删除指定的对象。 m COMMENT：允许用户定义或修改指定对象的注释。 i INDEX：允许用户在指定表上创建索引。 v VACUUM：允许用户对指定的表执行ANALYZE和VACUUM操作。 * 给前面权限的授权选项。 表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模式下，只显示实际的表数据。 - feedback 切换是否输出结果行数 - 表8 连接元命令 参数 参数说明 取值范围 \c[onnect] [DBNAME|- USER|- HOST|- PORT|-] 连接到一个新的数据库。当数据库名称长度超过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是一个所有特殊对待的变量列表。 \unset NAME 不设置（或删除）gsql变量名。 表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 AUTOCOMMIT [on|off] 设置当前gsql连接的自动提交行为，on为打开自动提交，off为关闭自动提交。默认情况下，gsql连接处于自动提交模式，每个单独的语句都被隐式提交。如果基于性能或者其它方面考虑，需要关闭自动提交时，需要用户自己显示的发出COMMIT命令来保证事务的提交。例如，在指定的业务SQL执行完之后发送COMMIT语句显式提交，特别是gsql客户端退出之前务必保证所有的事务已经提交。 说明： gsql默认使用自动提交模式，若关闭自动提交，将会导致后面执行的语句都受到隐式事务包裹，数据库中不支持在事务中执行的语句不能在此模式下执行。 on表示打开自动提交。 off表示关闭自动提交。 表12 大对象元命令 参数 参数说明 \lo_list 显示一个目前存储在该数据库里的所有GaussDB大对象和提供给他们的注释。