华为云用户手册

应用场景 Elasticsearch是一个高度可扩展的开源搜索和分析引擎，支持用户通过自定义规则对搜索结果进行排序。自定义排序允许开发者根据业务需求，定义特定的排序规则，以优化搜索结果的相关性和用户体验。该方案可以用于以下场景： 电子商务：根据销量、用户评价、价格等因素对商品进行排序。 内容管理：根据阅读量、发布时间对文章或博客帖子进行排序。 金融服务：根据交易金额、频率或风险评分对交易记录进行排序。 客户支持：根据工单的紧急程度或打开时间对客户请求进行排序。

方案架构 通过自定义规则对搜索结果进行排序是通过Elasticsearch的排序API实现的。通过调用排序API查询数据，实现数据按自定义规则排序。 自定义规则查询有两种方式。 用绝对好评率计算总分，按照总分由高到低的顺序排列出查询结果。 总分 = 匹配得分 * （好评率 * 绝对因子） 匹配得分：根据查询结果计分，内容匹配记1分，否则记0分，得分之和即为匹配得分。 好评率：从匹配项的数据内容中获取好评率的值，一般指单条数据的评分。 绝对因子：自定义的好评比例。 用相对好评率计算总分，按照总分由高到低的顺序排列查询结果。 总分 = 匹配得分 * （好评率 * 相对分数） 匹配得分：根据查询结果计分，内容匹配记1分，否则记0分，得分之和即为匹配得分。 好评率：从匹配项的数据内容中获取好评率的值，一般指单条数据的评分。 相对分数：自定义一个好评率阈值，当好评率大于阈值时，返回一个自定义的相对分数；当好评率小于等于阈值时，返回另一个自定义的相对分数。通过这种方式可以避免异常好评率对查询结果的影响。

