StarRocks SQL 命令文档写作规范与模板详解以 ADMIN SET REPLICA STATUS 为例【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks本篇技术指南围绕仓库中的 SQL 命令文档模板 展开系统讲解 StarRocks 官方 SQL Reference 文档的统一写作规范——包括六个标准章节的组织方式、语法代码块与参数表的要求以及完整可运行示例的硬性标准。文章以ADMIN SET REPLICA STATUS这一命令作为贯穿示例并结合 FE 侧文法、AST、语义分析与执行链路的真实源码逐层印证帮助读者既能按规范撰写高质量 SQL 命令文档也能深刻理解该命令的底层实现与运维风险。模板的定位SQL 命令文档的统一骨架在 StarRocks 的英文文档目录docs/en/sql-reference/下存放着数百篇 SQL 命令说明文档。为了保证这些文档在结构、术语、示例层面高度一致方便开发者检索、Agent 与 LLM 解析引用仓库提供了这份 SQL_command_template.md 作为内部写作模板。注意其 frontmatter 中标注了unlisted: true意味着该页面不会出现在文档侧边栏中其角色是写作规范本身而非对外发布的 SQL 参考条目。模板开篇即给出了三条贯穿全文的硬性要求正文中的命令与关键字一律大写。例如应写作 The SELECT statement is used to query records..., You can use GROUP BY to group data, The LIMIT keyword specifies the maximum number of records that can be returned。正文中引用参数或参数值须用双反引号包裹例如cachesize。示例必须完整包括CREATE TABLE、INSERT/LOAD数据、查询语句、查询结果以及结果说明确保示例可复制、可运行、可自证。模板特意选择ADMIN SET REPLICA STATUS作为示范命令因为它是一个参数结构典型、操作语义有风险警示的管理类 DDL能覆盖模板中几乎所有写作要点。六个标准章节模板的核心骨架模板规定一篇 SQL 命令文档应包含以下小节每一节都有明确的写作目标章节职责模板中的要点Description说明命令功能可附加相关描述与使用备注Syntax给出命令语法代码块包裹、合理换行缩进、关键字大写、不得出现中文标点Parameters逐项解释参数含义、值格式、取值范围、是否必填、备注可用列表或表格Return fields说明返回字段若某字段有多个取值须列出各取值对应的返回场景Usage notes可选补充注意事项按需添加使用前提与警示Examples给出使用示例可多个示例多场景时在代码中用注释区分下面结合模板原文逐一展开。Description功能描述用一两句话说明命令做什么。模板示例中对ADMIN SET REPLICA STATUS的描述是指定一个 tablet 的副本状态用于手动将 tablet 的副本状态设置为bad或ok。描述应聚焦命令的核心动作与适用场景不展开实现细节。Syntax语法规范模板对语法块的约束最为细致语法必须放在代码块中且须符合编码规范注意合理换行与缩进避免一行过长代码中禁止出现中文字符包括中文分号、中文逗号等SQL 关键字一律大写。模板给出了一个关键字大写的示范查询规范了子查询、JOIN、GROUP BY、ORDER BY、LIMIT的排版风格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 10Parameters参数说明参数描述是 SQL 文档信息密度最高的部分。模板要求每个参数的说明尽量包含参数含义、值格式、取值范围、是否必填以及必要的附加备注。组织方式上简单场景用无序列表复杂场景可整理为表格表格可包含四列参数名、值类型可选、示例值可选、参数描述。Return fields返回字段模板要求描述命令返回的字段若某个字段存在多个取值必须列出这些取值及各自出现的场景。对于ADMIN SET REPLICA STATUS这类不返回结果集的管理 DDL该小节在模板中保留为占位说明——从模板结构看撰写时可在该节说明命令不返回结果集或按需省略。Usage notes使用注意事项可选用于补充命令的使用前提与安全警示。模板将该节标记为可选但强烈建议在命令存在副作用如删除副本、跳过损坏数据时补全。Examples示例模板对示例的要求是最严格的必须提供CREATE TABLE INSERT/LOAD 数据 查询 查询结果 结果说明的完整闭环而不是孤立的命令片段。同时鼓励提供多个示例且当单个示例包含多个场景时须在代码内用注释标注每个场景方便读者快速区分。模板实例详解ADMIN SET REPLICA STATUS模板以ADMIN SET REPLICA STATUS为完整示范其正文内容本身就是一篇符合规范的标准 SQL 命令文档现完整继承如下。Description指定一个 tablet 的副本状态。该命令用于手动将 tablet 的副本状态设置为bad或ok。SyntaxADMIN SET REPLICA STATUS PROPERTIES (key value, ...);ParametersPROPERTIES每个属性必须是键值对。支持的属性如下参数是否必填值类型说明tablet_id是数值字符串tablet 的 IDbackend_id是数值字符串tablet 所在 BE 节点的 IDstatus是字符串副本状态。合法值为bad和ok其中ok表示系统会自动修复 tablet 的副本若副本状态被设为bad副本可能被立即删除执行该操作务必谨慎。若指定的 tablet 不存在或副本状态本身就是bad系统会忽略这些副本。Examples示例 1将 BE 10001 上 tablet 10003 的副本状态设置为bad。ADMIN SET REPLICA STATUS PROPERTIES(tablet_id 10003, backend_id 10001, status bad);示例 2将 BE 10001 上 tablet 10003 的副本状态设置为ok。ADMIN SET REPLICA STATUS PROPERTIES(tablet_id 10003, backend_id 10001, status ok);源码级验证从 SQL 文本到元数据状态的完整链路模板描述的语法、参数与行为并非纸面约定它们在 FE 源码中有完整的对应实现。沿着 SQL 执行的四个阶段可以逐层印证文档中的每一条表述。语法层ANTLR 文法在 FE 的 ANTLR 文法文件 StarRocks.g4 中该命令被定义为ADMIN SET REPLICA STATUS properties其中properties由解析器展开为键值对集合PropertySet对应文档中PROPERTIES (key value, ...)的语法形态。AST 层语句对象与常量解析结果落为 AdminSetReplicaStatusStmt.java 中的AdminSetReplicaStatusStmt它继承自DdlStmt并将三个参数名固化为常量TABLET_ID、BACKEND_ID、STATUS。该语句对象内部维护tabletId、backendId与status三个字段初始值分别为-1和null等待语义分析阶段填充——这为后续必填项缺失即报错的校验埋下伏笔。语义分析层参数解析与校验真正的参数校验发生在 AdminStmtAnalyzer.java 的visitAdminSetReplicaStatusStatement中其校验逻辑与文档参数表一一对应tablet_id与backend_id通过Long.parseLong解析为长整型解析失败抛出 invalid id format 语义异常status通过Enums.getIfPresent(ReplicaStatus.class, val.toUpperCase())解析为枚举仅接受BAD与OK两个值其他取值抛出 invalid property value 异常——这与文档中合法值为bad和ok完全一致三个参数缺一不可若解析后tabletId、backendId或status仍未赋值则抛出TABLET_ID, BACKEND_ID and STATUS缺失的语义异常——对应文档参数表中三个参数全部必填的约定解析成功后数值与枚举被回填到语句对象中。执行与持久化层忽略不存在的副本紧急修复受损副本执行阶段由 FE 的 DDL 执行器分发到 LocalMetastore.java 的setReplicaStatus/setReplicaStatusInternal其行为与文档中的风险提示严丝合缝getReplicaAndMeta先通过 tablet 倒排索引查询 tablet 元数据与副本若 tablet 或副本不存在直接返回并仅记录日志——这正是文档所述如果指定的 tablet 不存在系统会忽略这些副本的源码出处状态变更并非直接落盘先构造SetReplicaStatusOperationLog写入 FE 的 EditLogSetReplicaStatusOperationLog.java通过 WAL 回调执行setReplicaBadStatus保证元数据变更可重放、可恢复设置完成后该 tablet 所在分区会被加入TabletChecker的紧急修复队列setTabletForUrgentRepair促使系统尽快修复副本——这就是ok表示系统自动修复背后的调度机制。Replica 对象语义为什么bad可能立即删除副本文档提示若副本状态被设为bad副本可能被立即删除其根因在副本对象 Replica.java 的注释中明确写明当bad与setBadForce同时为 true 时表示该副本不可恢复系统将删除它。ADMIN SET REPLICA STATUS ... status bad正是通过setBadForce强制标记副本为损坏这也是模板反复强调Exercise caution谨慎操作的原因。测试验证行为可被单测复现仓库中的单元测试完整复现了文档的两个示例。在 AdminStmtTest.java 的testAdminSetReplicaStatus中测试先创建表并枚举 tablet 与 backend 的对应关系然后执行admin set replica status properties (tablet_id ..., backend_id ..., status bad)并断言replica.isBad()变为 true随后再执行status ok并断言副本恢复为非 bad 状态——与文档示例 1、示例 2 的语义一一对应。此外PrivilegeCheckerTest.java 中存在针对该语句的权限校验用例从源码结构看执行该命令需要相应的管理类权限普通用户不应拥有随意修改副本状态的能力。用模板撰写新 SQL 命令文档的操作清单结合模板要求与上述源码验证撰写一篇合格的 SQL 命令文档可以遵循以下检查清单标题使用英文命令名全大写作为主题标题注意拼写正确如ADMIN SET REPLICA STATUS六节结构按 Description、Syntax、Parameters、Return fields、Usage notes可选、Examples 组织正文语法块置于代码块中合理换行缩进禁中文标点关键字大写参数表覆盖含义、值格式、取值范围、是否必填与备注复杂场景使用参数名 / 值类型 / 示例值 / 描述四列表格完整示例每个示例都尽量给出 CREATE TABLE、数据导入、查询、查询结果与结果说明的闭环多场景用注释区分风险标注凡涉及数据删除、副本损坏、跳过校验等副作用在 Parameters 或 Usage notes 中明确警示并在源码中核实行为例如本命令中tablet 不存在则忽略bad 副本可能被立即删除均可从 LocalMetastore.java 与 Replica.java 找到依据。对于ADMIN SET REPLICA STATUS本身请务必记住它是一把高风险运维工具bad状态可能导致副本被立即删除仅应在明确知晓后果时使用而ok状态会将 tablet 推入紧急修复队列让系统自动恢复副本。文档规范与源码实现在此相互印证这正是 StarRocks SQL Reference 文档可以放心被开发者、Agent 与 LLM 引用和信赖的原因。【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 StarRocks SQL 命令文档写作规范与模板详解：以 ADMIN SET REPLICA STATUS 为例
StarRocks SQL 命令文档写作规范与模板详解以 ADMIN SET REPLICA STATUS 为例【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks本篇技术指南围绕仓库中的 SQL 命令文档模板 展开系统讲解 StarRocks 官方 SQL Reference 文档的统一写作规范——包括六个标准章节的组织方式、语法代码块与参数表的要求以及完整可运行示例的硬性标准。文章以ADMIN SET REPLICA STATUS这一命令作为贯穿示例并结合 FE 侧文法、AST、语义分析与执行链路的真实源码逐层印证帮助读者既能按规范撰写高质量 SQL 命令文档也能深刻理解该命令的底层实现与运维风险。模板的定位SQL 命令文档的统一骨架在 StarRocks 的英文文档目录docs/en/sql-reference/下存放着数百篇 SQL 命令说明文档。为了保证这些文档在结构、术语、示例层面高度一致方便开发者检索、Agent 与 LLM 解析引用仓库提供了这份 SQL_command_template.md 作为内部写作模板。注意其 frontmatter 中标注了unlisted: true意味着该页面不会出现在文档侧边栏中其角色是写作规范本身而非对外发布的 SQL 参考条目。模板开篇即给出了三条贯穿全文的硬性要求正文中的命令与关键字一律大写。例如应写作 The SELECT statement is used to query records..., You can use GROUP BY to group data, The LIMIT keyword specifies the maximum number of records that can be returned。正文中引用参数或参数值须用双反引号包裹例如cachesize。示例必须完整包括CREATE TABLE、INSERT/LOAD数据、查询语句、查询结果以及结果说明确保示例可复制、可运行、可自证。模板特意选择ADMIN SET REPLICA STATUS作为示范命令因为它是一个参数结构典型、操作语义有风险警示的管理类 DDL能覆盖模板中几乎所有写作要点。六个标准章节模板的核心骨架模板规定一篇 SQL 命令文档应包含以下小节每一节都有明确的写作目标章节职责模板中的要点Description说明命令功能可附加相关描述与使用备注Syntax给出命令语法代码块包裹、合理换行缩进、关键字大写、不得出现中文标点Parameters逐项解释参数含义、值格式、取值范围、是否必填、备注可用列表或表格Return fields说明返回字段若某字段有多个取值须列出各取值对应的返回场景Usage notes可选补充注意事项按需添加使用前提与警示Examples给出使用示例可多个示例多场景时在代码中用注释区分下面结合模板原文逐一展开。Description功能描述用一两句话说明命令做什么。模板示例中对ADMIN SET REPLICA STATUS的描述是指定一个 tablet 的副本状态用于手动将 tablet 的副本状态设置为bad或ok。描述应聚焦命令的核心动作与适用场景不展开实现细节。Syntax语法规范模板对语法块的约束最为细致语法必须放在代码块中且须符合编码规范注意合理换行与缩进避免一行过长代码中禁止出现中文字符包括中文分号、中文逗号等SQL 关键字一律大写。模板给出了一个关键字大写的示范查询规范了子查询、JOIN、GROUP BY、ORDER BY、LIMIT的排版风格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 10Parameters参数说明参数描述是 SQL 文档信息密度最高的部分。模板要求每个参数的说明尽量包含参数含义、值格式、取值范围、是否必填以及必要的附加备注。组织方式上简单场景用无序列表复杂场景可整理为表格表格可包含四列参数名、值类型可选、示例值可选、参数描述。Return fields返回字段模板要求描述命令返回的字段若某个字段存在多个取值必须列出这些取值及各自出现的场景。对于ADMIN SET REPLICA STATUS这类不返回结果集的管理 DDL该小节在模板中保留为占位说明——从模板结构看撰写时可在该节说明命令不返回结果集或按需省略。Usage notes使用注意事项可选用于补充命令的使用前提与安全警示。模板将该节标记为可选但强烈建议在命令存在副作用如删除副本、跳过损坏数据时补全。Examples示例模板对示例的要求是最严格的必须提供CREATE TABLE INSERT/LOAD 数据 查询 查询结果 结果说明的完整闭环而不是孤立的命令片段。同时鼓励提供多个示例且当单个示例包含多个场景时须在代码内用注释标注每个场景方便读者快速区分。模板实例详解ADMIN SET REPLICA STATUS模板以ADMIN SET REPLICA STATUS为完整示范其正文内容本身就是一篇符合规范的标准 SQL 命令文档现完整继承如下。Description指定一个 tablet 的副本状态。该命令用于手动将 tablet 的副本状态设置为bad或ok。SyntaxADMIN SET REPLICA STATUS PROPERTIES (key value, ...);ParametersPROPERTIES每个属性必须是键值对。支持的属性如下参数是否必填值类型说明tablet_id是数值字符串tablet 的 IDbackend_id是数值字符串tablet 所在 BE 节点的 IDstatus是字符串副本状态。合法值为bad和ok其中ok表示系统会自动修复 tablet 的副本若副本状态被设为bad副本可能被立即删除执行该操作务必谨慎。若指定的 tablet 不存在或副本状态本身就是bad系统会忽略这些副本。Examples示例 1将 BE 10001 上 tablet 10003 的副本状态设置为bad。ADMIN SET REPLICA STATUS PROPERTIES(tablet_id 10003, backend_id 10001, status bad);示例 2将 BE 10001 上 tablet 10003 的副本状态设置为ok。ADMIN SET REPLICA STATUS PROPERTIES(tablet_id 10003, backend_id 10001, status ok);源码级验证从 SQL 文本到元数据状态的完整链路模板描述的语法、参数与行为并非纸面约定它们在 FE 源码中有完整的对应实现。沿着 SQL 执行的四个阶段可以逐层印证文档中的每一条表述。语法层ANTLR 文法在 FE 的 ANTLR 文法文件 StarRocks.g4 中该命令被定义为ADMIN SET REPLICA STATUS properties其中properties由解析器展开为键值对集合PropertySet对应文档中PROPERTIES (key value, ...)的语法形态。AST 层语句对象与常量解析结果落为 AdminSetReplicaStatusStmt.java 中的AdminSetReplicaStatusStmt它继承自DdlStmt并将三个参数名固化为常量TABLET_ID、BACKEND_ID、STATUS。该语句对象内部维护tabletId、backendId与status三个字段初始值分别为-1和null等待语义分析阶段填充——这为后续必填项缺失即报错的校验埋下伏笔。语义分析层参数解析与校验真正的参数校验发生在 AdminStmtAnalyzer.java 的visitAdminSetReplicaStatusStatement中其校验逻辑与文档参数表一一对应tablet_id与backend_id通过Long.parseLong解析为长整型解析失败抛出 invalid id format 语义异常status通过Enums.getIfPresent(ReplicaStatus.class, val.toUpperCase())解析为枚举仅接受BAD与OK两个值其他取值抛出 invalid property value 异常——这与文档中合法值为bad和ok完全一致三个参数缺一不可若解析后tabletId、backendId或status仍未赋值则抛出TABLET_ID, BACKEND_ID and STATUS缺失的语义异常——对应文档参数表中三个参数全部必填的约定解析成功后数值与枚举被回填到语句对象中。执行与持久化层忽略不存在的副本紧急修复受损副本执行阶段由 FE 的 DDL 执行器分发到 LocalMetastore.java 的setReplicaStatus/setReplicaStatusInternal其行为与文档中的风险提示严丝合缝getReplicaAndMeta先通过 tablet 倒排索引查询 tablet 元数据与副本若 tablet 或副本不存在直接返回并仅记录日志——这正是文档所述如果指定的 tablet 不存在系统会忽略这些副本的源码出处状态变更并非直接落盘先构造SetReplicaStatusOperationLog写入 FE 的 EditLogSetReplicaStatusOperationLog.java通过 WAL 回调执行setReplicaBadStatus保证元数据变更可重放、可恢复设置完成后该 tablet 所在分区会被加入TabletChecker的紧急修复队列setTabletForUrgentRepair促使系统尽快修复副本——这就是ok表示系统自动修复背后的调度机制。Replica 对象语义为什么bad可能立即删除副本文档提示若副本状态被设为bad副本可能被立即删除其根因在副本对象 Replica.java 的注释中明确写明当bad与setBadForce同时为 true 时表示该副本不可恢复系统将删除它。ADMIN SET REPLICA STATUS ... status bad正是通过setBadForce强制标记副本为损坏这也是模板反复强调Exercise caution谨慎操作的原因。测试验证行为可被单测复现仓库中的单元测试完整复现了文档的两个示例。在 AdminStmtTest.java 的testAdminSetReplicaStatus中测试先创建表并枚举 tablet 与 backend 的对应关系然后执行admin set replica status properties (tablet_id ..., backend_id ..., status bad)并断言replica.isBad()变为 true随后再执行status ok并断言副本恢复为非 bad 状态——与文档示例 1、示例 2 的语义一一对应。此外PrivilegeCheckerTest.java 中存在针对该语句的权限校验用例从源码结构看执行该命令需要相应的管理类权限普通用户不应拥有随意修改副本状态的能力。用模板撰写新 SQL 命令文档的操作清单结合模板要求与上述源码验证撰写一篇合格的 SQL 命令文档可以遵循以下检查清单标题使用英文命令名全大写作为主题标题注意拼写正确如ADMIN SET REPLICA STATUS六节结构按 Description、Syntax、Parameters、Return fields、Usage notes可选、Examples 组织正文语法块置于代码块中合理换行缩进禁中文标点关键字大写参数表覆盖含义、值格式、取值范围、是否必填与备注复杂场景使用参数名 / 值类型 / 示例值 / 描述四列表格完整示例每个示例都尽量给出 CREATE TABLE、数据导入、查询、查询结果与结果说明的闭环多场景用注释区分风险标注凡涉及数据删除、副本损坏、跳过校验等副作用在 Parameters 或 Usage notes 中明确警示并在源码中核实行为例如本命令中tablet 不存在则忽略bad 副本可能被立即删除均可从 LocalMetastore.java 与 Replica.java 找到依据。对于ADMIN SET REPLICA STATUS本身请务必记住它是一把高风险运维工具bad状态可能导致副本被立即删除仅应在明确知晓后果时使用而ok状态会将 tablet 推入紧急修复队列让系统自动恢复副本。文档规范与源码实现在此相互印证这正是 StarRocks SQL Reference 文档可以放心被开发者、Agent 与 LLM 引用和信赖的原因。【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考