How to write SQL command doc.md

SQL命令模板

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

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

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

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，该副本会被忽略。

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

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

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

注意事项（可选）

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

示例

示例一：设置 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的样式来组织。

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

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