twalthr commented on a change in pull request #11081: [FLINK-16033][table-api] Introduced Java Table API Expression DSL URL: https://github.com/apache/flink/pull/11081#discussion_r380078629
########## File path: flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/internal/BaseExpressions.java ########## @@ -0,0 +1,1146 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.flink.table.api.internal; + +import org.apache.flink.annotation.PublicEvolving; +import org.apache.flink.api.common.typeinfo.SqlTimeTypeInfo; +import org.apache.flink.api.common.typeinfo.TypeInformation; +import org.apache.flink.table.api.Table; +import org.apache.flink.table.expressions.Expression; +import org.apache.flink.table.expressions.TimeIntervalUnit; +import org.apache.flink.table.expressions.utils.ApiExpressionUtils; +import org.apache.flink.table.functions.BuiltInFunctionDefinitions; +import org.apache.flink.table.types.DataType; + +import java.util.Arrays; +import java.util.stream.Stream; + +import static org.apache.flink.table.expressions.utils.ApiExpressionUtils.objectToExpression; +import static org.apache.flink.table.expressions.utils.ApiExpressionUtils.tableRef; +import static org.apache.flink.table.expressions.utils.ApiExpressionUtils.typeLiteral; +import static org.apache.flink.table.expressions.utils.ApiExpressionUtils.unresolvedCall; +import static org.apache.flink.table.expressions.utils.ApiExpressionUtils.valueLiteral; +import static org.apache.flink.table.types.utils.TypeConversions.fromLegacyInfoToDataType; +//CHECKSTYLE.OFF: AvoidStarImport|ImportOrder +import static org.apache.flink.table.functions.BuiltInFunctionDefinitions.*; +//CHECKSTYLE.ON: AvoidStarImport|ImportOrder + +/** + * These are Java and Scala common operations that can be used to construct an {@link Expression} AST for + * expression operations. + */ +@PublicEvolving +public abstract class BaseExpressions<InT, OutT> { + protected abstract Expression toExpr(); + + protected abstract OutT toApiSpecificExpression(Expression expression); + + /** + * Specifies a name for an expression i.e. a field. + * + * @param name name for one field + * @param extraNames additional names if the expression expands to multiple fields + * @return field with an alias + */ + public OutT as(String name, String... extraNames) { + return toApiSpecificExpression(ApiExpressionUtils.unresolvedCall( + BuiltInFunctionDefinitions.AS, + Stream.concat( + Stream.of(toExpr(), ApiExpressionUtils.valueLiteral(name)), + Stream.of(extraNames).map(ApiExpressionUtils::valueLiteral) + ).toArray(Expression[]::new))); + } + + /** + * Boolean AND in three-valued logic. + */ + public OutT and(InT other) { + return toApiSpecificExpression(unresolvedCall(AND, toExpr(), objectToExpression(other))); + } + + /** + * Boolean OR in three-valued logic. + */ + public OutT or(InT other) { + return toApiSpecificExpression(unresolvedCall(OR, toExpr(), objectToExpression(other))); + } + + /** + * Greater than. + */ + public OutT isGreater(InT other) { + return toApiSpecificExpression(unresolvedCall(GREATER_THAN, toExpr(), objectToExpression(other))); + } + + /** + * Greater than or equal. + */ + public OutT isGreaterOrEqual(InT other) { + return toApiSpecificExpression(unresolvedCall(GREATER_THAN_OR_EQUAL, toExpr(), objectToExpression(other))); + } + + /** + * Less than. + */ + public OutT isLess(InT other) { + return toApiSpecificExpression(unresolvedCall(LESS_THAN, toExpr(), objectToExpression(other))); + } + + /** + * Less than or equal. + */ + public OutT isLessOrEqual(InT other) { + return toApiSpecificExpression(unresolvedCall(LESS_THAN_OR_EQUAL, toExpr(), objectToExpression(other))); + } + + /** + * Equals. + */ + public OutT isEqual(InT other) { + return toApiSpecificExpression(unresolvedCall(EQUALS, toExpr(), objectToExpression(other))); + } + + /** + * Not equal. + */ + public OutT isNotEqual(InT other) { + return toApiSpecificExpression(unresolvedCall(NOT_EQUALS, toExpr(), objectToExpression(other))); + } + + /** + * Returns left plus right. + */ + public OutT plus(InT other) { + return toApiSpecificExpression(unresolvedCall(PLUS, toExpr(), objectToExpression(other))); + } + + /** + * Returns left minus right. + */ + public OutT minus(InT other) { + return toApiSpecificExpression(unresolvedCall(MINUS, toExpr(), objectToExpression(other))); + } + + /** + * Returns left divided by right. + */ + public OutT dividedBy(InT other) { + return toApiSpecificExpression(unresolvedCall(DIVIDE, toExpr(), objectToExpression(other))); + } + + /** + * Returns left multiplied by right. + */ + public OutT multipliedBy(InT other) { + return toApiSpecificExpression(unresolvedCall(TIMES, toExpr(), objectToExpression(other))); + } + + /** + * Returns true if the given expression is between lowerBound and upperBound (both inclusive). + * False otherwise. The parameters must be numeric types or identical comparable types. + * + * @param lowerBound numeric or comparable expression + * @param upperBound numeric or comparable expression + * @return boolean or null + */ + public OutT between(InT lowerBound, InT upperBound) { + return toApiSpecificExpression(unresolvedCall( + BETWEEN, + toExpr(), + objectToExpression(lowerBound), + objectToExpression(upperBound))); + } + + /** + * Returns true if the given expression is not between lowerBound and upperBound (both + * inclusive). False otherwise. The parameters must be numeric types or identical + * comparable types. + * + * @param lowerBound numeric or comparable expression + * @param upperBound numeric or comparable expression + * @return boolean or null + */ + public OutT notBetween(InT lowerBound, InT upperBound) { + return toApiSpecificExpression(unresolvedCall( + NOT_BETWEEN, + toExpr(), + objectToExpression(lowerBound), + objectToExpression(upperBound))); + } + + /** + * Returns true if the given expression is null. + */ + public OutT isNull() { + return toApiSpecificExpression(unresolvedCall(IS_NULL, toExpr())); + } + + /** + * Returns true if the given expression is not null. + */ + public OutT isNotNull() { + return toApiSpecificExpression(unresolvedCall(IS_NOT_NULL, toExpr())); + } + + /** + * Returns true if given boolean expression is true. False otherwise (for null and false). + */ + public OutT isTrue() { + return toApiSpecificExpression(unresolvedCall(IS_TRUE, toExpr())); + } + + /** + * Returns true if given boolean expression is false. False otherwise (for null and true). + */ + public OutT isFalse() { + return toApiSpecificExpression(unresolvedCall(IS_FALSE, toExpr())); + } + + /** + * Returns true if given boolean expression is not true (for null and false). False otherwise. + */ + public OutT isNotTrue() { + return toApiSpecificExpression(unresolvedCall(IS_NOT_TRUE, toExpr())); + } + + /** + * Returns true if given boolean expression is not false (for null and true). False otherwise. + */ + public OutT isNotFalse() { + return toApiSpecificExpression(unresolvedCall(IS_NOT_FALSE, toExpr())); + } + + /** + * Similar to a SQL distinct aggregation clause such as COUNT(DISTINCT a), declares that an + * aggregation function is only applied on distinct input values. + * + * <p>For example: + * <pre> + * {@code + * orders + * .groupBy('a) + * .select('a, 'b.sum.distinct as 'd) + * } + * </pre> + */ + public OutT distinct() { + return toApiSpecificExpression(unresolvedCall(DISTINCT, toExpr())); + } + + /** + * Returns the sum of the numeric field across all input values. + * If all values are null, null is returned. + */ + public OutT sum() { + return toApiSpecificExpression(unresolvedCall(SUM, toExpr())); + } + + /** + * Returns the sum of the numeric field across all input values. + * If all values are null, 0 is returned. + */ + public OutT sum0() { + return toApiSpecificExpression(unresolvedCall(SUM0, toExpr())); + } + + /** + * Returns the minimum value of field across all input values. + */ + public OutT min() { + return toApiSpecificExpression(unresolvedCall(MIN, toExpr())); + } + + /** + * Returns the maximum value of field across all input values. + */ + public OutT max() { + return toApiSpecificExpression(unresolvedCall(MAX, toExpr())); + } + + /** + * Returns the number of input rows for which the field is not null. + */ + public OutT count() { + return toApiSpecificExpression(unresolvedCall(COUNT, toExpr())); + } + + /** + * Returns the average (arithmetic mean) of the numeric field across all input values. + */ + public OutT avg() { + return toApiSpecificExpression(unresolvedCall(AVG, toExpr())); + } + + /** + * Returns the population standard deviation of an expression (the square root of varPop()). + */ + public OutT stddevPop() { + return toApiSpecificExpression(unresolvedCall(STDDEV_POP, toExpr())); + } + + /** + * Returns the sample standard deviation of an expression (the square root of varSamp()). + */ + public OutT stddevSamp() { + return toApiSpecificExpression(unresolvedCall(STDDEV_SAMP, toExpr())); + } + + /** + * Returns the population standard variance of an expression. + */ + public OutT varPop() { + return toApiSpecificExpression(unresolvedCall(VAR_POP, toExpr())); + } + + /** + * Returns the sample variance of a given expression. + */ + public OutT varSamp() { + return toApiSpecificExpression(unresolvedCall(VAR_SAMP, toExpr())); + } + + /** + * Returns multiset aggregate of a given expression. + */ + public OutT collect() { + return toApiSpecificExpression(unresolvedCall(COLLECT, toExpr())); + } + + /** + * Converts a value to a given data type. + * + * <p>e.g. "42".cast(DataTypes.INT()) leads to 42. + * + * @return casted expression + */ + public OutT cast(DataType toType) { + return toApiSpecificExpression(unresolvedCall(CAST, toExpr(), typeLiteral(toType))); + } + + /** + * @deprecated This method will be removed in future versions as it uses the old type system. It + * is recommended to use {@link #cast(DataType)} instead which uses the new type system + * based on {@link org.apache.flink.table.api.DataTypes}. Please make sure to use either the old + * or the new type system consistently to avoid unintended behavior. See the website documentation + * for more information. + */ + @Deprecated + public OutT cast(TypeInformation<?> toType) { + return toApiSpecificExpression(unresolvedCall(CAST, toExpr(), typeLiteral(fromLegacyInfoToDataType(toType)))); + } + + /** + * Specifies ascending order of an expression i.e. a field for orderBy unresolvedCall. + * + * @return ascend expression + */ + public OutT asc() { + return toApiSpecificExpression(unresolvedCall(ORDER_ASC, toExpr())); + } + + /** + * Specifies descending order of an expression i.e. a field for orderBy unresolvedCall. + * + * @return descend expression + */ + public OutT desc() { + return toApiSpecificExpression(unresolvedCall(ORDER_DESC, toExpr())); + } + + /** + * Returns true if an expression exists in a given list of expressions. This is a shorthand + * for multiple OR conditions. + * + * <p>If the testing set contains null, the result will be null if the element can not be found + * and true if it can be found. If the element is null, the result is always null. + * + * <p>e.g. "42".in(1, 2, 3) leads to false. + */ + @SafeVarargs + public final OutT in(InT... elements) { + Expression[] args = Stream.concat( + Stream.of(toExpr()), + Arrays.stream(elements).map(ApiExpressionUtils::objectToExpression)) + .toArray(Expression[]::new); + return toApiSpecificExpression(unresolvedCall(IN, args)); + } + + /** + * Returns true if an expression exists in a given table sub-query. The sub-query table + * must consist of one column. This column must have the same data type as the expression. + * + * <p>Note: This operation is not supported in a streaming environment yet. + */ + public OutT in(Table table) { + return toApiSpecificExpression(unresolvedCall(IN, toExpr(), tableRef(table.toString(), table))); + } + + /** + * Returns the start time (inclusive) of a window when applied on a window reference. + */ + public OutT start() { + return toApiSpecificExpression(unresolvedCall(WINDOW_START, toExpr())); + } + + /** + * Returns the end time (exclusive) of a window when applied on a window reference. + * + * <p>e.g. if a window ends at 10:59:59.999 this property will return 11:00:00.000. + */ + public OutT end() { + return toApiSpecificExpression(unresolvedCall(WINDOW_END, toExpr())); + } + + // scalar functions + + /** + * Calculates the remainder of division the given number by another one. + */ + public OutT mod(InT other) { + return toApiSpecificExpression(unresolvedCall(MOD, toExpr(), objectToExpression(other))); + } + + /** + * Calculates the Euler's number raised to the given power. + */ + public OutT exp() { + return toApiSpecificExpression(unresolvedCall(EXP, toExpr())); + } + + /** + * Calculates the base 10 logarithm of the given value. + */ + public OutT log10() { + return toApiSpecificExpression(unresolvedCall(LOG10, toExpr())); + } + + /** + * Calculates the base 2 logarithm of the given value. + */ + public OutT log2() { + return toApiSpecificExpression(unresolvedCall(LOG2, toExpr())); + } + + /** + * Calculates the natural logarithm of the given value. + */ + public OutT ln() { + return toApiSpecificExpression(unresolvedCall(LN, toExpr())); + } + + /** + * Calculates the natural logarithm of the given value. + */ + public OutT log() { + return toApiSpecificExpression(unresolvedCall(LOG, toExpr())); + } + + /** + * Calculates the logarithm of the given value to the given base. + */ + public OutT log(InT base) { + return toApiSpecificExpression(unresolvedCall(LOG, objectToExpression(base), toExpr())); + } + + /** + * Calculates the given number raised to the power of the other value. + */ + public OutT power(InT other) { + return toApiSpecificExpression(unresolvedCall(POWER, toExpr(), objectToExpression(other))); + } + + /** + * Calculates the hyperbolic cosine of a given value. + */ + public OutT cosh() { + return toApiSpecificExpression(unresolvedCall(COSH, toExpr())); + } + + /** + * Calculates the square root of a given value. + */ + public OutT sqrt() { + return toApiSpecificExpression(unresolvedCall(SQRT, toExpr())); + } + + /** + * Calculates the absolute value of given value. + */ + public OutT abs() { + return toApiSpecificExpression(unresolvedCall(ABS, toExpr())); + } + + /** + * Calculates the largest integer less than or equal to a given number. + */ + public OutT floor() { + return toApiSpecificExpression(unresolvedCall(FLOOR, toExpr())); + } + + /** + * Calculates the hyperbolic sine of a given value. + */ + public OutT sinh() { + return toApiSpecificExpression(unresolvedCall(SINH, toExpr())); + } + + /** + * Calculates the smallest integer greater than or equal to a given number. + */ + public OutT ceil() { + return toApiSpecificExpression(unresolvedCall(CEIL, toExpr())); + } + + /** + * Calculates the sine of a given number. + */ + public OutT sin() { + return toApiSpecificExpression(unresolvedCall(SIN, toExpr())); + } + + /** + * Calculates the cosine of a given number. + */ + public OutT cos() { + return toApiSpecificExpression(unresolvedCall(COS, toExpr())); + } + + /** + * Calculates the tangent of a given number. + */ + public OutT tan() { + return toApiSpecificExpression(unresolvedCall(TAN, toExpr())); + } + + /** + * Calculates the cotangent of a given number. + */ + public OutT cot() { + return toApiSpecificExpression(unresolvedCall(COT, toExpr())); + } + + /** + * Calculates the arc sine of a given number. + */ + public OutT asin() { + return toApiSpecificExpression(unresolvedCall(ASIN, toExpr())); + } + + /** + * Calculates the arc cosine of a given number. + */ + public OutT acos() { + return toApiSpecificExpression(unresolvedCall(ACOS, toExpr())); + } + + /** + * Calculates the arc tangent of a given number. + */ + public OutT atan() { + return toApiSpecificExpression(unresolvedCall(ATAN, toExpr())); + } + + /** + * Calculates the hyperbolic tangent of a given number. + */ + public OutT tanh() { + return toApiSpecificExpression(unresolvedCall(TANH, toExpr())); + } + + /** + * Converts numeric from radians to degrees. + */ + public OutT degrees() { + return toApiSpecificExpression(unresolvedCall(DEGREES, toExpr())); + } + + /** + * Converts numeric from degrees to radians. + */ + public OutT radians() { + return toApiSpecificExpression(unresolvedCall(RADIANS, toExpr())); + } + + /** + * Calculates the signum of a given number. + */ + public OutT sign() { + return toApiSpecificExpression(unresolvedCall(SIGN, toExpr())); + } + + /** + * Rounds the given number to integer places right to the decimal point. + */ + public OutT round(InT places) { + return toApiSpecificExpression(unresolvedCall(ROUND, toExpr(), objectToExpression(places))); + } + + /** + * Returns a string representation of an integer numeric value in binary format. Returns null if + * numeric is null. E.g. "4" leads to "100", "12" leads to "1100". + */ + public OutT bin() { + return toApiSpecificExpression(unresolvedCall(BIN, toExpr())); + } + + /** + * Returns a string representation of an integer numeric value or a string in hex format. Returns + * null if numeric or string is null. + * + * <p>E.g. a numeric 20 leads to "14", a numeric 100 leads to "64", and a string "hello,world" leads + * to "68656c6c6f2c776f726c64". + */ + public OutT hex() { + return toApiSpecificExpression(unresolvedCall(HEX, toExpr())); + } + + /** + * Returns a number of truncated to n decimal places. + * If n is 0,the result has no decimal point or fractional part. + * n can be negative to cause n digits left of the decimal point of the value to become zero. + * E.g. truncate(42.345, 2) to 42.34. + */ + public OutT truncate(InT n) { + return toApiSpecificExpression(unresolvedCall(TRUNCATE, toExpr(), objectToExpression(n))); + } + + /** + * Returns a number of truncated to 0 decimal places. + * E.g. truncate(42.345) to 42.0. + */ + public OutT truncate() { + return toApiSpecificExpression(unresolvedCall(TRUNCATE, toExpr())); + } + + // String operations + + /** + * Creates a substring of the given string at given index for a given length. + * + * @param beginIndex first character of the substring (starting at 1, inclusive) + * @param length number of characters of the substring + * @return substring Review comment: nit: remove the `@return` everywhere? ---------------------------------------------------------------- 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
