[FLINK-35271][docs] Add doc for DESCRIBE JOB <JOB_ID> statement

xuyangzhong · lsyldliu · commit cae9db9d523c · 2024-06-27T10:17:54.000+08:00
This closes apache#24984 (cherry picked from commit 7fc3aac)
diff --git a/docs/content.zh/docs/dev/table/sql/describe.md b/docs/content.zh/docs/dev/table/sql/describe.md
@@ -28,25 +28,25 @@ under the License.
 
 # DESCRIBE 语句
 
-DESCRIBE 语句用于描述表或视图的 schema 或 catalog 的元数据。
+DESCRIBE 语句用于描述表或视图的 schema，或catalog 的元数据，或 Flink 集群上的指定作业。
 
 <a name="run-a-describe-statement"></a>
 
 ## 执行 DESCRIBE 语句
 
 {{< tabs "describe" >}}
 {{< tab "Java" >}}
-可以使用 `TableEnvironment` 的 `executeSql()` 方法执行 DESCRIBE 语句。如果 DESCRIBE 操作执行成功，`executeSql()` 方法会返回给定表的 schema，否则会抛出异常。
+可以使用 `TableEnvironment` 的 `executeSql()` 方法执行 DESCRIBE 语句。如果 DESCRIBE 操作执行成功，`executeSql()` 方法会返回所有对象，否则会抛出异常。
 
 以下示例展示了如何在 `TableEnvironment` 中执行一条 DESCRIBE 语句。
 {{< /tab >}}
 {{< tab "Scala" >}}
-可以使用 `TableEnvironment` 的 `executeSql()` 方法执行 DESCRIBE 语句。如果 DESCRIBE 操作执行成功，`executeSql()` 方法会返回给定表的 schema，否则会抛出异常。
+可以使用 `TableEnvironment` 的 `executeSql()` 方法执行 DESCRIBE 语句。如果 DESCRIBE 操作执行成功，`executeSql()` 方法会返回所有对象，否则会抛出异常。
 
 以下示例展示了如何在 `TableEnvironment` 中执行一条 DESCRIBE 语句。
 {{< /tab >}}
 {{< tab "Python" >}}
-可以使用 `TableEnvironment` 的 `execute_sql()` 方法执行 DESCRIBE 语句。如果 DESCRIBE 操作执行成功，`execute_sql()` 方法会返回给定表的 schema，否则会抛出异常。
+可以使用 `TableEnvironment` 的 `execute_sql()` 方法执行 DESCRIBE 语句。如果 DESCRIBE 操作执行成功，`execute_sql()` 方法会返回所有对象，否则会抛出异常。
 
 以下示例展示了如何在 `TableEnvironment` 中执行一条 DESCRIBE 语句。
 {{< /tab >}}
