Optimize placement rules in sql #10736

Icemap · 2022-07-29T13:35:15Z

First-time contributors' checklist

I've signed Contributor License Agreement that's required for repo owners to accept my contribution.

What is changed, added or deleted? (Required)

重构整篇 Placement Rules in SQL 文档，用户反馈结构较乱。

规范用词：
- 同义的 参数、选项，统一为 参数
- 同义的 放置规则、放置策略，统一为 放置规则 （与 configure-placement-rules.md 保持一致）
- 其他不严谨的用词
更改结构：
- 将 绑定放置规则 中，创建、更新、删除放置规则的部分单独成章。
- 高级参数 中，不应放在 示例 下的部分，转为在 放置规则参数参考 一章中描述。
参数解释：
- 添加了参数的解释，如 SCHEDULE 中的 EVEN/ MAJORITY_IN_PRIMARY 原本无任何解释，SQL 参数亦无。需要相关技术审核，以防出现谬误。
- 更改了 PRIMARY_REGION / REGIONS 中较晦涩的句法。

Which TiDB version(s) do your changes apply to? (Required)

Tips for choosing the affected version(s):

By default, CHOOSE MASTER ONLY so your changes will be applied to the next TiDB major or minor releases. If your PR involves a product feature behavior change or a compatibility change, CHOOSE THE AFFECTED RELEASE BRANCH(ES) AND MASTER.

For details, see tips for choosing the affected versions (in Chinese).

What is the related PR or file link(s)?

This PR is translated from:
Other reference link(s):

Do your changes match any of the following descriptions?

Delete files
Change aliases
Need modification after applied to another branch
Might cause conflicts after applied to another branch

ti-chi-bot · 2022-07-29T13:35:18Z

[REVIEW NOTIFICATION]

This pull request has not been approved.

To complete the pull request process, please ask the reviewers in the list to review by filling /cc @reviewer in the comment.
After your PR has acquired the required number of LGTMs, you can assign this pull request to the committer in the list by filling /assign @committer in the comment to help you merge this pull request.

The full list of commands accepted by this bot can be found here.

Reviewer can indicate their review by submitting an approval review.
Reviewer can cancel approval by submitting a request changes review.

xhebox

还是需要仔细的想一下, 这个PR虽然从用户角度来说还不错, 但不够严谨.

xhebox · 2022-07-31T03:40:06Z

placement-rules-in-sql.md

@@ -9,7 +9,7 @@ Placement Rules in SQL 特性用于通过 SQL 接口配置数据在 TiKV 集群

 > **注意：**
 >
-> Placement Rules in SQL 底层的实现依赖 PD 提供的放置规则 (placement rules) 功能，参考 [Placement Rules 使用文档](/configure-placement-rules.md)。在 Placement Rules in SQL 语境下，放置规则既可以代指绑定对象的放置策略 (placement policy)，也可以代指 TiDB 发给 PD 的放置规则。
+> Placement Rules in SQL 底层的实现依赖 PD 提供的放置规则 (placement rules) 功能，参考 [Placement Rules 使用文档](/configure-placement-rules.md)。在 Placement Rules in SQL 语境下，放置规则既可以代指绑定对象的放置规则 (placement policy)，也可以代指 TiDB 发给 PD 的放置规则。


放置规则和放置策略是有意为止. 因为本质上placement rules是PD的feat, 而placement rules in SQL是tidb的feat. 所以故意在placement rules in SQL方面使用放置策略, 而PD沿用原有的放置规则翻译.

xhebox · 2022-07-31T03:43:32Z

placement-rules-in-sql.md

+**参数描述**
+
+- `{policy_name}`: 策略名。
+- `{primary_region}`: Raft Leader 将放置在 `region` 标签与该值相等的 TiKV 节点上。
+- `{regions}`: 这是一个英文半角逗号分隔的列表，Raft Followers 将放置在 `region` 标签与该列表中每一个对象相等的 TiKV 节点上。
+
+如策略名称为 `my_policy`, Raft 的 Leader 希望放置于 `region` 带有 `us-east-1` 的 TiKV, Raft 的 Follower 希望放置于 `region` 带有 `us-east-1` 或 `us-west-1` 的 TiKV 时，SQL 语句为：


我不知道应不应该在这里解释这么多, 因为实际上/sql-statements/sql-statement-create-placement-policy.md有更详细的解释. 如果要在入口文档解释这么多, 那子文档就没有意义了. 下面几个语句同理. 你也许可以提示一下还有子文档这件事情. 这个可以请文档的同学来看一下.

而且这是一个英文半角逗号分隔的列表，Raft Followers 将放置在 region 标签与该列表中每一个对象相等的 TiKV 节点上。这个是有问题的. Sugar syntax有一个默认数量, 如果你指定的比默认数量还多, 就不会每个都有follower.

您好，提示有子文档这个链接蛮好，但是参数描述在子文档并没有明显体现，是否有必要对子文档进行补充说明。

