编辑

SQL命令模板

本模板使用 ADMIN SET REPLICA STATUS 命令为例介绍 SQL 命令写作的统一要求。

  • 正文如果引用了代码里的参数或参数取值,使用**倒引号**(``)进行引用,例如 *cachesize*,便于区分和识别。

  • 正文中提到一条SQL命令或者关键字,如果没有使用任何标记,则需要全大写,比如“SELECT 语句可用于查询符合条件的记录”,“您可以使用 GROUP BY 对该列数据进行分组”,“LIMIT 关键字定义了输出了记录条数”

ADMIN SET REPLICA STATUS

标题使用命令的英文名称,全大写,确保拼写正确。

功能

设置指定分片的副本状态。该命令目前仅用于手动将副本状态设置为 badok

简要描述命令的功能,可直接使用动词开头。可以补充相关说明。

语法

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:副本的状态,必选参数,当前仅支持设置为 badok。设置为 ok 表示系统自动修复指定副本。设置为 bad 状态的副本可能会被立即删除,请谨慎操作。如果指定的分片不存在,或副本状态已经是 bad,该副本会被忽略。

对语法结构里出现的参数进行解释。

  • 参数说明一般包括参数含义、是否必选、取值格式、取值范围、单位、使用注意事项或限制条件等。

  • 建议使用**无序**列表的样式来组织参数说明。如果参数较多,且参数说明较复杂,也可以使用表格来组织。使用表格时,可以包含如下列:参数名称,数据类型(可选),示例值(可选),参数说明。

注意事项(可选)

执行命令时需要特别注意的事项或者限制,比如某个参数取值会带来的影响。

示例

示例一:设置 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");
  • 需要描述每一个示例的作用和目的,帮助用户快速了解该示例场景。

  • 如果有多个示例,可以使用示例1,示例2的样式来组织。

  • 如果一个示例中包含多个场景,可对每一个场景的代码加上注释,便于用户快速区分场景。

  • 注释如果是完整句,需加上句号。