public abstract class SqlOperator
extends java.lang.Object
SqlOperator
is a type of node in a SQL parse tree (it is NOT a
node in a SQL parse tree). It includes functions, operators such as '=', and
syntactic constructs such as 'case' statements. Operators may represent
query-level expressions (e.g. SqlSelectOperator
or row-level
expressions (e.g. SqlBetweenOperator
.
Operators have formal operands, meaning ordered (and optionally
named) placeholders for the values they operate on. For example, the division
operator takes two operands; the first is the numerator and the second is the
denominator. In the context of subclass SqlFunction
, formal operands
are referred to as parameters.
When an operator is instantiated via a SqlCall
, it is supplied
with actual operands. For example, in the expression 3 /
5
, the literal expression 3
is the actual operand
corresponding to the numerator, and 5
is the actual operand
corresponding to the denominator. In the context of SqlFunction, actual
operands are referred to as arguments
In many cases, the formal/actual distinction is clear from context, in which case we drop these qualifiers.
Modifier and Type | Field and Description |
---|---|
SqlKind |
kind
See
SqlKind . |
private int |
leftPrec
The precedence with which this operator binds to the expression to the
left.
|
static int |
MDX_PRECEDENCE
Maximum precedence.
|
private java.lang.String |
name
The name of the operator/function.
|
static java.lang.String |
NL |
private SqlOperandTypeChecker |
operandTypeChecker
used to validate operand types
|
private SqlOperandTypeInference |
operandTypeInference
used to infer types of unknown operands
|
private SqlReturnTypeInference |
returnTypeInference
used to infer the return type of a call to this operator
|
private int |
rightPrec
The precedence with which this operator binds to the expression to the
right.
|
Modifier | Constructor and Description |
---|---|
protected |
SqlOperator(java.lang.String name,
SqlKind kind,
int prec,
boolean leftAssoc,
SqlReturnTypeInference returnTypeInference,
SqlOperandTypeInference operandTypeInference,
SqlOperandTypeChecker operandTypeChecker)
Creates an operator specifying left/right associativity.
|
protected |
SqlOperator(java.lang.String name,
SqlKind kind,
int leftPrecedence,
int rightPrecedence,
SqlReturnTypeInference returnTypeInference,
SqlOperandTypeInference operandTypeInference,
SqlOperandTypeChecker operandTypeChecker)
Creates an operator.
|
Modifier and Type | Method and Description |
---|---|
<R> R |
acceptCall(SqlVisitor<R> visitor,
SqlCall call)
Accepts a
SqlVisitor , visiting each operand of a call. |
<R> void |
acceptCall(SqlVisitor<R> visitor,
SqlCall call,
boolean onlyExpressions,
SqlBasicVisitor.ArgHandler<R> argHandler)
Accepts a
SqlVisitor , directing an
SqlBasicVisitor.ArgHandler
to visit an operand of a call. |
protected RelDataType |
adjustType(SqlValidator validator,
SqlCall call,
RelDataType type)
Validates and determines coercibility and resulting collation name of
binary operator if needed.
|
boolean |
allowsFraming()
Returns whether this is a window function that allows framing (i.e.
|
boolean |
argumentMustBeScalar(int ordinal)
Returns whether the
ordinal th argument to this operator must
be scalar (as opposed to a query). |
protected void |
checkOperandCount(SqlValidator validator,
SqlOperandTypeChecker argType,
SqlCall call) |
boolean |
checkOperandTypes(SqlCallBinding callBinding,
boolean throwOnFailure)
Checks that the operand values in a
SqlCall to this operator are
valid. |
protected java.util.List<java.lang.String> |
constructArgNameList(SqlCall call) |
protected java.util.List<RelDataType> |
constructArgTypeList(SqlValidator validator,
SqlValidatorScope scope,
SqlCall call,
java.util.List<SqlNode> args,
boolean convertRowArgToColumnList) |
protected java.util.List<SqlNode> |
constructOperandList(SqlValidator validator,
SqlCall call,
java.util.List<java.lang.String> argNames) |
SqlCall |
createCall(SqlLiteral functionQualifier,
SqlParserPos pos,
SqlNode... operands)
Creates a call to this operand with an array of operands.
|
SqlCall |
createCall(SqlNodeList nodeList)
Creates a call to this operand with a list of operands contained in a
SqlNodeList . |
SqlCall |
createCall(SqlParserPos pos,
java.util.List<? extends SqlNode> operandList)
Creates a call to this operand with a list of operands.
|
SqlCall |
createCall(SqlParserPos pos,
SqlNode... operands)
Creates a call to this operand with an array of operands.
|
RelDataType |
deriveType(SqlValidator validator,
SqlValidatorScope scope,
SqlCall call)
Derives the type of a call to this operator.
|
boolean |
equals(java.lang.Object obj) |
java.lang.String |
getAllowedSignatures()
Returns a string describing the expected operand types of a call, e.g.
|
java.lang.String |
getAllowedSignatures(java.lang.String opNameToUse)
Returns a string describing the expected operand types of a call, e.g.
|
SqlKind |
getKind() |
int |
getLeftPrec() |
SqlMonotonicity |
getMonotonicity(SqlCall call,
SqlValidatorScope scope)
Deprecated.
|
SqlMonotonicity |
getMonotonicity(SqlOperatorBinding call)
Returns whether a call to this operator is monotonic.
|
java.lang.String |
getName() |
SqlIdentifier |
getNameAsId()
Returns the fully-qualified name of this operator.
|
SqlOperandCountRange |
getOperandCountRange()
Returns a constraint on the number of operands expected by this operator.
|
SqlOperandTypeChecker |
getOperandTypeChecker() |
SqlOperandTypeInference |
getOperandTypeInference() |
SqlReturnTypeInference |
getReturnTypeInference() |
int |
getRightPrec() |
java.lang.String |
getSignatureTemplate(int operandsCount)
Returns a template describing how the operator signature is to be built.
|
abstract SqlSyntax |
getSyntax()
Returns the syntactic type of this operator, never null.
|
int |
hashCode() |
RelDataType |
inferReturnType(RelDataTypeFactory typeFactory,
java.util.List<RelDataType> operandTypes)
Infers the type of a call to this operator with a given set of operand
types.
|
RelDataType |
inferReturnType(SqlOperatorBinding opBinding)
Infers the return type of an invocation of this operator; only called
after the number and types of operands have already been validated.
|
boolean |
isAggregator()
Returns whether this operator is an aggregate function.
|
boolean |
isDeterministic() |
boolean |
isDynamicFunction() |
boolean |
isGroup()
Returns whether this is a group function.
|
boolean |
isGroupAuxiliary()
Returns whether this is an group auxiliary function.
|
boolean |
isName(java.lang.String testName,
boolean caseSensitive) |
protected static int |
leftPrec(int prec,
boolean leftAssoc) |
(package private) boolean |
needsSpace()
Returns whether this operator should be surrounded by space when
unparsed.
|
protected void |
preValidateCall(SqlValidator validator,
SqlValidatorScope scope,
SqlCall call)
Receives notification that validation of a call to this operator is
beginning.
|
boolean |
requiresDecimalExpansion()
Method to check if call requires expansion when it has decimal operands.
|
boolean |
requiresOrder()
Returns whether this is a window function that requires ordering.
|
boolean |
requiresOver()
Returns whether this is a window function that requires an OVER clause.
|
SqlNode |
rewriteCall(SqlValidator validator,
SqlCall call)
Rewrites a call to this operator.
|
protected static int |
rightPrec(int prec,
boolean leftAssoc) |
java.lang.String |
toString() |
void |
unparse(SqlWriter writer,
SqlCall call,
int leftPrec,
int rightPrec)
Writes a SQL representation of a call to this operator to a writer,
including parentheses if the operators on either side are of greater
precedence.
|
protected void |
unparseListClause(SqlWriter writer,
SqlNode clause) |
protected void |
unparseListClause(SqlWriter writer,
SqlNode clause,
SqlKind sepKind) |
void |
validateCall(SqlCall call,
SqlValidator validator,
SqlValidatorScope scope,
SqlValidatorScope operandScope)
Validates a call to this operator.
|
RelDataType |
validateOperands(SqlValidator validator,
SqlValidatorScope scope,
SqlCall call)
Validates the operands of a call, inferring the return type in the
process.
|
boolean |
validRexOperands(int count,
Litmus litmus)
Returns whether the given operands are valid.
|
public static final java.lang.String NL
public static final int MDX_PRECEDENCE
private final java.lang.String name
public final SqlKind kind
SqlKind
. It's possible to have a name that doesn't match the
kindprivate final int leftPrec
private final int rightPrec
private final SqlReturnTypeInference returnTypeInference
private final SqlOperandTypeInference operandTypeInference
private final SqlOperandTypeChecker operandTypeChecker
protected SqlOperator(java.lang.String name, SqlKind kind, int leftPrecedence, int rightPrecedence, SqlReturnTypeInference returnTypeInference, SqlOperandTypeInference operandTypeInference, SqlOperandTypeChecker operandTypeChecker)
protected SqlOperator(java.lang.String name, SqlKind kind, int prec, boolean leftAssoc, SqlReturnTypeInference returnTypeInference, SqlOperandTypeInference operandTypeInference, SqlOperandTypeChecker operandTypeChecker)
protected static int leftPrec(int prec, boolean leftAssoc)
protected static int rightPrec(int prec, boolean leftAssoc)
public SqlOperandTypeChecker getOperandTypeChecker()
public SqlOperandCountRange getOperandCountRange()
SqlOperandTypeChecker
associated with this
operator.public java.lang.String getName()
public SqlIdentifier getNameAsId()
public SqlKind getKind()
public java.lang.String toString()
toString
in class java.lang.Object
public int getLeftPrec()
public int getRightPrec()
public abstract SqlSyntax getSyntax()
public SqlCall createCall(SqlLiteral functionQualifier, SqlParserPos pos, SqlNode... operands)
The position of the resulting call is the union of the
pos
and the positions of all of the operands.
functionQualifier
- function qualifier (e.g. "DISTINCT"), may bepos
- parser position of the identifier of the calloperands
- array of operandspublic final SqlCall createCall(SqlParserPos pos, SqlNode... operands)
The position of the resulting call is the union of the
pos
and the positions of all of the operands.
pos
- Parser positionoperands
- List of argumentspublic final SqlCall createCall(SqlNodeList nodeList)
SqlNodeList
.
The position of the resulting call inferred from the SqlNodeList.
nodeList
- List of argumentspublic final SqlCall createCall(SqlParserPos pos, java.util.List<? extends SqlNode> operandList)
The position of the resulting call is the union of the
pos
and the positions of all of the operands.
public SqlNode rewriteCall(SqlValidator validator, SqlCall call)
validator
- Validatorcall
- Call to be rewrittenpublic void unparse(SqlWriter writer, SqlCall call, int leftPrec, int rightPrec)
The default implementation of this method delegates to
SqlSyntax.unparse(org.apache.calcite.sql.SqlWriter, org.apache.calcite.sql.SqlOperator, org.apache.calcite.sql.SqlCall, int, int)
.
protected void unparseListClause(SqlWriter writer, SqlNode clause, SqlKind sepKind)
public boolean equals(java.lang.Object obj)
equals
in class java.lang.Object
public boolean isName(java.lang.String testName, boolean caseSensitive)
public int hashCode()
hashCode
in class java.lang.Object
public void validateCall(SqlCall call, SqlValidator validator, SqlValidatorScope scope, SqlValidatorScope operandScope)
This method should not perform type-derivation or perform validation
related related to types. That is done later, by
deriveType(SqlValidator, SqlValidatorScope, SqlCall)
. This method
should focus on structural validation.
A typical implementation of this method first validates the operands, then performs some operator-specific logic. The default implementation just validates the operands.
This method is the default implementation of SqlCall.validate(org.apache.calcite.sql.validate.SqlValidator, org.apache.calcite.sql.validate.SqlValidatorScope)
;
but note that some sub-classes of SqlCall
never call this method.
call
- the call to this operatorvalidator
- the active validatorscope
- validator scopeoperandScope
- validator scope in which to validate operands to this
call; usually equal to scope, but not always because
some operators introduce new scopesSqlNode.validateExpr(SqlValidator, SqlValidatorScope)
,
deriveType(SqlValidator, SqlValidatorScope, SqlCall)
public final RelDataType validateOperands(SqlValidator validator, SqlValidatorScope scope, SqlCall call)
validator
- active validatorscope
- validation scopecall
- call to be validatedprotected void preValidateCall(SqlValidator validator, SqlValidatorScope scope, SqlCall call)
validator
- invoking validatorscope
- validation scopecall
- the call being validatedpublic RelDataType inferReturnType(SqlOperatorBinding opBinding)
SqlReturnTypeInference
to the constructor.opBinding
- description of invocation (not necessarily a
SqlCall
)public RelDataType deriveType(SqlValidator validator, SqlValidatorScope scope, SqlCall call)
This method is an intrinsic part of the validation process so, unlike
inferReturnType(org.apache.calcite.sql.SqlOperatorBinding)
, specific operators would not typically override
this method.
validator
- Validatorscope
- Scope of validationcall
- Call to this operatorprotected java.util.List<java.lang.String> constructArgNameList(SqlCall call)
protected java.util.List<SqlNode> constructOperandList(SqlValidator validator, SqlCall call, java.util.List<java.lang.String> argNames)
protected java.util.List<RelDataType> constructArgTypeList(SqlValidator validator, SqlValidatorScope scope, SqlCall call, java.util.List<SqlNode> args, boolean convertRowArgToColumnList)
boolean needsSpace()
protected RelDataType adjustType(SqlValidator validator, SqlCall call, RelDataType type)
public final RelDataType inferReturnType(RelDataTypeFactory typeFactory, java.util.List<RelDataType> operandTypes)
inferReturnType(SqlOperatorBinding)
.public boolean checkOperandTypes(SqlCallBinding callBinding, boolean throwOnFailure)
SqlCall
to this operator are
valid. Subclasses must either override this method or supply an instance
of SqlOperandTypeChecker
to the constructor.callBinding
- description of callthrowOnFailure
- whether to throw an exception if check fails
(otherwise returns false in that case)protected void checkOperandCount(SqlValidator validator, SqlOperandTypeChecker argType, SqlCall call)
public boolean validRexOperands(int count, Litmus litmus)
fail
, throws an assertion error.
Similar to checkOperandCount(org.apache.calcite.sql.validate.SqlValidator, org.apache.calcite.sql.type.SqlOperandTypeChecker, org.apache.calcite.sql.SqlCall)
, but some operators may have
different valid operands in SqlNode
and RexNode
formats
(some examples are CAST and AND), and this method throws internal errors,
not user errors.
public java.lang.String getSignatureTemplate(int operandsCount)
operandsCount
- is used with functions that can take a variable
number of operandspublic final java.lang.String getAllowedSignatures()
public java.lang.String getAllowedSignatures(java.lang.String opNameToUse)
public SqlOperandTypeInference getOperandTypeInference()
public boolean isAggregator()
Per SQL:2011, there are aggregate functions and window functions. Every aggregate function (e.g. SUM) is also a window function. There are window functions that are not aggregate functions, e.g. RANK, NTILE, LEAD, FIRST_VALUE.
Collectively, aggregate and window functions are called analytic functions. Despite its name, this method returns true for every analytic function.
requiresOrder()
public boolean requiresOver()
For example, returns true for RANK
, DENSE_RANK
and
other ranking functions; returns false for SUM
, COUNT
,
MIN
, MAX
, AVG
(they can be used as non-window
aggregate functions).
If requiresOver
returns true, then isAggregator()
must
also return true.
allowsFraming()
,
requiresOrder()
public boolean requiresOrder()
Per SQL:2011, 2, 6.10: "If <ntile function>, <lead or lag function>, RANK or DENSE_RANK is specified, then the window ordering clause shall be present."
isAggregator()
public boolean allowsFraming()
public boolean isGroup()
Group functions can only appear in the GROUP BY clause.
Examples are HOP
, TUMBLE
, SESSION
.
Group functions have auxiliary functions, e.g. HOP_START
, but
these are not group functions.
public boolean isGroupAuxiliary()
Examples are HOP_START
and HOP_END
(both auxiliary to
HOP
).
isGroup()
public <R> R acceptCall(SqlVisitor<R> visitor, SqlCall call)
SqlVisitor
, visiting each operand of a call. Returns
null.visitor
- Visitorcall
- Call to visitpublic <R> void acceptCall(SqlVisitor<R> visitor, SqlCall call, boolean onlyExpressions, SqlBasicVisitor.ArgHandler<R> argHandler)
SqlVisitor
, directing an
SqlBasicVisitor.ArgHandler
to visit an operand of a call.
The argument handler allows fine control about how the operands are visited, and how the results are combined.
visitor
- Visitorcall
- Call to visitonlyExpressions
- If true, ignores operands which are not
expressions. For example, in the call to the
AS
operatorargHandler
- Called for each operandpublic SqlReturnTypeInference getReturnTypeInference()
@Deprecated public SqlMonotonicity getMonotonicity(SqlCall call, SqlValidatorScope scope)
getMonotonicity(SqlOperatorBinding)
Default implementation returns SqlMonotonicity.NOT_MONOTONIC
.
call
- Call to this operatorscope
- Scope in which the call occurspublic SqlMonotonicity getMonotonicity(SqlOperatorBinding call)
Default implementation returns SqlMonotonicity.NOT_MONOTONIC
.
call
- Call to this operator with particular arguments and information
about the monotonicity of the argumentspublic boolean isDeterministic()
public boolean isDynamicFunction()
public boolean requiresDecimalExpansion()
public boolean argumentMustBeScalar(int ordinal)
ordinal
th argument to this operator must
be scalar (as opposed to a query).
If true (the default), the validator will attempt to convert the argument into a scalar sub-query, which must have one column and return at most one row.
Operators such as SELECT
and EXISTS
override
this method.
Copyright © 2012–2019 The Apache Software Foundation. All rights reserved.