@@ -181,6 +181,10 @@ Flink SQL> CREATE CATALOG cat2 WITH ('type'='generic_in_memory', 'default-databa
 Flink SQL> DESCRIBE CATALOG cat2;
 
 Flink SQL> DESC CATALOG EXTENDED cat2;
+      
+Flink SQL> DESCRIBE JOB '228d70913eab60dda85c5e7f78b5782c';
+      
+Flink SQL> DESC JOB '228d70913eab60dda85c5e7f78b5782c';
 ```
 {{< /tab >}}
 {{< /tabs >}}
@@ -329,6 +333,14 @@ Flink SQL> DESC CATALOG EXTENDED cat2;
 | option:default-database |                db |
 +-------------------------+-------------------+
 4 rows in set
+
+# DESCRIBE JOB '228d70913eab60dda85c5e7f78b5782c'
++----------------------------------+----------+---------+-------------------------+
+|                           job id | job name |  status |              start time |
++----------------------------------+----------+---------+-------------------------+
+| 228d70913eab60dda85c5e7f78b5782c |    myjob | RUNNING | 2023-02-11T05:03:51.523 |
++----------------------------------+----------+---------+-------------------------+
+1 row in set
 ```
 {{< /tab >}}
 {{< /tabs >}}
@@ -339,11 +351,22 @@ Flink SQL> DESC CATALOG EXTENDED cat2;
 
 ## 语法
 
-- DESCRIBE TABLE
+### DESCRIBE TABLE
+
 ```sql
 { DESCRIBE | DESC } [catalog_name.][db_name.]table_name
 ```
-- DESCRIBE CATALOG
+
+### DESCRIBE CATALOG
+
 ```sql
 { DESCRIBE | DESC } CATALOG [EXTENDED] catalog_name
 ```
+
+### DESCRIBE JOB
+
+```sql
+{ DESCRIBE | DESC } JOB '<job_id>'
+```
+
+<span class="label label-danger">Attention</span> DESCRIBE JOB 语句仅适用于 [SQL CLI]({{< ref "docs/dev/table/sqlClient" >}}) 或者 [SQL Gateway]({{< ref "docs/dev/table/sql-gateway/overview" >}}).
diff --git a/docs/content.zh/docs/dev/table/sql/job.md b/docs/content.zh/docs/dev/table/sql/job.md
@@ -30,6 +30,7 @@ Job 语句用于管理作业的生命周期。
 
 目前 Flink SQL 支持以下 JOB 语句：
 - SHOW JOBS
+- DESCRIBE JOB
 - STOP JOB
 
 ## 执行 JOB 语句
@@ -52,6 +53,13 @@ Flink SQL> SHOW JOBS;
 | 228d70913eab60dda85c5e7f78b5782c |    myjob | RUNNING | 2023-02-11T05:03:51.523 |
 +----------------------------------+----------+---------+-------------------------+
 
+Flink SQL> DESCRIBE JOB '228d70913eab60dda85c5e7f78b5782c';
++----------------------------------+----------+---------+-------------------------+
+|                           job id | job name |  status |              start time |
++----------------------------------+----------+---------+-------------------------+
+| 228d70913eab60dda85c5e7f78b5782c |    myjob | RUNNING | 2023-02-11T05:03:51.523 |
++----------------------------------+----------+---------+-------------------------+
+
 Flink SQL> SET 'execution.checkpointing.savepoint-dir'='file:/tmp/';
 [INFO] Execute statement succeeded.
 
@@ -75,6 +83,16 @@ SHOW JOBS
 
 <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" >}}).
 
+## DESCRIBE JOB
+
+```sql
+{ DESCRIBE | DESC } JOB '<job_id>'
+```
+
+展示 Flink 集群上的指定作业。
+
+<span class="label label-danger">Attention</span> DESCRIBE JOB 语句仅适用于 [SQL CLI]({{< ref "docs/dev/table/sqlClient" >}}) 或者 [SQL Gateway]({{< ref "docs/dev/table/sql-gateway/overview" >}}).
+
 ## STOP JOB
 
 ```sql
diff --git a/docs/content/docs/dev/table/sql/describe.md b/docs/content/docs/dev/table/sql/describe.md
@@ -26,25 +26,25 @@ under the License.
 
 # DESCRIBE Statements
 
-DESCRIBE statements are used to describe the schema of a table or a view, or the metadata of a catalog.
+DESCRIBE statements are used to describe the schema of a table or a view, or the metadata of a catalog, or the specified job in the Flink cluster.
 
 
 ## Run a DESCRIBE statement
 
 {{< tabs "describe" >}}
 {{< tab "Java" >}}
-DESCRIBE statements can be executed with the `executeSql()` method of the `TableEnvironment`. The `executeSql()` method returns the schema of given table for a successful DESCRIBE operation, otherwise will throw an exception.
+DESCRIBE statements can be executed with the `executeSql()` method of the `TableEnvironment`. The `executeSql()` method returns objects for a successful DESCRIBE operation, otherwise will throw an exception.
 
 The following examples show how to run a DESCRIBE statement in `TableEnvironment`.
 {{< /tab >}}
 {{< tab "Scala" >}}
-DESCRIBE statements can be executed with the `executeSql()` method of the `TableEnvironment`. The `executeSql()` method returns the schema of given table for a successful DESCRIBE operation, otherwise will throw an exception.
+DESCRIBE statements can be executed with the `executeSql()` method of the `TableEnvironment`. The `executeSql()` method returns objects for a successful DESCRIBE operation, otherwise will throw an exception.
 
 The following examples show how to run a DESCRIBE statement in `TableEnvironment`.
 {{< /tab >}}
 {{< tab "Python" >}}
 
-DESCRIBE statements can be executed with the `execute_sql()` method of the `TableEnvironment`. The `execute_sql()` method returns the schema of given table for a successful DESCRIBE operation, otherwise will throw an exception.
+DESCRIBE statements can be executed with the `execute_sql()` method of the `TableEnvironment`. The `execute_sql()` method returns objects for a successful DESCRIBE operation, otherwise will throw an exception.
 
 The following examples show how to run a DESCRIBE statement in `TableEnvironment`.
 
@@ -180,6 +180,10 @@ Flink SQL> CREATE CATALOG cat2 WITH ('type'='generic_in_memory', 'default-databa
 Flink SQL> DESCRIBE CATALOG cat2;
 
 Flink SQL> DESC CATALOG EXTENDED cat2;
+      
+Flink SQL> DESCRIBE JOB '228d70913eab60dda85c5e7f78b5782c';
+      
+Flink SQL> DESC JOB '228d70913eab60dda85c5e7f78b5782c';
 ```
 {{< /tab >}}
 {{< /tabs >}}
@@ -329,6 +333,14 @@ The result of the above example is:
 +-------------------------+-------------------+
 4 rows in set
 
+# DESCRIBE JOB '228d70913eab60dda85c5e7f78b5782c'
++----------------------------------+----------+---------+-------------------------+
+|                           job id | job name |  status |              start time |
++----------------------------------+----------+---------+-------------------------+
+| 228d70913eab60dda85c5e7f78b5782c |    myjob | RUNNING | 2023-02-11T05:03:51.523 |
++----------------------------------+----------+---------+-------------------------+
+1 row in set
+
 ```
 {{< /tab >}}
 {{< /tabs >}}
@@ -338,11 +350,21 @@ The result of the above example is:
 
 ## Syntax
 
-- DESCRIBE TABLE
+### DESCRIBE TABLE
+
 ```sql
 { DESCRIBE | DESC } [catalog_name.][db_name.]table_name
 ```
-- DESCRIBE CATALOG
+
+### DESCRIBE CATALOG
+
 ```sql
 { DESCRIBE | DESC } CATALOG [EXTENDED] catalog_name
 ```
+
+### DESCRIBE JOB
+```sql
+{ DESCRIBE | DESC } JOB '<job_id>'
+```
+
+<span class="label label-danger">Attention</span> DESCRIBE JOB statements only work in [SQL CLI]({{< ref "docs/dev/table/sqlClient" >}}) or [SQL Gateway]({{< ref "docs/dev/table/sql-gateway/overview" >}}).
diff --git a/docs/content/docs/dev/table/sql/job.md b/docs/content/docs/dev/table/sql/job.md
@@ -30,6 +30,7 @@ Job statements are used for management of Flink jobs.
 
 Flink SQL supports the following JOB statements for now:
 - SHOW JOBS
+- DESCRIBE JOB
 - STOP JOB
 
 ## Run a JOB statement
@@ -52,6 +53,13 @@ Flink SQL> SHOW JOBS;
 | 228d70913eab60dda85c5e7f78b5782c |    myjob | RUNNING | 2023-02-11T05:03:51.523 |
 +----------------------------------+----------+---------+-------------------------+
 
+Flink SQL> DESCRIBE JOB '228d70913eab60dda85c5e7f78b5782c';
++----------------------------------+----------+---------+-------------------------+
+|                           job id | job name |  status |              start time |
++----------------------------------+----------+---------+-------------------------+
+| 228d70913eab60dda85c5e7f78b5782c |    myjob | RUNNING | 2023-02-11T05:03:51.523 |
++----------------------------------+----------+---------+-------------------------+
+
 Flink SQL> SET 'execution.checkpointing.savepoint-dir'='file:/tmp/';
 [INFO] Execute statement succeeded.
 
@@ -75,6 +83,17 @@ 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" >}}).
 
+## DESCRIBE JOB
+
+```sql
+{ DESCRIBE | DESC } JOB '<job_id>'
+```
+
+Show the specified job in the Flink cluster.
+
+<span class="label label-danger">Attention</span> DESCRIBE JOB statements only work in [SQL CLI]({{< ref "docs/dev/table/sqlClient" >}}) or [SQL Gateway]({{< ref "docs/dev/table/sql-gateway/overview" >}}).
+
+
 ## STOP JOB
 
 ```sql
