dawidwys commented on a change in pull request #11153:
[FLINK-15958][table-common] Introduce unresolved data types in API
URL: https://github.com/apache/flink/pull/11153#discussion_r382168576
##########
File path:
flink-table/flink-table-common/src/main/java/org/apache/flink/table/api/DataTypes.java
##########
@@ -73,13 +78,83 @@
* A {@link DataType} can be used to declare input and/or output types of
operations. This class
* enumerates all pre-defined data types of the Table & SQL API.
*
+ * <p>For convenience, this class also contains methods for creating {@link
UnresolvedDataType}s that
+ * need to be resolved at later stages. This is in particular useful for more
complex types that are
+ * expressed as {@link Class} (see {@link #of(Class)}) or types that need to
be looked up in a catalog
+ * (see {@link #of(String)}).
+ *
* <p>NOTE: Planners might not support every data type with the desired
precision or parameter. Please
* see the planner compatibility and limitations section in the website
documentation before using a
* data type.
*/
@PublicEvolving
public final class DataTypes {
+ /**
+ * Creates an unresolved type that will be resolved to a {@link
DataType} by analyzing the given
+ * class later.
+ *
+ * <p>During the resolution, Java reflection is used which can be
supported by {@link DataTypeHint}
+ * annotations for nested, structured types.
+ *
+ * <p>It will throw an {@link ValidationException} in cases where the
reflective extraction needs
+ * more information or simply fails.
+ *
+ * <p>The following examples show how to use and enrich the extraction
process:
+ *
+ * <pre>
+ * {@code
+ * // returns INT
+ * of(Integer.class)
+ *
+ * // returns TIMESTAMP(9)
+ * of(java.time.LocalDateTime.class)
+ *
+ * // returns an anonymous, unregistered structured type
+ * // that is deeply integrated into the API compared to opaque RAW
types
+ * class User {
+ *
+ * // extract fields automatically
+ * public String name;
+ * public int age;
+ *
+ * // enrich the extraction with precision information
+ * public @DataTypeHint("DECIMAL(10,2)") BigDecimal accountBalance;
+ *
+ * // enrich the extraction with forcing using RAW types
+ * public @DataTypeHint(forceRawPattern = "scala.") Address address;
+ *
+ * // enrich the extraction by specifying defaults
+ * public @DataTypeHint(defaultSecondPrecision = 3) Log log;
+ * }
+ * of(User.class)
+ * }
+ * </pre>
+ *
+ * <p>Note: In most of the cases, the {@link UnresolvedDataType} will
be automatically resolved by
+ * the API. At other locations, a {@link DataTypeFactory} is provided.
+ */
+ public static UnresolvedDataType of(Class<?> unresolvedClass) {
Review comment:
nit: How about we move it somewhere down below in this class? It shouldn't
be the "to go" method for all types. I think the specific SQL types should be
constructed explicitly.
----------------------------------------------------------------
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