脚本“perf.lua” local random = math.random local reqs = {} local cnt = 0 -- 压测的查询请求文件名称根据需要调整。 for line in io.lines("requests.txt") do table.insert(reqs, line) cnt = cnt + 1 end local addrs = {} local counter = 0 function setup(thread) local append = function(host, port) for i, addr in ipairs(wrk.lookup(host, port)) do if wrk.connect(addr) then addrs[#addrs+1] = addr end end end if #addrs == 0 then -- 根据集群的实际地址进行修改。 append("x.x.x.x", 9200) append("x.x.x.x", 9200) append("x.x.x.x", 9200) end local index = counter % #addrs + 1 counter = counter + 1 thread.addr = addrs[index] end -- 索引名称根据需要调整。 wrk.path = "/index_sift_graph/_search?request_cache=false&preference=_local" wrk.method = "GET" wrk.headers["Content-Type"] = "application/json" function request() return wrk.format(wrk.method, wrk.path, wrk.headers, reqs[random(cnt)]) end

脚本“base_test_example.py” # -*- coding: UTF-8 -*- import json import time import h5py from elasticsearch import Elasticsearch from elasticsearch import helpers def get_client(hosts: list, user: str = None, password: str = None): if user and password: return Elasticsearch(hosts, http_auth=(user, password), verify_certs=False, ssl_show_warn=False) else: return Elasticsearch(hosts) # 索引参数说明请参见在Elasticsearch集群创建向量索引。 def create(es_client, index_name, shards, replicas, dim, algorithm="GRAPH", metric="euclidean", neighbors=64, efc=200, shrink=1.0): index_mapping = { "settings": { "index": { "vector": True }, "number_of_shards": shards, "number_of_replicas": replicas, }, "mappings": { "properties": { "id": { "type": "integer" }, "vec": { "type": "vector", "indexing": True, "dimension": dim, "algorithm": algorithm, "metric": metric, "neighbors": neighbors, "efc": efc, "shrink": shrink, } } } } es_client.indices.create(index=index_name, body=index_mapping) print(f"Create index success! Index name: {index_name}") def write(es_client, index_name, vectors, bulk_size=1000): print("Start write! Index name: " + index_name) start = time.time() for i in range(0, len(vectors), bulk_size): actions = [{ "_index": index_name, "id": i + j, "vec": v.tolist() } for j, v in enumerate(vectors[i: i + bulk_size])] helpers.bulk(es_client, actions, request_timeout=180) print(f"Write success! Docs count: {len(vectors)}, total cost: {time.time() - start:.2f} seconds") merge(es_client, index_name) def merge(es_client, index_name, seg_cnt=1): print(f"Start merge! Index name: {index_name}") start = time.time() es_client.indices.forcemerge(index=index_name, max_num_segments=seg_cnt, request_timeout=7200) print(f"Merge success! Total cost: {time.time() - start:.2f} seconds") # 查询参数说明请参考见在Elasticsearch集群使用向量索引搜索数据。 def query(es_client, index_name, queries, gts, size=10, k=10, ef=200, msn=10000): print("Start query! Index name: " + index_name) i = 0 precision = [] for vec in queries: hits = set() dsl = { "size": size, "stored_fields": ["_none_"], "docvalue_fields": ["id"], "query": { "vector": { "vec": { "vector": vec.tolist(), "topk": k, "ef": ef, "max_scan_num": msn } } } } res = es_client.search(index=index_name, body=json.dumps(dsl)) for hit in res['hits']['hits']: hits.add(int(hit['fields']['id'][0])) precision.append(len(hits.intersection(set(gts[i, :size]))) / size) i += 1 print(f"Query complete! Average precision: {sum(precision) / len(precision)}") def load_test_data(src): hdf5_file = h5py.File(src, "r") base_vectors = hdf5_file["train"] query_vectors = hdf5_file["test"] ground_truths = hdf5_file["neighbors"] return base_vectors, query_vectors, ground_truths def test_sift(es_client): index_name = "index_sift_graph" vectors, queries, gts = load_test_data(r"sift-128-euclidean.hdf5") # 根据实际测试需求调整分片和副本数、索引算法、索引参数等。本文性能测试均配置的是1个分片、2个副本。 create(es_client, index_name, shards=1, replicas=2, dim=128) write(es_client, index_name, vectors) query(es_client, index_name, queries, gts) if __name__ == "__main__": # 此处修改为 CSS 集群的实际访问地址。 client = get_client(['http://x.x.x.x:9200']) test_sift(client)

测试前准备 创建Elasticsearch向量数据库，参考创建Elasticsearch集群。 “节点数量”选择“3”，“节点规格”选择“通用计算型”的“4vCPUs | 16GB”（由于测试的数据量不大，且为了和第三方的基线测试保持相同的CPU规格），“节点存储”选择“超高I/O”，不启用安全模式。 获取测试数据集。 sift-128-euclidean：维度128，base数据100万条，使用欧式距离度量。 cohere-768-cosine：维度768，base数据100万条，使用余弦距离度量。 gist-960-euclidean：维度960，base数据100万条，使用欧式距离度量。 “sift-128-euclidean”和“gist-960-euclidean”数据的下载地址是https://github.com/erikbern/ann-benchmarks。如需使用“cohere-768-cosine”数据，请提交工单获取。 图1 下载“sift-128-euclidean”和“gist-960-euclidean”数据 准备测试工具。 准备数据写入和召回率测试脚本，参考脚本base_test_example.py。 下载性能测试使用的开源压测工具Wrk，获取地址https://github.com/wg/wrk/tree/master。

性能测试的操作步骤 创建一个弹性 云服务器ECS ，用于安装压测工具和执行测试脚本。操作指导请参见快速购买和使用Linux E CS 。 ECS必须和Elasticsearch集群在同一个虚拟私有云和安全组中。 也可以使用其他客户端服务器，但是必须保证服务器和Elasticsearch集群在同一VPC。 将测试数据集上传到ECS上。 将数据写入和召回率测试脚本上传到ECS上，并执行如下命令。 pip install h5py pip install elasticsearch==7.6 python3 base_test_example.py 执行完成后，会创建测试的向量索引，写入测试数据，并返回平均查询召回率Recall。 在ECS上安装开源压测工具Wrk。 在ECS上准备压测的查询请求文件，用于模拟真实业务场景。参考脚本prepare_query.py。 pip install h5py python3 prepare_query.py 在ECS上准备Wrk的压测配置脚本。参考脚本perf.lua，脚本中的查询请求文件名称、集群访问地址和索引名称需要根据实际环境修改。 在ECS执行如下命令进行向量检索的性能压测。 wrk -c60 -t60 -d10m -s perf.lua http://x.x.x.x:9200 “t”表示压测线程数。 “c”表示与服务端的连接数。 “d”表示压测时间，“10m”表示10分钟 。 “s”表示Wrk的压测配置脚本。 “x.x.x.x”表示Elasticsearch集群的访问地址。 在回显中获得测试数据，其中“Requests/sec”即查询吞吐量QPS。 图2 测试结果示例

性能测试比较 以下测试方案只列出了对比项的参数值，未列举的参数建议保持默认值。 GRAPH类索引 百万规模的场景推荐使用GRAPH索引类型。 测试方案一：使用不同维度的数据集，在Top10召回率均达到99%的情况下，测试向量数据库能支撑的最大QPS。每个数据集均基于默认参数和调优参数分别进行测试，通过调整构建参数可以使得图索引结构更优，在同等召回精度下能取得更高的查询性能。 测试结果： 表1 GRAPH类索引测试结果1 数据集 构建参数 查询参数 性能指标 efc shrink ef max_scan_num QPS Recall sift-128-euclidean 200 1.0 84 10000 15562 0.99 500 0.8 50 10000 17332 0.99 cohere-768-cosine 200 1.0 154 10000 3232 0.99 500 0.95 106 10000 3821 0.99 gist-960-euclidean 200 1.0 800 19000 860 0.99 500 0.9 400 15000 1236 0.99 结论：对于不同的数据集，使用默认参数均能达到99%以上的召回率。在进一步调整构建参数和查询参数后，增加了一定的索引构建开销，同时也达到更高的查询性能。 测试方案二：使用同一数据集，通过调整索引参数，测试不同召回率下的查询性能。本方案用COHERE数据集，分别测试了Top10召回率为99%、98%及95%时的集群最大QPS。 测试结果： 表2 GRAPH类索引测试结果1 数据集 构建参数 查询参数 性能指标 efc ef QPS Recall cohere-768-cosine 500 128 3687 0.99 500 80 5320 0.98 500 36 9028 0.95 结论：同一集群在统一索引构建参数的情况下，通过调整ef参数可以获得不同的查询精度，在略微损失召回率的场景下可以获得成倍的性能提升。 GRAPH_PQ类索引 基于图算法的索引为了保证查询性能通常需要常驻内存，因此当向量维度较高或数据量较大时，内存资源成为影响成本及性能的关键因素。具体来说，高维度的向量和大规模的数据集对内存的需求显著增加，这不仅关系到存储成本，还直接影响到索引算法的运行效率和响应速度。该场景推荐使用GRAPH_PQ索引类型。 测试方案：使用维度较高的COHERE与GIST数据集，测试在Top10召回率达到95%时的集群最大QPS，并与GRAPH索引对比常驻内存开销。 测试结果： 表3 GRAPH_PQ类索引测试结果 数据集 构建参数 查询参数 性能指标 内存开销 efc fragment_num ef topk QPS Recall GRAPH_PQ GRAPH cohere-768-cosine 200 64 85 130 8723 0.95 332MB 3.3GB gist-960-euclidean 200 120 200 360 4267 0.95 387MB 4.0GB 结论：结果显示使用GRAPH_PQ类索引能够在节约10倍+内存开销的情况下，取得与GRAPH索引差不多的精度和性能。因此，CSS向量索引的GRAPH_PQ算法融合了图索引与量化算法，能够大幅降低内存的开销，提升单机的数据容量。 测试数据中涉及的索引参数说明请参见表4，关于构建参数的详细说明请参见在Elasticsearch集群创建向量索引，关于查询参数的详细说明请参见在Elasticsearch集群使用向量索引搜索数据。 表4 索引参数说明 类型 参数名称 说明 构建参数 efc 构建hnsw时考察邻居节点的队列大小，默认值为200，值越大精度越高，构建速度将会变慢。 shrink 构建hnsw时的裁边系数，默认值为1.0f。 fragment_num 段数，默认值为0，插件自动根据向量长度设置合适的段数。 查询参数 ef 查询时考察邻居节点的队列大小。值越大查询精度越高，查询速度会变慢。默认值为200。 max_scan_num 扫描节点上限。值越大精度越高，查询速度变慢。默认值为10000。 topk 查询时返回top k条数据。

应用场景 本文以Elasticsearch、Filebeat、Logstash和Kibana为例，搭建一个统一日志管理平台。使用Filebeat采集ECS中的日志，发送到Logstash进行数据处理，再存储到Elasticsearch中，最后通过Kibana进行日志的可视化查询与分析。该方案可以用于以下场景： 日志管理：集中管理应用程序和系统日志，快速定位问题。 安全监控：检测和响应安全威胁，进行入侵检测和异常行为分析。 业务分析：分析用户行为，优化产品和服务。 性能监控：监控系统和应用程序性能，实时发现瓶颈。

方案架构 ELKB（Elasticsearch、Logstash、Kibana、Beats）提供了一整套日志场景解决方案，是目前主流的一种日志系统。 Elasticsearch是一个开源分布式的搜索和分析引擎，用于存储、搜索和分析大量数据。 Logstash是一个服务器端的数据管道，负责收集、解析和丰富数据后，将其发送到Elasticsearch。 Kibana为Elasticsearch提供一个开源的数据分析和可视化平台，用于对Elasticsearch中的数据进行搜索、查看和交互。 Beats：轻量级的数据收集器（如Filebeat、Metricbeat等），安装在服务器上，负责收集和转发数据到Logstash。 使用Elasticsearch和Logstash构建日志管理平台的方案架构如图1所示。 图1 ELKB架构 数据收集 Beats作为数据收集器，负责从各种源收集数据并发送到Logstash。 Logstash可以独立收集数据，或从Beats接收数据，对数据进行过滤、转换和增强。 数据处理 Logstash在将数据发送到Elasticsearch之前，对数据进行必要的处理，如解析结构化日志、过滤无用信息等。 数据存储 Elasticsearch作为核心存储组件，Elasticsearch索引和存储来自Logstash的数据，提供快速搜索和数据检索功能。 数据分析与可视化 使用Kibana对Elasticsearch中的数据进行分析和可视化，创建仪表板和报告，以直观展示数据。 ELKB系统中各组件的版本兼容性请参见https://www.elastic.co/support/matrix#matrix_compatibility。

前提条件 在CSS控制台已创建Elasticsearch集群，用于存储、分析数据。集群状态为“运行中”。获取并记录了集群的访问地址，如果是安全集群，还要记录访问集群的账号和密码。 如需新建集群请参见创建Elasticsearch集群。 在CSS控制台已创建Logstash集群，用于数据处理。 如需新建集群请参见创建Logstash集群。 数据已成功接入Kafka的指定Topic中。获取并记录了Kafka的IP地址和端口号。 如果使用的是分布式消息服务Kafka版则可以参考创建Kafka Topic。

SDK列表 在开始使用之前，请确保您安装的是最新版本的SDK。使用过时的版本可能会导致兼容性问题或无法使用最新功能。您可以在 SDK中心 查询版本信息。 表1提供了CBH服务支持的SDK列表，您可以在GitHub仓库查看SDK更新历史、获取安装包以及查看指导文档。 如果无法正常打开GitHub仓库，请检查您所使用的网络是否可以正常访问公网。由于GitHub的服务器部署在国外，国内用户访问时容易遇到无法打开的情况，请切换网络后再尝试打开。 表1 SDK列表 编程语言 Github地址 参考文档 Java huaweicloud-sdk-java-v3 Java SDK使用指导 Python huaweicloud-sdk-python-v3 Python SDK使用指导 Go huaweicloud-sdk-go-v3 Go SDK使用指导 NodeJs huaweicloud-sdk-nodejs-v3 NodeJs SDK使用指导 PHP huaweicloud-sdk-php-v3 PHP SDK使用指导

基本概念 账号 用户注册时的账号，账号对其所拥有的资源及云服务具有完全的访问权限，可以重置用户密码、分配用户权限等。由于账号是付费主体，为了确保账号安全，建议您不要直接使用账号进行日常管理工作，而是创建用户并使用他们进行日常管理工作。 用户 由账号在 IAM 中创建的用户，是云服务的使用人员，具有身份凭证（密码和访问密钥）。 在我的凭证下，您可以查看账号ID和用户ID。通常在调用API的鉴权过程中，您需要用到账号、用户和密码等信息。 区域（Region） 从地理位置和网络时延维度划分，同一个Region内共享弹性计算、块存储、对象存储、VPC网络、弹性公网IP、镜像等公共服务。Region分为通用Region和专属Region，通用Region指面向公共租户提供通用云服务的Region；专属Region指只承载同一类业务或只面向特定租户提供业务服务的专用Region。 详情请参见区域和可用区。 可用区（AZ，Availability Zone） 一个AZ是一个或多个物理数据中心的集合，有独立的风火水电，AZ内逻辑上再将计算、网络、存储等资源划分成多个集群。一个Region中的多个AZ间通过高速光纤相连，以满足用户跨AZ构建高可用性系统的需求。 项目 区域默认对应一个项目，这个项目由系统预置，用来隔离物理区域间的资源（计算资源、存储资源和网络资源），以默认项目为单位进行授权，用户可以访问您账号中该区域的所有资源。如果您希望进行更加精细的权限控制，可以在区域默认的项目中创建子项目，并在子项目中创建资源，然后以子项目为单位进行授权，使得用户仅能访问特定子项目中资源，使得资源的权限控制更加精确。 图1 项目隔离模型

AK/SK认证 AK/SK签名认证方式仅支持消息体大小12MB以内，12MB以上的请求请使用Token认证。 AK/SK既可以使用永久访问密钥中的AK/SK，也可以使用临时访问密钥中的AK/SK，但使用临时访问密钥的AK/SK时需要额外携带“X-Security-Token”字段，字段值为临时访问密钥的security_token。 AK/SK认证就是使用AK/SK对请求进行签名，在请求时将签名信息添加到消息头，从而通过身份认证。 AK(Access Key ID)：访问密钥ID。与私有访问密钥关联的唯一标识符；访问密钥ID和私有访问密钥一起使用，对请求进行加密签名。 SK(Secret Access Key)：与访问密钥ID结合使用的密钥，对请求进行加密签名，可标识发送方，并防止请求被修改。 使用AK/SK认证时，您可以基于签名算法使用AK/SK对请求进行签名，也可以使用专门的签名SDK对请求进行签名。详细的签名方法和SDK使用方法请参见API签名指南。 签名SDK只提供签名功能，与服务提供的SDK不同，使用时请注意。

Token认证 Token的有效期为24小时，需要使用一个Token鉴权时，可以先缓存起来，避免频繁调用。 使用Token前请确保Token离过期有足够的时间，防止调用API的过程中Token过期导致调用API失败。 Token在计算机系统中代表令牌（临时）的意思，拥有Token就代表拥有某种权限。Token认证就是在调用API的时候将Token加到请求消息头，从而通过身份认证，获得操作API的权限。 Token可通过调用获取用户Token接口获取，调用本服务API需要project级别的Token，即调用获取用户Token接口时，请求body中auth.scope的取值需要选择project，如下所示。 { "auth": { "identity": { "methods": [ "password" ], "password": { "user": { "name": "username", "password": "********", "domain": { "name": "domainname" } } } }, "scope": { "project": { "name": "xxxxxxxx" } } } } 获取Token 后，再调用其他接口时，您需要在请求消息头中添加“X-Auth-Token”，其值即为Token。例如Token值为“ABCDEFG....”，则调用接口时将“X-Auth-Token: ABCDEFG....”加到请求消息头即可，如下所示。 POST https://iam.cn-north-4.myhuaweicloud.com/v3.0/OS-USER/users Content-Type: application/json X-Auth-Token: ABCDEFG.... 您还可以通过这个视频教程了解如何使用Token认证：https://bbs.huaweicloud.com/videos/101333。

请求消息体 请求消息体通常以结构化格式发出，与请求消息头中Content-type对应，传递除请求消息头之外的内容。若请求消息体中参数支持中文，则中文字符必须为UTF-8编码。 每个接口的请求消息体内容不同，也并不是每个接口都需要有请求消息体（或者说消息体为空），GET、DELETE操作类型的接口就不需要消息体，消息体具体内容需要根据具体接口而定。 对于管理员创建IAM用户接口，您可以从接口的请求部分看到所需的请求参数及参数说明。将消息体加入后的请求如下所示，加粗的斜体字段需要根据实际值填写。 accountid为IAM用户所属的账号ID。 username为要创建的IAM用户名。 email为IAM用户的邮箱。 **********为IAM用户的登录密码。 POST https://iam.cn-north-4.myhuaweicloud.com/v3.0/OS-USER/users Content-Type: application/json X-Sdk-Date: 20240416T095341Z Authorization: SDK-HMAC-SHA256 Access=****************, SignedHeaders=content-type;host;x-sdk-date, Signature=**************** { "user": { "domain_id": "accountid", "name": "username", "password": "**********", "email": "email", "description": "IAM User Description" } } 到这里为止这个请求需要的内容就具备齐全了，您可以使用curl、Postman或直接编写代码等方式发送请求调用API。

请求消息头 附加请求头字段，如指定的URI和HTTP方法所要求的字段。例如定义消息体类型的请求头“Content-Type”，请求鉴权信息等。 如下公共消息头需要添加到请求中。 Content-Type：消息体的类型（格式），必选，默认取值为“application/json”，有其他取值时会在具体接口中专门说明。 Authorization：签名认证信息，可选，当使用AK/SK方式认证时，使用SDK对请求进行签名的过程中会自动填充该字段。 X-Sdk-Date：请求发送的时间，可选，当使用AK/SK方式认证时，使用SDK对请求进行签名的过程中会自动填充该字段。 X-Auth-Token：用户Token，可选，当使用Token方式认证时，必须填充该字段。用户Token也就是调用获取用户Token接口的响应值，该接口是唯一不需要认证的接口。 X-Project-ID：子项目ID，可选，在多项目场景中使用。如果云服务资源创建在子项目中，AK/SK认证方式下，操作该资源的接口调用需要在请求消息头中携带X-Project-ID。 X-Domain-ID：账号ID，可选。AK/SK认证方式下，全局服务的接口调用时，需在请求消息头中携带X-Domain-ID。 对于管理员创建IAM用户接口，使用AK/SK方式认证时，添加消息头后的请求如下所示。 POST https://iam.cn-north-4.myhuaweicloud.com/v3.0/OS-USER/users Content-Type: application/json X-Sdk-Date: 20240416T095341Z Authorization: SDK-HMAC-SHA256 Access=****************, SignedHeaders=content-type;host;x-sdk-date, Signature=**************** API同时支持使用AK/SK认证，AK/SK认证是使用SDK对请求进行签名，签名过程会自动往请求中添加Authorization（签名认证信息）和X-Sdk-Date（请求发送的时间）请求头。 AK/SK认证的详细说明请参见AK/SK认证。

请求方法 HTTP请求方法（也称为操作或动词），它告诉服务正在请求什么类型的操作。 GET：请求服务器返回指定资源。 PUT：请求服务器更新指定资源。 POST：请求服务器新增资源或执行特殊操作。 DELETE：请求服务器删除指定资源，如删除对象等。 HEAD：请求服务器资源头部。 PATCH：请求服务器更新资源的部分内容。当资源不存在的时候，PATCH可能会去创建一个新的资源。 在管理员创建IAM用户的URI部分，您可以看到其请求方法为“POST”，则其请求为： POST https://iam.cn-north-4.myhuaweicloud.com/v3.0/OS-USER/users

请求URI 请求URI由如下部分组成。 {URI-scheme} :// {Endpoint} / {resource-path} ? {query-string} 尽管请求URI包含在请求消息头中，但大多数语言或框架都要求您从请求消息中单独传递它，所以在此单独强调。 URI-scheme： 表示用于传输请求的协议，当前所有API均采用HTTPS协议。 Endpoint： 指定承载REST服务端点的服务器 域名 或IP，不同服务不同区域的Endpoint不同，您可以从地区和终端节点获取。 例如IAM服务在“华北-北京一”区域的Endpoint为“iam.cn-north-1.myhuaweicloud.com”。 resource-path： 资源路径，也即API访问路径。从具体API的URI模块获取，例如“获取用户Token”API的resource-path为“/v3/auth/tokens”。 query-string： 查询参数，是可选部分，并不是每个API都有查询参数。查询参数前面需要带一个“？”，形式为“参数名=参数取值”，例如“limit=10”，表示查询不超过10条数据。 例如您需要创建IAM用户，由于IAM为全局服务，则使用任一区域的Endpoint（比如“华北-北京四”区域的Endpoint：“iam.cn-north-4.myhuaweicloud.com”），并在管理员创建IAM用户的URI部分找到resource-path（/v3.0/OS-USER/users），拼接起来如下所示。 https://iam.cn-north-4.myhuaweicloud.com/v3.0/OS-USER/users 图1 URI示意图 为查看方便，在每个具体API的URI部分，只给出resource-path部分，并将请求方法写在一起。这是因为URI-scheme都是HTTPS，同一个服务的Endpoint在同一个区域也相同，所以简洁起见将这两部分省略。

调用API获取项目ID 项目ID可以通过调用查询指定条件下的项目信息API获取。 获取项目ID的接口为“GET https://{Endpoint}/v3/projects”，其中{Endpoint}为IAM的终端节点，可以从地区和终端节点获取。接口的认证鉴权请参见认证鉴权。 响应示例如下，其中projects下的“id”即为项目ID。 { "projects": [ { "domain_id": "65382450e8f64ac0870cd180d14e684b", "is_domain": false, "parent_id": "65382450e8f64ac0870cd180d14e684b", "name": "xxxxxxxx", "description": "", "links": { "next": null, "previous": null, "self": "https://www.example.com/v3/projects/a4a5d4098fb4474fa22cd05f897d6b99" }, "id": "a4a5d4098fb4474fa22cd05f897d6b99", "enabled": true } ], "links": { "next": null, "previous": null, "self": "https://www.example.com/v3/projects" } }

响应消息体 响应消息体通常以结构化格式返回，与响应消息头中Content-type对应，传递除响应消息头之外的内容。 对于管理员创建IAM用户接口，返回如下消息体。为篇幅起见，这里只展示部分内容。 { "user": { "id": "c131886aec...", "name": "IAMUser", "description": "IAM User Description", "areacode": "", "phone": "", "email": "***@***.com", "status": null, "enabled": true, "pwd_status": false, "access_mode": "default", "is_domain_owner": false, "xuser_id": "", "xuser_type": "", "password_expires_at": null, "create_time": "2024-05-21T09:03:41.000000", "domain_id": "d78cbac1..........", "xdomain_id": "30086000........", "xdomain_type": "", "default_project_id": null } } 当接口调用出错时，会返回错误码及错误信息说明，错误响应的Body体格式如下所示。 { "error_msg": "Request body is invalid.", "error_code": "IAM.0011" } 其中，error_code表示错误码，error_msg表示错误描述信息。

更新表中数据 修改已经存储在数据库中数据的行为叫做更新。用户可以更新单独一行，所有行或者指定的部分行。还可以独立更新每个字段，而其他字段则不受影响。 使用UPDATE命令更新现有行，需要提供以下三种信息： 表的名称和要更新的字段名 字段的新值 要更新的行 SQL通常不会为数据行提供唯一标识，因此无法直接声明需要更新哪一行。但是可以通过声明一个被更新的行必须满足的条件。只有在表里存在主键的时候，才可以通过主键指定一个独立的行。 建立表和插入数据的步骤请参见创建表和向表中插入数据。 需要将表customer_t1中c_customer_sk为9527的地域重新定义为9876。 1 gaussdb=# UPDATE customer_t1 SET c_customer_sk = 9876 WHERE c_customer_sk = 9527; 这里的表名称也可以使用模式名修饰，否则会从默认的模式路径找到这个表。SET后面紧跟字段和新的字段值。新的字段值不仅可以是常量，也可以是变量表达式。 比如，把所有c_customer_sk的值增加100。 1 gaussdb=# UPDATE customer_t1 SET c_customer_sk = c_customer_sk + 100; 在这里省略了WHERE子句，表示表中的所有行都要被更新。如果出现了WHERE子句，那么只有匹配其条件的行才会被更新。 在SET子句中的等号是一个赋值，而在WHERE子句中的等号是比较。WHERE条件不一定是相等比较，许多其他的操作符也可以使用。 用户可以在一个UPDATE命令中更新更多的字段，方法是在SET子句中列出更多赋值，比如： 1 gaussdb=# UPDATE customer_t1 SET c_customer_id = 'Admin', c_first_name = 'Local' WHERE c_customer_sk = 4421; 批量更新或删除数据后，会在数据文件中产生大量的删除标记，查询过程中标记删除的数据也是需要扫描的。故多次批量更新/删除后，标记删除的数据量过大会严重影响查询的性能。建议在批量更新/删除业务会反复执行的场景下，定期执行VACUUM FULL以保持查询性能。 父主题： 创建和管理表

序列号生成函数 generate_series(start, stop) 描述：生成一个数值序列，从start到stop，步长为1。 参数类型：int、bigint、numeric 返回值类型：setof int、setof bigint、setof numeric（与参数类型相同） generate_series(start, stop, step) 描述：生成一个数值序列，从start到stop，步长为step。 参数类型：int、bigint、numeric 返回值类型：setof int、setof bigint、setof numeric（与参数类型相同） generate_series(start, stop, step interval) 描述：生成一个数值序列，从start到stop，步长为step。 参数类型：timestamp或timestamp with time zone 返回值类型：setof timestamp或setof timestamp with time zone（与参数类型相同）

下标生成函数 generate_subscripts(array anyarray, dim int) 描述：生成一系列包括给定数组的下标。 返回值类型：setof int generate_subscripts(array anyarray, dim int, reverse boolean) 描述：生成一系列包括给定数组的下标。当reverse为真时，该系列则以相反的顺序返回。 返回值类型：setof int

聚集函数嵌套 描述：对聚集函数分组计算的结果再进行一次聚集函数操作。 一般可描述为： SELECT AGG1(AGG2(column_name1)) FROM table_name GROUP BY column_name2; 等价为： SELECT AGG1(value) FROM (SELECT AGG2(column_name1) value FROM table_name GROUP BY column_name2); 其中： AGG1()：表示外层聚集函数。 AGG2()：表示内层聚集函数。 table_name：表示表名。 column_name1、column_name2：表示列名。 value：表示内层聚集函数结果的别名。 整体含义可描述为：将内层聚集函数AGG2()分组计算的结果作为外层聚集函数AGG1()的输入再计算一次。 嵌套的聚集函数应位于SELECT和FROM之间，否则无意义。 使用嵌套聚集函数的SELECT语句应包含GROUP BY子句。 与嵌套聚集函数同时被SELECT的，应同为嵌套聚集函数，或为常量表达式。 聚集函数仅支持一次聚集函数嵌套操作。 当前支持以下聚集函数之间的嵌套：avg、max、min、sum、var_pop、var_samp、variance、stddev_pop、stddev_samp、stddev、median、regr_sxx、regr_syy、regr_sxy、regr_avgx、regr_avgy、regr_r2、regr_slope、regr_intercept、covar_pop、covar_samp、corr和listagg。 内层聚集函数的返回结果类型应符合外层聚集函数的参数类型。 示例： gaussdb=# CREATE TABLE test1 (id INT,val INT); CREATE TABLE gaussdb=# INSERT INTO test1 VALUES (1, 1); INSERT 0 1 gaussdb=# INSERT INTO test1 VALUES (1, null); INSERT 0 1 gaussdb=# INSERT INTO test1 VALUES (2, 10); INSERT 0 1 gaussdb=# INSERT INTO test1 VALUES (2, 55); INSERT 0 1 gaussdb=# SELECT SUM(MIN(val)) FROM test1 GROUP BY id; sum ----- 11 (1 row) gaussdb=# DROP TABLE test1; DROP TABLE

几何函数 area(object) 描述：计算图形的面积。 返回类型：double precision 示例： 1 2 3 4 5 gaussdb=# SELECT area(box '((0,0),(1,1))') AS RESULT; result -------- 1 (1 row) center(object) 描述：计算图形的中心。 返回类型：point 示例： 1 2 3 4 5 gaussdb=# SELECT center(box '((0,0),(1,2))') AS RESULT; result --------- (0.5,1) (1 row) diameter(circle) 描述：计算圆的直径。 返回类型：double precision 示例： 1 2 3 4 5 gaussdb=# SELECT diameter(circle '((0,0),2.0)') AS RESULT; result -------- 4 (1 row) height(box) 描述：矩形的竖直高度。 返回类型：double precision 示例： 1 2 3 4 5 gaussdb=# SELECT height(box '((0,0),(1,1))') AS RESULT; result -------- 1 (1 row) isclosed(path) 描述：图形是否为闭合路径。 返回类型：Boolean 示例： 1 2 3 4 5 gaussdb=# SELECT isclosed(path '((0,0),(1,1),(2,0))') AS RESULT; result -------- t (1 row) isopen(path) 描述：图形是否为开放路径。 返回类型：Boolean 示例： 1 2 3 4 5 gaussdb=# SELECT isopen(path '[(0,0),(1,1),(2,0)]') AS RESULT; result -------- t (1 row) length(object) 描述：计算图形的长度。 返回类型：double precision 示例： 1 2 3 4 5 gaussdb=# SELECT length(path '((-1,0),(1,0))') AS RESULT; result -------- 4 (1 row) npoints(path) 描述：计算路径的顶点数。 返回类型：int 示例： 1 2 3 4 5 gaussdb=# SELECT npoints(path '[(0,0),(1,1),(2,0)]') AS RESULT; result -------- 3 (1 row) npoints(polygon) 描述：计算多边形的顶点数。 返回类型：int 示例： 1 2 3 4 5 gaussdb=# SELECT npoints(polygon '((1,1),(0,0))') AS RESULT; result -------- 2 (1 row) pclose(path) 描述：把路径转换为闭合路径。 返回类型：path 示例： 1 2 3 4 5 gaussdb=# SELECT pclose(path '[(0,0),(1,1),(2,0)]') AS RESULT; result --------------------- ((0,0),(1,1),(2,0)) (1 row) popen(path) 描述：把路径转换为开放路径。 返回类型：path 示例： 1 2 3 4 5 gaussdb=# SELECT popen(path '((0,0),(1,1),(2,0))') AS RESULT; result --------------------- [(0,0),(1,1),(2,0)] (1 row) radius(circle) 描述：计算圆的半径。 返回类型：double precision 示例： 1 2 3 4 5 gaussdb=# SELECT radius(circle '((0,0),2.0)') AS RESULT; result -------- 2 (1 row) width(box) 描述：计算矩形的水平尺寸。 返回类型：double precision 示例： 1 2 3 4 5 gaussdb=# SELECT width(box '((0,0),(1,1))') AS RESULT; result -------- 1 (1 row)

date_part date_part('field', source) 描述：date_part函数基于传统的Ingres函数实现（该函数等效于SQL标准函数extract）。 参数：field参数是一个字符串，而不是一个名称。有效的field与extract一致，详细信息请参见EXTRACT。 示例： 1 2 3 4 5 gaussdb=# SELECT date_part('day', TIMESTAMP '2001-02-16 20:38:40'); date_part ----------- 16 (1 row) 1 2 3 4 5 gaussdb=# SELECT date_part('hour', INTERVAL '4 hours 3 minutes'); date_part ----------- 4 (1 row)

EXTRACT EXTRACT(field FROM source) 描述：extract函数从日期或时间的数值里抽取子域，比如年、小时等。 参数： source是一个timestamp、time或interval类型的值表达式（类型为date的表达式转换为timestamp，因此也可以用）。 field是一个标识符或者字符串，它指定从源数据中抽取的域。 返回值类型：double precision field的取值范围如下所示。 century 世纪。 第一个世纪从0001-01-01 00:00:00 AD开始。这个定义适用于所有使用阳历的国家。没有0世纪，直接从公元前1世纪到公元1世纪。 1 2 3 4 5 gaussdb=# SELECT EXTRACT(CENTURY FROM TIMESTAMP '2000-12-16 12:21:13'); date_part ----------- 20 (1 row) day 如果source为timestamp，表示月份里的日期（1~31）。 1 2 3 4 5 gaussdb=# SELECT EXTRACT(DAY FROM TIMESTAMP '2001-02-16 20:38:40'); date_part ----------- 16 (1 row) 如果source为interval，表示天数。 1 2 3 4 5 gaussdb=# SELECT EXTRACT(DAY FROM INTERVAL '40 days 1 minute'); date_part ----------- 40 (1 row) decade 年份除以10。 1 2 3 4 5 gaussdb=# SELECT EXTRACT(DECADE FROM TIMESTAMP '2001-02-16 20:38:40'); date_part ----------- 200 (1 row) dow 每周的星期几，星期天（0）到星期六（6）。 1 2 3 4 5 gaussdb=# SELECT EXTRACT(DOW FROM TIMESTAMP '2001-02-16 20:38:40'); date_part ----------- 5 (1 row) doy 一年的第几天（1~365/366）。 1 2 3 4 5 gaussdb=# SELECT EXTRACT(DOY FROM TIMESTAMP '2001-02-16 20:38:40'); date_part ----------- 47 (1 row) epoch 如果source为timestamp with time zone，表示自1970-01-01 00:00:00-00 UTC以来的秒数（结果可能是负数）； 如果source为date和timestamp，表示自1970-01-01 00:00:00-00当地时间以来的秒数； 如果source为interval，表示时间间隔的总秒数。 1 2 3 4 5 gaussdb=# SELECT EXTRACT(EPOCH FROM TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40.12-08'); date_part -------------- 982384720.12 (1 row) 1 2 3 4 5 gaussdb=# SELECT EXTRACT(EPOCH FROM INTERVAL '5 days 3 hours'); date_part ----------- 442800 (1 row) 将epoch值转换为时间戳的方法。 1 2 3 4 5 gaussdb=# SELECT TIMESTAMP WITH TIME ZONE 'epoch' + 982384720.12 * INTERVAL '1 second' AS RESULT; result --------------------------- 2001-02-17 12:38:40.12+08 (1 row) hour 小时域（0~23）。 1 2 3 4 5 gaussdb=# SELECT EXTRACT(HOUR FROM TIMESTAMP '2001-02-16 20:38:40'); date_part ----------- 20 (1 row) isodow 一周的第几天（1~7）。 星期一为1，星期天为7。 除了星期天外，都与dow相同。 1 2 3 4 5 gaussdb=# SELECT EXTRACT(ISODOW FROM TIMESTAMP '2001-02-18 20:38:40'); date_part ----------- 7 (1 row) isoyear 日期中的ISO 8601标准年（不适用于间隔）。 每个带有星期一开始的周中包含1月4日的ISO年，所以在年初的1月或12月下旬的ISO年可能会不同于阳历的年。详细信息请参见week。 1 2 3 4 5 6 7 8 9 10 gaussdb=# SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-01'); date_part ----------- 2005 (1 row) gaussdb=# SELECT EXTRACT(WEEK FROM TIMESTAMP '2006-01-01 00:00:40'); date_part ----------- 52 (1 row) gaussdb=# SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-02'); date_part ----------- 2006 (1 row) gaussdb=# SELECT EXTRACT(WEEK FROM TIMESTAMP '2006-01-02 00:00:40'); date_part ----------- 1 (1 row) microseconds 秒域（包括小数部分）乘以1,000,000。 1 2 3 4 5 gaussdb=# SELECT EXTRACT(MICROSECONDS FROM TIME '17:12:28.5'); date_part ----------- 28500000 (1 row) millennium 千年。 20世纪（19xx年）里面的年份在第二个千年里。第三个千年从2001年1月1日零时开始。 1 2 3 4 5 gaussdb=# SELECT EXTRACT(MILLENNIUM FROM TIMESTAMP '2001-02-16 20:38:40'); date_part ----------- 3 (1 row) milliseconds 秒域（包括小数部分）乘以1000。请注意它包括完整的秒。 1 2 3 4 5 gaussdb=# SELECT EXTRACT(MILLISECONDS FROM TIME '17:12:28.5'); date_part ----------- 28500 (1 row) minute 分钟域（0~59）。 1 2 3 4 5 gaussdb=# SELECT EXTRACT(MINUTE FROM TIMESTAMP '2001-02-16 20:38:40'); date_part ----------- 38 (1 row) month 如果source为timestamp，表示一年里的月份数（1~12）。 1 2 3 4 5 gaussdb=# SELECT EXTRACT(MONTH FROM TIMESTAMP '2001-02-16 20:38:40'); date_part ----------- 2 (1 row) 如果source为interval，表示月的数目，然后对12取模（0~11）。 1 2 3 4 5 gaussdb=# SELECT EXTRACT(MONTH FROM INTERVAL '2 years 13 months'); date_part ----------- 1 (1 row) quarter 该天所在的该年的季度（1~4）。 1 2 3 4 5 gaussdb=# SELECT EXTRACT(QUARTER FROM TIMESTAMP '2001-02-16 20:38:40'); date_part ----------- 1 (1 row) second 秒域，包括小数部分（0~59）。 1 2 3 4 5 gaussdb=# SELECT EXTRACT(SECOND FROM TIME '17:12:28.5'); date_part ----------- 28.5 (1 row) timezone 与UTC的时区偏移量，单位为秒。正数对应UTC东边的时区，负数对应UTC西边的时区。 timezone_hour 时区偏移量的小时部分。 timezone_minute 时区偏移量的分钟部分。 week 该天在所在的年份里是第几周。根据ISO-8601标准，一年的第一周包含该年的一月四日（ISO-8601标准的周从星期一开始）。换言之，一年的第一个星期四在第一周。 在ISO定义中，一月的开始几天可能是前一年的第52或者第53周，十二月的最后几天可能是下一年第一周。例如，2006-01-01是2005年的第52周，而2006-01-02是2006年的第1周。建议isoyear字段和week一起使用，以获得一致的结果。 1 2 3 4 5 6 7 8 9 10 gaussdb=# SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-01'); date_part ----------- 2005 (1 row) gaussdb=# SELECT EXTRACT(WEEK FROM TIMESTAMP '2006-01-01 00:00:40'); date_part ----------- 52 (1 row) gaussdb=# SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-02'); date_part ----------- 2006 (1 row) gaussdb=# SELECT EXTRACT(WEEK FROM TIMESTAMP '2006-01-02 00:00:40'); date_part ----------- 1 (1 row) year 年份域。 1 2 3 4 5 gaussdb=# SELECT EXTRACT(YEAR FROM TIMESTAMP '2001-02-16 20:38:40'); date_part ----------- 2001 (1 row)

时间日期操作符 时间日期操作符如表1所示。 用户在使用时间和日期操作符时，应使用明确的类型前缀修饰对应的操作数，以确保数据库在解析操作数的时候能够与用户预期一致，避免产生非预期的结果。 举例：以下示例没有明确数据类型，就会出现异常错误。 1 2 3 4 5 6 7 gaussdb=# SELECT date '2001-10-01' - '7' AS RESULT; ERROR: GAUSS-10416: invalid input syntax for type timestamp: "7" SQLSTATE: 22007 LINE 1: SELECT date '2001-10-01' - '7' AS RESULT; ^ CONTEXT: referenced column: result

TIMESTAMPDIFF TIMESTAMPDIFF(unit, timestamp_expr1, timestamp_expr2) 描述：timestampdiff函数计算两个时间之间(timestamp_expr2-timestamp_expr1)的差值，并以unit形式返回结果。等效于timestamp_diff(text, timestamp, timestamp)。 参数： timestamp_expr1以及timestamp_expr2的类型为时间类型表达式、text、datetime、date或time等类型。 unit表示的是两个参数差的单位，按照指定形式对结果进行返回。 返回值类型：bigint 该函数仅在MYSQL模式数据库中有效。 timestampdiff在sql_compatibility = 'MYSQL'，且参数b_format_version值为5.7、b_format_dev_version值为s1时，调用的函数实际上注册为b_timestampdiff；在MYSQL模式数据库中且未开启GUC参数时，调用的函数注册为timestamp_diff，可以用“\df b_timestampdiff”等指令查询函数的详细入参与返回值信息。 参数unit的取值范围如下所示。 year 年份。 1 2 3 4 5 gaussdb=# SELECT TIMESTAMPDIFF(YEAR, '2018-01-01', '2020-01-01'); timestamp_diff ---------------- 2 (1 row)

数据库对象位置函数 pg_relation_filenode(relation regclass) 描述：指定关系的文件节点数。 返回值类型：oid 备注：pg_relation_filenode接受一个表、索引、序列或压缩表的OID或者名称，并且返回当前分配给它的“filenode”数。文件节点是关系使用的文件名称的基本组件。对大多数表来说，结果和pg_class.relfilenode相同，但对确定的系统目录来说， relfilenode为0而且这个函数必须用来获取正确的值。如果传递一个没有存储的关系，比如一个视图，那么这个函数返回NULL。 pg_relation_filepath(relation regclass) 描述：指定关系的文件路径名。只能用于非段页式关系。 返回值类型：text 备注：pg_relation_filepath类似于pg_relation_filenode，但是它返回关系的整个文件路径名（相对于数据库集群的数据目录PGDATA）。 段页式关系建议使用段页式相关函数或视图，例如： SELECT e.*, f.file_name FROM gs_seg_extents e, gs_seg_datafiles f WHERE e.tablespace_name = f.tablespace_name AND e.bucketnode = f.bucketnode ADN e.file_id = f.file_id ADN e.forknum = f.forknum; get_large_table_name(relfile_node text, threshold_size_gb int8) 描述：根据表的文件编码（relfile_node）查询对应的表大小（单位为GB）是否超过阈值（threshold_size_gb），如果超过则返回模式名和表名（形式为schemaname.tablename）， 否则返回字符串'null'。 返回值类型：text pg_filenode_relation(tablespacename, relname) 描述：获取对应的tablespace和relfilenode所对应的表名。 返回类型：regclass pg_partition_filenode(partition_oid) 描述：获取到指定分区表的oid锁对应的filenode。 返回类型：oid pg_partition_filepath(partition_oid) 描述：指定分区的文件路径名。只能用于非段页式关系。 返回值类型：text 备注：段页式关系建议使用段页式相关函数或视图，例如： SELECT e.*, f.file_name FROM gs_seg_extents e, gs_seg_datafiles f WHERE e.tablespace_name = f.tablespace_name ADN e.bucketnode = f.bucketnode ADN e.file_id = f.file_id ADN e.forknum = f.forknum;