twalthr commented on a change in pull request #11290: [FLINK-16379][table]
Introduce fromValues in TableEnvironment
URL: https://github.com/apache/flink/pull/11290#discussion_r404097656
##########
File path:
flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/TableEnvironment.java
##########
@@ -89,6 +93,223 @@ static TableEnvironment create(EnvironmentSettings
settings) {
return TableEnvironmentImpl.create(settings);
}
+ /**
+ * Creates a Table from given values.
+ *
+ * <p>Examples:
+ *
+ * <p>You can use a {@code row(...)} expression to create a composite
rows:
+ * <pre>{@code
+ * tEnv.fromValues(
+ * row(1, "ABC"),
+ * row(2L, "ABCDE")
+ * )
+ * }</pre>
+ * will produce a Table with a schema as follows:
+ * <pre>{@code
+ * root
+ * |-- f0: BIGINT NOT NULL
+ * |-- f1: VARCHAR(5) NOT NULL
+ * }</pre>
+ *
+ * <p>It is also possible to use {@link org.apache.flink.types.Row}
object instead of
+ * {@code row} expressions.
+ *
+ * <p>ROWs that are a result of e.g. a function call are not flattened
+ * <pre>{@code
+ * public class RowFunction extends ScalarFunction {
+ * @DataTypeHint("ROW<f0 BIGINT, f1 VARCHAR(5)>")
+ * Row eval();
+ * }
+ *
+ * tEnv.fromValues(
+ * call(new RowFunction()),
+ * call(new RowFunction())
+ * )
+ * }</pre>
+ * will produce a Table with a schema as follows:
+ * <pre>{@code
+ * root
+ * |-- f0: ROW<`f0` BIGINT, `f1` VARCHAR(5)>
+ * }</pre>
+ *
+ * <p>The row constructor can be dropped to create a table with a
single column:
+ *
+ * <p>ROWs that are a result of e.g. a function call are not flattened
+ * <pre>{@code
+ * tEnv.fromValues(
+ * 1,
+ * 2L,
+ * 3
+ * )
+ * }</pre>
+ * will produce a Table with a schema as follows:
+ * <pre>{@code
+ * root
+ * |-- f0: BIGINT NOT NULL
+ * }</pre>
+ *
+ * @param values Expressions for constructing rows of the VALUES table.
+ */
+ default Table fromValues(Object... values) {
+ // It is necessary here to implement
TableEnvironment#fromValues(Object...) for BatchTableEnvImpl.
+ // In scala varargs are translated to Seq. Due to the type
erasure Seq<Expression> and Seq<Object>
+ // are the same. It is not a problem in java as varargs in java
are translated to an array.
+ return fromValues(Arrays.asList(values));
+ }
+
+ /**
+ * Creates a Table from given collection of objects with a given row
type.
+ *
+ * <p>The difference between this method and {@link
#fromValues(Object...)} is that the schema
+ * can be manually adjusted. It might be helpful for assigning more
generic types like
+ * e.g. DECIMAL or naming the columns.
+ *
+ * <p>Examples:
+ * <pre>{@code
+ * tEnv.fromValues(
+ * DataTypes.ROW(
+ * DataTypes.FIELD("id", DataTypes.DECIMAL(10, 2)),
+ * DataTypes.FIELD("name", DataTypes.STRING())
+ * ),
+ * row(1, "ABC"),
+ * row(2L, "ABCDE")
+ * )
+ * }</pre>
+ * will produce a Table with a schema as follows:
+ * <pre>{@code
+ * root
+ * |-- id: DECIMAL(10, 2)
+ * |-- f1: STRING
+ * }</pre>
+ *
+ * <p>For more examples see {@link #fromValues(Object...)}.
+ *
+ * @param rowType Expected row type for the values.
+ * @param values Expressions for constructing rows of the VALUES table.
+ * @see #fromValues(Object...)
+ */
+ default Table fromValues(DataType rowType, Object... values) {
+ // It is necessary here to implement
TableEnvironment#fromValues(Object...) for BatchTableEnvImpl.
+ // In scala varargs are translated to Seq. Due to the type
erasure Seq<Expression> and Seq<Object>
+ // are the same. It is not a problem in java as varargs in java
are translated to an array.
+ return fromValues(rowType, Arrays.asList(values));
+ }
+
+ /**
+ * Creates a Table from given values.
+ *
+ * <p>Examples:
+ *
+ * <p>You can use a {@code row(...)} expression to create a composite
rows:
+ * <pre>{@code
+ * tEnv.fromValues(
+ * row(1, "ABC"),
+ * row(2L, "ABCDE")
+ * )
+ * }</pre>
+ * will produce a Table with a schema as follows:
+ * <pre>{@code
+ * root
+ * |-- f0: BIGINT NOT NULL
+ * |-- f1: VARCHAR(5) NOT NULL
+ * }</pre>
+ *
+ * <p>It is also possible to use {@link org.apache.flink.types.Row}
object instead of
+ * {@code row} expressions.
+ *
+ * <p>ROWs that are a result of e.g. a function call are not flattened
+ * <pre>{@code
+ * public class RowFunction extends ScalarFunction {
+ * @DataTypeHint("ROW<f0 BIGINT, f1 VARCHAR(5)>")
+ * Row eval();
+ * }
+ *
+ * tEnv.fromValues(
+ * call(new RowFunction()),
+ * call(new RowFunction())
+ * )
+ * }</pre>
+ * will produce a Table with a schema as follows:
+ * <pre>{@code
+ * root
+ * |-- f0: ROW<`f0` BIGINT, `f1` VARCHAR(5)>
+ * }</pre>
+ *
+ * <p>The row constructor can be dropped to create a table with a
single column:
+ *
+ * <p>ROWs that are a result of e.g. a function call are not flattened
+ * <pre>{@code
+ * tEnv.fromValues(
+ * lit(1).plus(2),
+ * lit(2L),
+ * lit(3)
+ * )
+ * }</pre>
+ * will produce a Table with a schema as follows:
+ * <pre>{@code
+ * root
+ * |-- f0: BIGINT NOT NULL
+ * }</pre>
+ *
+ * @param values Expressions for constructing rows of the VALUES table.
+ */
+ Table fromValues(Expression... values);
+
+ /**
+ * Creates a Table from given collection of objects with a given row
type.
+ *
+ * <p>The difference between this method and {@link
#fromValues(Expression...)} is that the
+ * schema can be manually adjusted. It might be helpful for assigning
more generic types like
+ * e.g. DECIMAL or naming the columns.
+ *
+ * <p>Examples:
+ * <pre>{@code
+ * tEnv.fromValues(
+ * DataTypes.ROW(
+ * DataTypes.FIELD("id", DataTypes.DECIMAL(10, 2)),
+ * DataTypes.FIELD("name", DataTypes.STRING())
+ * ),
+ * row(1, "ABC"),
+ * row(2L, "ABCDE")
+ * )
+ * }</pre>
+ * will produce a Table with a schema as follows:
+ * <pre>{@code
+ * root
+ * |-- id: DECIMAL(10, 2)
+ * |-- name: STRING
+ * }</pre>
+ *
+ * <p>For more examples see {@link #fromValues(Expression...)}.
+ *
+ * @param rowType Expected row type for the values.
+ * @param values Expressions for constructing rows of the VALUES table.
+ * @see #fromValues(Expression...)
+ */
+ Table fromValues(DataType rowType, Expression... values);
+
+ /**
+ * Creates a Table from given collection of objects.
+ *
+ * <p>See {@link #fromValues(Object...)} for more explanation.
+ *
+ * @param values Expressions for constructing rows of the VALUES table.
+ * @see #fromValues(Object...)
+ */
+ Table fromValues(Collection<?> values);
Review comment:
Could you explain why you decided for `Collection`? We could also make it
broader and allow `Iterable`?
----------------------------------------------------------------
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:
[email protected]
With regards,
Apache Git Services
