[GitHub] [flink] twalthr commented on a change in pull request #11527: [FLINK-16035] Updated Stream/BatchTableEnvironment.java to use Java's Expression DSL

[GitBox <gi...@apache.org>]

twalthr commented on a change in pull request #11527:  [FLINK-16035] Updated Stream/BatchTableEnvironment.java to use Java's Expression DSL
URL: https://github.com/apache/flink/pull/11527#discussion_r401407132
 
 

 ##########
 File path: flink-table/flink-table-api-java-bridge/src/main/java/org/apache/flink/table/api/java/BatchTableEnvironment.java
 ##########
 @@ -114,17 +137,46 @@
 	/**
 	 * Converts the given {@link DataSet} into a {@link Table} with specified field names.
 	 *
-	 * Example:
+	 * <p>There are two modes for mapping original fields to the fields of the {@link Table}:
+	 *
+	 * <p>1. Reference input fields by name:
+	 * All fields in the schema definition are referenced by name
+	 * (and possibly renamed using an alias (as). In this mode, fields can be reordered and
+	 * projected out. This mode can be used for any input type, including POJOs.
+	 *
+	 * <p>Example:
+	 *
+	 * <pre>
+	 * {@code
+	 *   DataSet<Tuple2<String, Long>> set = ...
+	 *   Table table = tableEnv.fromDataSet(
+	 *      set,
+	 *      $("f1"), // reorder and use the original field
+	 *      $("f0").as("name") // reorder and give the original field a better name
+	 *   );
+	 * }
+	 * </pre>
+	 *
+	 * <p>2. Reference input fields by position:
+	 * In this mode, fields are simply renamed. This mode can only be
+	 * used if the input type has a defined field order (tuple, case class, Row) and none of
+	 * the {@code fields} references a field of the input type.
+	 *
+	 * <p>Example:
 	 *
 	 * <pre>
 	 * {@code
 	 *   DataSet<Tuple2<String, Long>> set = ...
-	 *   Table tab = tableEnv.fromDataSet(set, $("a"), $("b").as("name"), $("timestamp").rowtime());
+	 *   Table table = tableEnv.fromDataSet(
+	 *      set,
+	 *      $("a"), // renames the first field to 'a'
+	 *      $("b") // renames the second field to 'b'
+	 *   );
 	 * }
 	 * </pre>
 	 *
 	 * @param dataSet The {@link DataSet} to be converted.
-	 * @param fields The field names of the resulting {@link Table}.
+	 * @param fields The fields expressions to map original fields of the DataSet to the fields of the {@code Table}.
 
 Review comment:
   nit: link Table instead of code Table

----------------------------------------------------------------
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.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services