[flink] branch release-1.11 updated: [FLINK-18598][python][docs] Add documentation on how to wait for the job execution to finish when using asynchronous APIs

[di...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

dianfu pushed a commit to branch release-1.11
in repository https://gitbox.apache.org/repos/asf/flink.git


The following commit(s) were added to refs/heads/release-1.11 by this push:
     new d4bcfdf  [FLINK-18598][python][docs] Add documentation on how to wait for the job execution to finish when using asynchronous APIs
d4bcfdf is described below

commit d4bcfdfbf18b6c2f005b03e330f04576e71b2359
Author: acqua.csq <ac...@alibaba-inc.com>
AuthorDate: Fri Sep 4 20:57:10 2020 +0800

    [FLINK-18598][python][docs] Add documentation on how to wait for the job execution to finish when using asynchronous APIs
    
    This closes #13295.
---
 docs/dev/python/faq.md    | 15 +++++++++++++++
 docs/dev/python/faq.zh.md | 14 ++++++++++++++
 2 files changed, 29 insertions(+)

diff --git a/docs/dev/python/faq.md b/docs/dev/python/faq.md
index 50c62a5..97f7575 100644
--- a/docs/dev/python/faq.md
+++ b/docs/dev/python/faq.md
@@ -97,3 +97,18 @@ table_env.add_python_file('myDir')
 def my_udf():
     from utils import my_util
 {% endhighlight %}
+
+## Wait for jobs to finish when executing jobs in mini cluster
+
+When executing jobs in mini cluster(e.g. when executing jobs in IDE) and using the following APIs in the jobs(
+e.g. TableEnvironment.execute_sql, StatementSet.execute, etc in the Python Table API), please remember to explicitly
+wait for the job execution to finish as these APIs are asynchronous. Otherwise you may could not find the execution
+results as the program will exit before the job execution finishes. Please refer to the following example on how to do that:
+
+{% highlight python %}
+# execute SQL / Table API query asynchronously
+t_result = table_env.execute_sql(...)
+t_result.get_job_client().get_job_execution_result().result()
+{% endhighlight %}
+
+<strong>Note:</strong> There is no need to wait for the job execution to finish when executing jobs in remote cluster and so remember to remove these codes when executing jobs in remote cluster.
diff --git a/docs/dev/python/faq.zh.md b/docs/dev/python/faq.zh.md
index a2b7653..aa11e66 100644
--- a/docs/dev/python/faq.zh.md
+++ b/docs/dev/python/faq.zh.md
@@ -96,3 +96,17 @@ table_env.add_python_file('myDir')
 def my_udf():
     from utils import my_util
 {% endhighlight %}
+
+## 当在 mini cluster 环境执行作业时，显式等待作业执行结束
+
+当在 mini cluster 环境执行作业（比如，在IDE中执行作业）且在作业中使用了如下API（比如 Python Table API 的
+TableEnvironment.execute_sql 和 StatementSet.execute 等）的时候，因为这些API是异步的，请记得显式地等待作业执行结束。
+否则程序会在已提交的作业执行结束之前退出，以致无法观测到已提交作业的执行结果。请参考如下示例代码，了解如何显式地等待作业执行结束：
+
+{% highlight python %}
+# 异步执行 SQL / Table API 作业
+t_result = table_env.execute_sql(...)
+t_result.get_job_client().get_job_execution_result().result()
+{% endhighlight %}
+
+<strong>注意:</strong> 当往远程集群提交作业时，无需显式地等待作业执行结束，所以当往远程集群提交作业之前，请记得移除这些等待作业执行结束的代码逻辑。