Add docs for placement rules in SQL by TomShawn · Pull Request #7444 · pingcap/docs-cn

TomShawn · 2021-11-09T08:26:48Z

What is changed, added or deleted? (Required)

Add docs for placement rules in SQL

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: Add docs for placement rules in SQL docs#6618 Refine placement rules in sql docs#6766
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 · 2021-11-09T08:26:50Z

[REVIEW NOTIFICATION]

This pull request has been approved by:

Liuxiaozhen12
hfxsd

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.

Details

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

TomShawn · 2021-11-09T08:29:29Z

system-variables.md

+
+- 作用域：SESSION | GLOBAL
+- 默认值：`ON`
+- 该变量用于控制 DDL 语句是否验证通过 [Placement Rules in SQL](/placement-rules-in-sql.md) 指定的放置规则。


这一句的英文我读不太明白。PTAL

TOC.md

xhebox

标注了我觉得描述不太准确的地方, 可以作为参考

information-schema/information-schema-placement-rules.md

information-schema/information-schema.md

placement-rules-in-sql.md

xhebox · 2021-11-12T10:11:43Z

placement-rules-in-sql.md

+
+## 指定放置选项
+
+要使用 Placement Rules in SQL 特性，你需要在 SQL 语句中指定一个或多个放置选项 (placement option)。可通过*直接放置 (direct placement)* 或*放置策略 (placement policy)* 来指定放置选项。


direct placement其实可以看成式 "匿名放置策略"

placement-rules-in-sql.md

xhebox · 2021-11-12T10:42:12Z

placement-rules-in-sql.md

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


是PRIMARY_REGION...和CONSTRAINTS不能混用, 应该说这两类不能混用.

是说【PRIMARY_REGION、REGIONS 和 SCHEDULE】不能和【CONSTRAINTS】混用吗？

Suggested change

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

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

包括XXX_CONSTRAINTS也不能混用, 其实就是所有高级放置新介绍的选项都不能和REGION/SCHEDULE混用.

已修改 comment

sql-statements/sql-statement-create-placement-policy.md

system-variables.md

information-schema/information-schema-placement-rules.md

placement-rules-in-sql.md

configure-placement-rules.md

placement-rules-in-sql.md

hfxsd · 2021-11-15T02:21:24Z

sql-statements/sql-statement-show-placement.md

+>
+> Placement Rules in SQL 是一项 TiDB v5.3.0 中引入的实验特性。特性的语法在 GA 前可能会发生变化，还可能存在 bug。如果你知晓潜在的风险，可通过执行 `SET GLOBAL tidb_enable_alter_placement = 1;` 来开启该实验特性。
+
+`SHOW PLACEMENT` 汇总了直接放置 (direct placement) 和放置策略 (placement policy) 中的所有放置选项，并以规范的形式呈现这些选项信息。


这个和 SHOW PLACEMENT FOR 高度相似。建议增加一个说明，介绍一下二者的区别。

@xhebox SHOW PLACEMENT FOR 里的描述是“SHOW PLACEMENT FOR 用于汇总直接放置 (direct placement) 和放置策略 (placement policy) 中所有的放置选项，并为特定表、数据库或分区以规范形式呈现这些选项信息。”

SHOW PLACEMENT FOR 和 SHOW PLACEMENT 还有其他区别吗？

show placement 会打印policy的名字和对应的选项, 以及所有库表和上面的选项, show placement for只显示库表上的选项.

show placement | POLICY p1 | PRIMARY_REGION="us-east-1" REGIONS="us-east-1" | | TABLE test.t2 | PRIMARY_REGION="us-east-1" REGIONS="us-east-1" | show placement for | TABLE test.t2 | PRIMARY_REGION="us-east-1" REGIONS="us-east-1" |

这个设计是这样, policy是一些全局, 有名字的, 预先配置好的, placement option(放置选项), 通过执行语句可以绑定到库表上. . direct placement其实就是匿名策略, 直接把选项绑定上去.

TomShawn · 2021-11-15T04:02:42Z

@xhebox @hfxsd @en-jin19 Thanks for your comment! 🌹 PTAL again~

xhebox · 2021-11-15T04:04:55Z

@xhebox @hfxsd @en-jin19 Thanks for your comment! 🌹 PTAL again~

I think you could resolve addressed comments, so that reviewers only need to review interested parts of the document, and unresolved comments.

placement-rules-in-sql.md

Co-authored-by: Enwei <jinenwei@pingcap.com>

placement-rules-in-sql.md

ti-chi-bot · 2021-11-15T09:42:30Z

@xhebox: Thanks for your review. The bot only counts approvals from reviewers and higher roles in list, but you're still welcome to leave your comments.

Details

In response to this:

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 ti-community-infra/tichi repository.

Co-authored-by: Enwei <jinenwei@pingcap.com>

placement-rules-in-sql.md

system-variables.md

en-jin19

rest LGTM

ti-chi-bot · 2021-11-15T10:39:38Z

@en-jin19: Thanks for your review. The bot only counts approvals from reviewers and higher roles in list, but you're still welcome to leave your comments.

Details

In response to this:

rest LGTM

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 ti-community-infra/tichi repository.

Co-authored-by: Enwei <jinenwei@pingcap.com>

TomShawn · 2021-11-15T11:34:37Z

/merge

ti-chi-bot · 2021-11-15T11:34:40Z

This pull request has been accepted and is ready to merge.

Details

Commit hash: 4ffe36b

Add docs for placement rules in SQL

38808b0

TomShawn added translation/from-docs This PR is translated from a PR in pingcap/docs. area/sql-infra Indicates that the Issue or PR belongs to the area of sql-infra and sql-metadata. v5.3 This PR/issue applies to TiDB v5.3. labels Nov 9, 2021

