[flink] branch release-1.9 updated: [hotifx][table] Improve documentation around table config

[tw...@apache.org]

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

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


The following commit(s) were added to refs/heads/release-1.9 by this push:
     new 278a2bc  [hotifx][table] Improve documentation around table config
278a2bc is described below

commit 278a2bced0020a0fa3fa5f764fb7c5305f5a83c8
Author: Timo Walther <tw...@apache.org>
AuthorDate: Tue Aug 6 09:17:32 2019 +0200

    [hotifx][table] Improve documentation around table config
    
    This closes #9369.
---
 flink-python/pyflink/table/table_config.py         | 24 +++++++++++++++++-----
 .../org/apache/flink/table/api/TableConfig.java    | 23 +++++++++++++++++----
 2 files changed, 38 insertions(+), 9 deletions(-)

diff --git a/flink-python/pyflink/table/table_config.py b/flink-python/pyflink/table/table_config.py
index 42026d2..2f84c2f 100644
--- a/flink-python/pyflink/table/table_config.py
+++ b/flink-python/pyflink/table/table_config.py
@@ -30,7 +30,20 @@ if sys.version > '3':
 
 class TableConfig(object):
     """
-    A config to define the runtime behavior of the Table API.
+    Configuration for the current :class:`TableEnvironment` session to adjust Table & SQL API
+    programs.
+
+    For common or important configuration options, this class provides getters and setters methods
+    with detailed inline documentation.
+
+    For more advanced configuration, users can directly access the underlying key-value map via
+    :func:`~pyflink.table.TableConfig.get_configuration`. Currently, key-value options are only
+    supported for the Blink planner.
+
+    .. note::
+
+        Because options are read at different point in time when performing operations, it is
+        recommended to set configuration options early after instantiating a table environment.
     """
 
     def __init__(self, j_table_config=None):
@@ -231,18 +244,19 @@ class TableConfig(object):
 
     def get_configuration(self):
         """
-        Returns all key/value configuration.
+        Gives direct access to the underlying key-value map for advanced configuration.
 
-        :return: All key/value configuration.
+        :return: Entire key-value configuration.
         :rtype: Configuration
         """
         return Configuration(j_configuration=self._j_table_config.getConfiguration())
 
     def add_configuration(self, configuration):
         """
-        Adds the given key/value configuration.
+        Adds the given key-value configuration to the underlying configuration. It overwrites
+        existing keys.
 
-        :param configuration: The given key/value configuration.
+        :param configuration: Key-value configuration to be added.
         :type configuration: Configuration
         """
         self._j_table_config.addConfiguration(configuration._j_configuration)
diff --git a/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/TableConfig.java b/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/TableConfig.java
index 7dfd46f..8acfdcf 100644
--- a/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/TableConfig.java
+++ b/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/TableConfig.java
@@ -21,13 +21,27 @@ package org.apache.flink.table.api;
 import org.apache.flink.annotation.PublicEvolving;
 import org.apache.flink.api.common.time.Time;
 import org.apache.flink.configuration.Configuration;
+import org.apache.flink.table.api.config.ExecutionConfigOptions;
+import org.apache.flink.table.api.config.OptimizerConfigOptions;
 import org.apache.flink.util.Preconditions;
 
 import java.math.MathContext;
 import java.time.ZoneId;
 
 /**
- * A config to define the runtime behavior of the Table API.
+ * Configuration for the current {@link TableEnvironment} session to adjust Table & SQL API programs.
+ *
+ * <p>For common or important configuration options, this class provides getters and setters methods
+ * with detailed inline documentation.
+ *
+ * <p>For more advanced configuration, users can directly access the underlying key-value map via
+ * {@link #getConfiguration()}. Currently, key-value options are only supported for the Blink planner.
+ *
+ * <p>Note: Because options are read at different point in time when performing operations, it is
+ * recommended to set configuration options early after instantiating a table environment.
+ *
+ * @see ExecutionConfigOptions
+ * @see OptimizerConfigOptions
  */
 @PublicEvolving
 public class TableConfig {
@@ -83,16 +97,17 @@ public class TableConfig {
 	private SqlDialect sqlDialect = SqlDialect.DEFAULT;
 
 	/**
-	 * Returns all key/value configuration.
+	 * Gives direct access to the underlying key-value map for advanced configuration.
 	 */
 	public Configuration getConfiguration() {
 		return configuration;
 	}
 
 	/**
-	 * Adds the given key/value configuration.
+	 * Adds the given key-value configuration to the underlying configuration. It overwrites
+	 * existing keys.
 	 *
-	 * @param configuration key/value configuration to adds
+	 * @param configuration key-value configuration to be added
 	 */
 	public void addConfiguration(Configuration configuration) {
 		Preconditions.checkNotNull(configuration);