SQL 命令模板
-
请提供完整的从 CREATE TABLE,INSERT/LOAD,到查询结果的示例。
-
正文如果引用了代码里的参数或参数取值,使用反引号(``)进行引用,例如
cachesize,便于区分和识别。 -
正文中提到 SQL 命令或关键字,如果没有使用任何标记,则需要全大写,比如 “SELECT 语句可用于查询符合条件的记录”,“您可以使用 GROUP BY 对该列数据进行分组”,“LIMIT 关键字定义了输出了记录条数”。
本模板使用
ADMIN SET REPLICA STATUS命令为例介绍 SQL 命令写作的统一要求。
ADMIN SET REPLICA STATUS
标题使用命令的英文名称,全大写,确保拼写正确。
功能
设置指定分片的副本状态。该命令目前仅用于手动将副本状态设置为 bad 或 ok。
简要描述命令的功能,可直接使用动词开头。可以补充相关使用场景,使用说明,支持的版本。
语法
ADMIN SET REPLICA STATUS
PROPERTIES("key" = "value", ...);
需检查语法的正确性,可选内容用 [] 包裹。语法需要用代码块包裹。*
-
使用合理的换行和缩进。
-
代码里不能包含中文字符,例如中文分号、逗号、或引号。
-
代码内的关键字大写。例如:
SELECT ta.x, count(ta.y) AS y, sum(tb.z) AS z
FROM (
SELECT a AS x, b AS y
FROM t) ta
JOIN tb
ON ta.x = tb.x
WHERE tb.a > 10
GROUP BY ta.x
ORDER BY ta.x, z
LIMIT 10
参数说明
PROPERTIES:取值以 key-value 对出现。当前支持如下属性:
tablet_id:分片ID,必选参数。backend_id:分片所属BE的ID,必选参数。status:副本的状态,必选参数,当前仅支持设置为bad或ok。设置为ok表示系统自动修复指定副本。设置为bad状态的副本可能会被立即删除,请谨慎操作。如果指定的分片不存在,或副本状态已经是bad,该副本会被忽略。
对语法里出现的参数进行解释。
-
参数说明一般包括参数含义、是否必选、取值格式 (if any)、取值范围 (if any)、单位 (if any)、使用注意事项或限制条件等。
-
建议使用无序列表的样式来组织参数说明。如果参数较多,且参数说明较复杂,也可以使用表格来组织。使用表格时,可以包含如下列:参数名称,数据类型(可选),示例值(可选),默认值,参数说明。
返回字段 (可选)
执行该命令返回的字段,以及字段的说明。如果某个字段会返回多个值,则需要告知用户每个返回值分别是什么,以及在什么场景下会返回哪个值。
注意事项(可选)
执行命令时需要特别注意的事项或者限制,比如某个参数取值会带来的影响或报错。
示例
示例一:设置 tablet 10003 在 BE 10001 上的副本状态为 bad。
ADMIN SET REPLICA STATUS
PROPERTIES("tablet_id" = "10003", "backend_id" = "10001", "status" = "bad");
示例二:设置 tablet 10003 在 BE 10001 上的副本状态为 ok。
ADMIN SET REPLICA STATUS
PROPERTIES("tablet_id" = "10003", "backend_id" = "10001", "status" = "ok");
-
需要描述示例的作用和目的,帮助用户快速了解示例场景。
-
如果一个示例中包含多个场景,可对每一个场景的代码加上注释,便于用户快速区分场景。
-
提供完整示例,从建表,到导入数据,到查询,以及查询结果。
-
注释如果是完整句,需加上句号。
相关文档
可选。与该命令强相关的文档,帮助用户理解和快速使用。比如命令对应的特性功能文档,建表命令对应的增/删/改命令等。
本文来自 StarRocks 文档贡献者,按 Apache 2.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。
