fsk119 commented on code in PR #21912: URL: https://github.com/apache/flink/pull/21912#discussion_r1105231662
########## docs/content.zh/docs/dev/table/sql/job.md: ########## @@ -0,0 +1,96 @@ +--- +title: "JOB Statements" +weight: 16 +type: docs +aliases: +- /dev/table/sql/job.html +--- +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +# JOB Statements + +Job 语句用于管理作业的生命周期。 + +目前 Flink SQL 支持以下 JOB 语句： +- SHOW JOBS +- STOP JOB + +## 执行 JOB 语句 + +{{< tabs "show jobs statement" >}} +{{< tab "SQL CLI" >}} + +以下示例展示如何在 [SQL CLI]({{< ref "docs/dev/table/sqlClient" >}}) 中执行 JOB 语句. + +{{< /tab >}} +{{< /tabs >}} + +{{< tabs "show jobs" >}} +{{< tab "SQL CLI" >}} +```sql +Flink SQL> SHOW JOBS; ++----------------------------------+----------+---------+-------------------------+ +| job id | job name | status | start time | ++----------------------------------+----------+---------+-------------------------+ +| 228d70913eab60dda85c5e7f78b5782c | myjob | RUNNING | 2023-02-11T05:03:51.523 | ++----------------------------------+----------+---------+-------------------------+ + +Flink SQL> SET 'state.savepoints.dir'='file:/tmp/'; +[INFO] Execute statement succeed. + +Flink SQL> STOP JOB '228d70913eab60dda85c5e7f78b5782c' WITH SAVEPOINT; ++-----------------------------------------+ +| savepoint path | ++-----------------------------------------+ +| file:/tmp/savepoint-3addd4-0b224d9311e6 | ++-----------------------------------------+ +``` +{{< /tab >}} +{{< /tabs >}} + +## SHOW JOBS + +```sql +SHOW JOBS +``` + +展示 Flink 集群上的作业。 + +<span class="label label-danger">Attention</span> SHOW JOBS 语句仅适用于 [SQL CLI]({{< ref "docs/dev/table/sqlClient" >}}) 或者 [SQL Gateway]({{< ref "docs/dev/table/sql-gateway/overview" >}}). + +## STOP JOB + +```sql +STOP JOB '<job_id>' [WITH SAVEPOINT] [WITH DRAIN] +``` + +停止指定作业。 + +**WITH SAVEPOINT** +在作业停止之前执行 Savepoin。 Savepoint 的路径可以通过集群配置的 +[state.savepoints.dir]({{< ref "docs/deployment/config" >}}#state-savepoints-dir) 指定， +或者通过 `SET` 语句指定（后者有更高优先级）。 + +**WITH DRAIN** +在完成最后一个 Checkpoint 之前将 Watermark 提升至最大。当你想永久停止作业时可以使用。 Review Comment: 在触发 savepoint 之前将 Watermark 提升至最大。该操作会可能会触发窗口的计算。请您注意该操作可能导致您之后从该创建的 savepoint 恢复的作业结果不正确。 ########## docs/content/docs/dev/table/sqlClient.md: ########## @@ -750,7 +750,8 @@ Cluster ID: StandaloneClusterId Job ID: 6f922fe5cba87406ff23ae4a7bb79044 ``` -<span class="label label-danger">Attention</span> The SQL Client does not track the status of the running Flink job after submission. The CLI process can be shutdown after the submission without affecting the detached query. Flink's `restart strategy` takes care of the fault-tolerance. A query can be cancelled using Flink's web interface, command-line, or REST API. +<span class="label label-danger">Attention</span> The status of the submitted Flink jobs could be Review Comment: ``` The SQL Client does not track the status of the running Flink job after submission. The CLI process can be shutdown after the submission without affecting the detached query. Flink's `restart strategy` takes care of the fault-tolerance. Please use the job statements to monitor the detached query status({{< ref "docs/dev/table/sqlClient" >}}#monitoring-job-status) or stop the detached query({{< ref "docs/dev/table/sqlClient" >}}#monitoring-job-status). ``` ########## docs/content/docs/dev/table/sqlClient.md: ########## @@ -537,7 +537,7 @@ information on how to configure connector and format dependencies. {{< top >}} -Use SQL Client to submit job +Executing statements Review Comment: How about using `Usage` here? ########## docs/content/docs/dev/table/sql/job.md: ########## @@ -0,0 +1,97 @@ +--- +title: "JOB Statements" +weight: 16 +type: docs +aliases: +- /dev/table/sql/job.html +--- +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +# JOB Statements + +Job statements are used for management of Flink jobs. + +Flink SQL supports the following JOB statements for now: +- SHOW JOBS +- STOP JOB + +## Run a JOB statement + +{{< tabs "show jobs statement" >}} +{{< tab "SQL CLI" >}} + +The following examples show how to run `JOB` statements in [SQL CLI]({{< ref "docs/dev/table/sqlClient" >}}). + +{{< /tab >}} +{{< /tabs >}} + +{{< tabs "show jobs" >}} +{{< tab "SQL CLI" >}} +```sql +Flink SQL> SHOW JOBS; ++----------------------------------+----------+---------+-------------------------+ +| job id | job name | status | start time | ++----------------------------------+----------+---------+-------------------------+ +| 228d70913eab60dda85c5e7f78b5782c | myjob | RUNNING | 2023-02-11T05:03:51.523 | ++----------------------------------+----------+---------+-------------------------+ + +Flink SQL> SET 'state.savepoints.dir'='file:/tmp/'; +[INFO] Execute statement succeed. + +Flink SQL> STOP JOB '228d70913eab60dda85c5e7f78b5782c' WITH SAVEPOINT; ++-----------------------------------------+ +| savepoint path | ++-----------------------------------------+ +| file:/tmp/savepoint-3addd4-0b224d9311e6 | ++-----------------------------------------+ +``` +{{< /tab >}} +{{< /tabs >}} + +## SHOW JOBS + +```sql +SHOW JOBS +``` + +Show the jobs in the Flink cluster. + +<span class="label label-danger">Attention</span> SHOW JOBS statements only work in [SQL CLI]({{< ref "docs/dev/table/sqlClient" >}}) or [SQL Gateway]({{< ref "docs/dev/table/sql-gateway/overview" >}}). + +## STOP JOB + +```sql +STOP JOB '<job_id>' [WITH SAVEPOINT] [WITH DRAIN] +``` + +Stop the specified job. + +**WITH SAVEPOINT** +Perform a savepoint right before stopping the job. The savepoint path could be specified with +[state.savepoints.dir]({{< ref "docs/deployment/config" >}}#state-savepoints-dir) either in +the cluster configuration or via `SET` statements (the latter would take precedence). + +**WITH DRAIN** +Increase the watermark to the maximum value before the last checkpoint barrier. Use it when you +want to terminate the job permanently. + +<span class="label label-danger">Attention</span> STOP JOBS statements only work in [SQL CLI]({{< ref "docs/dev/table/sqlClient" >}}) or [SQL Gateway]({{< ref "docs/dev/table/sql-gateway/overview" >}}). Review Comment: STOP JOBS -> STOP JOB ########## docs/content/docs/dev/table/sqlClient.md: ########## @@ -812,4 +812,35 @@ Flink SQL> RESET pipeline.name; If the option `pipeline.name` is not specified, SQL Client will generate a default name for the submitted job, e.g. `insert-into_<sink_table_name>` for `INSERT INTO` statements. +### Monitoring job status Review Comment: The first time I read it, I thought this part was a bit repetitive. One idea gives an example of how users stop the job. Users first use SHOW statements to get the running job list and then select one of these to kill. How about adding a new section named `Stop a Job with a savepoint`? ########## docs/content/docs/dev/table/sqlClient.md: ########## @@ -812,4 +813,35 @@ Flink SQL> RESET pipeline.name; If the option `pipeline.name` is not specified, SQL Client will generate a default name for the submitted job, e.g. `insert-into_<sink_table_name>` for `INSERT INTO` statements. +### Monitoring job status + +SQL Client supports to list jobs status in the cluster through `SHOW JOBS` statements. + +```sql +Flink SQL> SHOW JOBS; ++----------------------------------+---------------+----------+-------------------------+ +| job id | job name | status | start time | ++----------------------------------+---------------+----------+-------------------------+ +| 228d70913eab60dda85c5e7f78b5782c | kafka-to-hive | RUNNING | 2023-02-11T05:03:51.523 | ++----------------------------------+---------------+----------+-------------------------+ +``` + +### Terminating a job Review Comment: job -> Job Please align the style with other titles in the article. ########## docs/content.zh/docs/dev/table/sql/show.md: ########## @@ -746,6 +746,16 @@ SHOW JARS 展示所有通过 [`ADD JAR`]({{< ref "docs/dev/table/sql/jar" >}}#add-jar) 语句加入到 session classloader 中的 jar。 -<span class="label label-danger">Attention</span> 当前 SHOW JARS 命令只能在 [SQL CLI]({{< ref "docs/dev/table/sqlClient" >}}) 中使用。 +<span class="label label-danger">Attention</span> 当前 SHOW JARS 命令只能在 [SQL CLI]({{< ref "docs/dev/table/sqlClient" >}}) 或者 [SQL Gateway]({{< ref "docs/dev/table/sql-gateway/overview" >}}) 中使用. + +## SHOW JOBS + +```sql +SHOW JOBS +``` + +展示集群中所有 job。 Review Comment: I think we can translate `job` to `作业`. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: issues-unsubscr...@flink.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
