From cae9db9d523ca321061f097016fe1563d3cab8fc Mon Sep 17 00:00:00 2001 From: Xuyang Date: Thu, 27 Jun 2024 10:13:21 +0800 Subject: [PATCH] [FLINK-35271][docs] Add doc for DESCRIBE JOB statement This closes #24984 (cherry picked from commit 7fc3aac774f5deb9b48727ba5f916c78085b49b9) --- .../content.zh/docs/dev/table/sql/describe.md | 35 +++++++++++++++---- docs/content.zh/docs/dev/table/sql/job.md | 18 ++++++++++ docs/content/docs/dev/table/sql/describe.md | 34 ++++++++++++++---- docs/content/docs/dev/table/sql/job.md | 19 ++++++++++ 4 files changed, 94 insertions(+), 12 deletions(-) diff --git a/docs/content.zh/docs/dev/table/sql/describe.md b/docs/content.zh/docs/dev/table/sql/describe.md index 4f77e3010ba1e..5f7480da1b555 100644 --- a/docs/content.zh/docs/dev/table/sql/describe.md +++ b/docs/content.zh/docs/dev/table/sql/describe.md @@ -28,7 +28,7 @@ under the License. # DESCRIBE 语句 -DESCRIBE 语句用于描述表或视图的 schema 或 catalog 的元数据。 +DESCRIBE 语句用于描述表或视图的 schema，或catalog 的元数据，或 Flink 集群上的指定作业。 @@ -36,17 +36,17 @@ DESCRIBE 语句用于描述表或视图的 schema 或 catalog 的元数据。 {{< 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 '' +``` + +Attention DESCRIBE JOB 语句仅适用于 [SQL CLI]({{< ref "docs/dev/table/sqlClient" >}}) 或者 [SQL Gateway]({{< ref "docs/dev/table/sql-gateway/overview" >}}). \ No newline at end of file diff --git a/docs/content.zh/docs/dev/table/sql/job.md b/docs/content.zh/docs/dev/table/sql/job.md index 5661969f4f2be..eafb125bcc340 100644 --- 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 Attention SHOW JOBS 语句仅适用于 [SQL CLI]({{< ref "docs/dev/table/sqlClient" >}}) 或者 [SQL Gateway]({{< ref "docs/dev/table/sql-gateway/overview" >}}). +## DESCRIBE JOB + +```sql +{ DESCRIBE | DESC } JOB '' +``` + +展示 Flink 集群上的指定作业。 + +Attention 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 index 0ef8421f73d05..4fdde4a29a844 100644 --- 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 '' +``` + +Attention DESCRIBE JOB statements only work in [SQL CLI]({{< ref "docs/dev/table/sqlClient" >}}) or [SQL Gateway]({{< ref "docs/dev/table/sql-gateway/overview" >}}). \ No newline at end of file diff --git a/docs/content/docs/dev/table/sql/job.md b/docs/content/docs/dev/table/sql/job.md index e9d00f4f2a27a..379475c55e85b 100644 --- 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. Attention 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 '' +``` + +Show the specified job in the Flink cluster. + +Attention 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