这个当然是可以有的, 子文档按道理说是最终参考, 应该明确.

xhebox · 2022-07-31T03:44:42Z

placement-rules-in-sql.md

 ```

-## 查看放置规则
+## 查询表已绑定放置规则名称


不通顺, 有语病

xhebox · 2022-07-31T03:45:01Z

placement-rules-in-sql.md


-要修改放置策略，你可以使用 [`ALTER PLACEMENT POLICY`](/sql-statements/sql-statement-alter-placement-policy.md) 语句。修改将传播到所有绑定此放置策略的对象。
+[创建放置规则](#创建放置规则)后，才可绑定放置规则。可使用 `CREATE TABLE` 或者 `ALTER TABLE` 将策略绑定至表或分区表。放置规则为全局作用域，不与任何数据库表结构相关联。因此，绑定放置规则时，无需任何额外的权限。


语句需要链接子文档.

xhebox · 2022-07-31T03:48:29Z

placement-rules-in-sql.md


-除以上配置选项外，你还可以使用高级配置，详细介绍见[高级放置选项](#高级放置选项)。
+放置规则高级参数提供更高的灵活性，常用参数与高级参数两者**不可**同时使用。若在较复杂的场景下，需要更灵活地放置数据，可使用高级放置参数：


放置选项 PRIMARY_REGION、REGIONS 和 SCHEDULE 可满足数据放置的基本需求，但会缺乏一些灵活性。在较复杂的场景下，若需要更灵活地放置数据，可以使用高级放置选项 CONSTRAINTS 和 FOLLOWER_CONSTRAINTS。PRIMARY_REGION、REGIONS 和 SCHEDULE 选项不可与 CONSTRAINTS 选项同时指定，否则会报错。

这个详细说明建议保留, 或者至少应该有个明确规则. 因为比如FOLLOWERS其实是两个参数共有的选项. 不明说有些语言不详, 可能造成混淆.

shawn0915 · 2022-08-05T02:04:55Z

@TomShawn
有几点建议，PTAL.

格式：有几处加粗斜体显示不对，建议修正
typo：查询表已绑定放置规则名称, myplacementpolicy 应为 my_policy
其他：工具兼容性， “BR 兼容性” 的页面，并没有“放置规则”相关说明
易用：建议将create table的示例中加入drop table if exists t1;，不然将示例中的语句复制出来测试时还需要再手动删一次表。
补充：建议补充【重置库、表绑定的放置规则】章节，

ALTER DATABASE test PLACEMENT POLICY default;
ALTER TABLE t1 PLACEMENT POLICY default;

ti-chi-bot · 2022-11-11T09:48:49Z

@Icemap: PR needs rebase.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

qiancai · 2023-02-24T11:45:20Z

Removed the needs-cherry-pick-release-6.3 label because the v6.3 docs have been archived at https://docs-archive.pingcap.com/zh/tidb/v6.3 and will no longer receive new updates.

qiancai · 2023-04-06T07:03:00Z

Removed the needs-cherry-pick-release-6.4 label because the v6.4 docs have been archived at https://docs-archive.pingcap.com/zh/tidb/v6.4 and will no longer receive new updates.

qiancai · 2023-07-07T06:11:33Z

Removed the needs-cherry-pick-release-6.6 label because the v6.6 docs have been archived at https://docs-archive.pingcap.com/zh/tidb/v6.6 and will no longer receive new updates.

qiancai · 2023-10-20T07:57:56Z

Removed the needs-cherry-pick-release-7.2 label because the v7.2 docs have been archived at https://docs-archive.pingcap.com/zh/tidb/v7.2 and will no longer receive new updates.

ti-chi-bot · 2024-01-26T10:59:45Z

@Icemap: The following test failed, say /retest to rerun all failed tests or /retest-required to rerun all mandatory failed tests:

Test name	Commit	Details	Required	Rerun command
pull-verify	`dc43e54`	link	true	`/test pull-verify`

Full PR test history. Your PR dashboard.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. I understand the commands that are listed here.

[Update] reform placement-rules-in-sql

dc43e54

ti-chi-bot requested a review from TomShawn July 29, 2022 13:35

ti-chi-bot added missing-translation-status This PR does not have translation status info. size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Jul 29, 2022

Oreoxmt added the translation/doing This PR’s assignee is translating this PR. label Jul 29, 2022

ti-chi-bot removed the missing-translation-status This PR does not have translation status info. label Jul 29, 2022

Oreoxmt added type/enhancement The issue or PR belongs to an enhancement. missing-translation-status This PR does not have translation status info. labels Jul 29, 2022

Oreoxmt self-requested a review July 29, 2022 13:47

shichun-0415 removed the missing-translation-status This PR does not have translation status info. label Jul 30, 2022

xhebox reviewed Jul 31, 2022

View reviewed changes

TomShawn self-assigned this Aug 1, 2022

TomShawn added the area/sql-infra Indicates that the Issue or PR belongs to the area of sql-infra and sql-metadata. label Aug 4, 2022

TomShawn added the needs-cherry-pick-release-6.2 label Aug 15, 2022

TomShawn added the needs-cherry-pick-release-6.3 label Sep 29, 2022

ti-chi-bot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Nov 11, 2022

TomShawn added the needs-cherry-pick-release-6.4 label Nov 16, 2022

TomShawn added the needs-cherry-pick-release-6.5 Should cherry pick this PR to release-6.5 branch. label Dec 28, 2022

TomShawn removed the needs-cherry-pick-release-6.2 label Jan 31, 2023

TomShawn added the needs-cherry-pick-release-6.6 label Feb 17, 2023

qiancai removed the needs-cherry-pick-release-6.3 label Feb 24, 2023

lilin90 changed the title ~~[Update] reform placement-rules-in-sql~~ Optimize placement rules in sql Mar 30, 2023

lilin90 removed the request for review from TomShawn March 30, 2023 06:08

lilin90 assigned Oreoxmt and unassigned TomShawn Mar 30, 2023

qiancai removed the needs-cherry-pick-release-6.4 label Apr 6, 2023

Oreoxmt added the needs-cherry-pick-release-7.1 Should cherry pick this PR to release-7.1 branch. label May 29, 2023

Oreoxmt added the needs-cherry-pick-release-7.2 label Jun 28, 2023

qiancai removed the needs-cherry-pick-release-6.6 label Jul 7, 2023

qiancai removed the needs-cherry-pick-release-7.2 label Oct 20, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Optimize placement rules in sql #10736

Optimize placement rules in sql #10736

Icemap commented Jul 29, 2022 •

edited by lilin90

Loading

ti-chi-bot commented Jul 29, 2022

xhebox left a comment

xhebox Jul 31, 2022

xhebox Jul 31, 2022 •

edited

Loading

shawn0915 Aug 1, 2022

xhebox Aug 1, 2022

xhebox Jul 31, 2022

xhebox Jul 31, 2022

xhebox Jul 31, 2022 •

edited

Loading

shawn0915 commented Aug 5, 2022 •

edited

Loading

ti-chi-bot commented Nov 11, 2022

qiancai commented Feb 24, 2023

qiancai commented Apr 6, 2023

qiancai commented Jul 7, 2023

qiancai commented Oct 20, 2023

ti-chi-bot bot commented Jan 26, 2024


		要修改放置策略，你可以使用 [`ALTER PLACEMENT POLICY`](/sql-statements/sql-statement-alter-placement-policy.md) 语句。修改将传播到所有绑定此放置策略的对象。
		[创建放置规则](#创建放置规则)后，才可绑定放置规则。可使用 `CREATE TABLE` 或者 `ALTER TABLE` 将策略绑定至表或分区表。放置规则为全局作用域，不与任何数据库表结构相关联。因此，绑定放置规则时，无需任何额外的权限。


		除以上配置选项外，你还可以使用高级配置，详细介绍见[高级放置选项](#高级放置选项)。
		放置规则高级参数提供更高的灵活性，常用参数与高级参数两者不可同时使用。若在较复杂的场景下，需要更灵活地放置数据，可使用高级放置参数：

Optimize placement rules in sql #10736

Are you sure you want to change the base?

Optimize placement rules in sql #10736

Conversation

Icemap commented Jul 29, 2022 • edited by lilin90 Loading

First-time contributors' checklist

What is changed, added or deleted? (Required)

Which TiDB version(s) do your changes apply to? (Required)

What is the related PR or file link(s)?

Do your changes match any of the following descriptions?

ti-chi-bot commented Jul 29, 2022

xhebox left a comment

Choose a reason for hiding this comment

xhebox Jul 31, 2022

Choose a reason for hiding this comment

xhebox Jul 31, 2022 • edited Loading

Choose a reason for hiding this comment

shawn0915 Aug 1, 2022

Choose a reason for hiding this comment

xhebox Aug 1, 2022

Choose a reason for hiding this comment

xhebox Jul 31, 2022

Choose a reason for hiding this comment

xhebox Jul 31, 2022

Choose a reason for hiding this comment

xhebox Jul 31, 2022 • edited Loading

Choose a reason for hiding this comment

shawn0915 commented Aug 5, 2022 • edited Loading

ti-chi-bot commented Nov 11, 2022

qiancai commented Feb 24, 2023

qiancai commented Apr 6, 2023

qiancai commented Jul 7, 2023

qiancai commented Oct 20, 2023

ti-chi-bot bot commented Jan 26, 2024

Icemap commented Jul 29, 2022 •

edited by lilin90

Loading

xhebox Jul 31, 2022 •

edited

Loading

xhebox Jul 31, 2022 •

edited

Loading

shawn0915 commented Aug 5, 2022 •

edited

Loading