TomShawn requested review from djshow832, nolouch and xhebox November 9, 2021 08:26

ti-chi-bot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label Nov 9, 2021

TomShawn commented Nov 9, 2021

View reviewed changes

TOC.md Outdated Show resolved Hide resolved

Update TOC.md

8cac2b0

TomShawn requested a review from en-jin19 November 9, 2021 09:49

add user scenarios

c34b3ad

xhebox reviewed Nov 12, 2021

View reviewed changes

en-jin19 reviewed Nov 15, 2021

View reviewed changes

information-schema/information-schema-placement-rules.md Outdated Show resolved Hide resolved

en-jin19 reviewed Nov 15, 2021

View reviewed changes

placement-rules-in-sql.md Outdated Show resolved Hide resolved

en-jin19 reviewed Nov 15, 2021

View reviewed changes

placement-rules-in-sql.md Outdated Show resolved Hide resolved

en-jin19 reviewed Nov 15, 2021

View reviewed changes

placement-rules-in-sql.md Outdated Show resolved Hide resolved

en-jin19 reviewed Nov 15, 2021

View reviewed changes

placement-rules-in-sql.md Outdated Show resolved Hide resolved

en-jin19 reviewed Nov 15, 2021

View reviewed changes

placement-rules-in-sql.md Outdated Show resolved Hide resolved

en-jin19 reviewed Nov 15, 2021

View reviewed changes

placement-rules-in-sql.md Outdated Show resolved Hide resolved

en-jin19 reviewed Nov 15, 2021

View reviewed changes

placement-rules-in-sql.md Outdated Show resolved Hide resolved

en-jin19 reviewed Nov 15, 2021

View reviewed changes

placement-rules-in-sql.md Outdated Show resolved Hide resolved

en-jin19 reviewed Nov 15, 2021

View reviewed changes

placement-rules-in-sql.md Outdated Show resolved Hide resolved

TomShawn added the status/require-change Needs the author to address comments. label Nov 15, 2021

hfxsd reviewed Nov 15, 2021

View reviewed changes

TomShawn added 2 commits November 15, 2021 11:53

address comments from xhebox, en-jin19 and hfxsd

cf3a918

Update placement-rules-in-sql.md

098ad0e

TomShawn requested a review from xhebox November 15, 2021 03:59

TomShawn requested review from en-jin19 and hfxsd November 15, 2021 03:59

TomShawn added status/PTAL This PR is ready for reviewing. and removed status/require-change Needs the author to address comments. labels Nov 15, 2021

en-jin19 reviewed Nov 15, 2021

View reviewed changes

placement-rules-in-sql.md Outdated Show resolved Hide resolved

Update placement-rules-in-sql.md

634d831

Co-authored-by: Enwei <jinenwei@pingcap.com>

en-jin19 reviewed Nov 15, 2021

View reviewed changes

placement-rules-in-sql.md Show resolved Hide resolved

en-jin19 reviewed Nov 15, 2021

View reviewed changes

placement-rules-in-sql.md Outdated Show resolved Hide resolved

xhebox approved these changes Nov 15, 2021

View reviewed changes

Update placement-rules-in-sql.md

7fcb3c2

Co-authored-by: Enwei <jinenwei@pingcap.com>

en-jin19 reviewed Nov 15, 2021

View reviewed changes

placement-rules-in-sql.md Outdated Show resolved Hide resolved

en-jin19 reviewed Nov 15, 2021

View reviewed changes

placement-rules-in-sql.md Outdated Show resolved Hide resolved

en-jin19 reviewed Nov 15, 2021

View reviewed changes

placement-rules-in-sql.md Outdated Show resolved Hide resolved

en-jin19 reviewed Nov 15, 2021

View reviewed changes

system-variables.md Outdated Show resolved Hide resolved

en-jin19 approved these changes Nov 15, 2021

View reviewed changes

Apply suggestions from code review

4ffe36b

Co-authored-by: Enwei <jinenwei@pingcap.com>

hfxsd approved these changes Nov 15, 2021

View reviewed changes

ti-chi-bot added the status/LGT1 Indicates that a PR has LGTM 1. label Nov 15, 2021

Liuxiaozhen12 approved these changes Nov 15, 2021

View reviewed changes

ti-chi-bot added status/LGT2 Indicates that a PR has LGTM 2. and removed status/LGT1 Indicates that a PR has LGTM 1. labels Nov 15, 2021

ti-chi-bot added the status/can-merge Indicates a PR has been approved by a committer. label Nov 15, 2021

TomShawn merged commit 3a5ffb3 into pingcap:master Nov 15, 2021

TomShawn deleted the placement-rule-sql-in branch November 15, 2021 11:34


		## 指定放置选项

		要使用 Placement Rules in SQL 特性，你需要在 SQL 语句中指定一个或多个放置选项 (placement option)。可通过直接放置 (direct placement) 或放置策略 (placement policy) 来指定放置选项。


		### 高级放置

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

Conversation

TomShawn commented Nov 9, 2021

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?

Uh oh!

ti-chi-bot commented Nov 9, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

xhebox left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TomShawn Nov 15, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TomShawn Nov 15, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xhebox Nov 15, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TomShawn commented Nov 15, 2021

Uh oh!

xhebox commented Nov 15, 2021

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ti-chi-bot commented Nov 15, 2021

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

en-jin19 left a comment

Choose a reason for hiding this comment

Uh oh!

ti-chi-bot commented Nov 15, 2021

ti-chi-bot commented Nov 9, 2021 •

edited

Loading

TomShawn Nov 15, 2021 •

edited

Loading

TomShawn Nov 15, 2021 •

edited

Loading

xhebox Nov 15, 2021 •

edited

Loading