SqlLiteral (Calcite Core 1.2.0-incubating API)

java.lang.Object
- org.apache.calcite.sql.SqlNode
- - org.apache.calcite.sql.SqlLiteral

All Implemented Interfaces:: Cloneable

Direct Known Subclasses:: SqlBinaryStringLiteral, SqlCharStringLiteral, SqlDateLiteral, SqlIntervalLiteral, SqlNumericLiteral, SqlTimeLiteral, SqlTimestampLiteral

public class SqlLiteral
extends SqlNode

A SqlLiteral is a constant. It is, appropriately, immutable.

How is the value stored? In that respect, the class is somewhat of a black box. There is a getValue() method which returns the value as an object, but the type of that value is implementation detail, and it is best that your code does not depend upon that knowledge. It is better to use task-oriented methods such as SqlNode.toSqlString(SqlDialect) and toValue().

If you really need to access the value directly, you should switch on the value of the typeName field, rather than making assumptions about the runtime type of the value.

The allowable types and combinations are:

Allowable types for SqlLiteral
TypeName	Meaing	Value type
`SqlTypeName.NULL`	The null value. It has its own special type.	null
`SqlTypeName.BOOLEAN`	Boolean, namely `TRUE`, `FALSE` or `UNKNOWN`.	`Boolean`, or null represents the UNKNOWN value
`SqlTypeName.DECIMAL`	Exact number, for example `0`, `-.5`, `12345`.	`BigDecimal`
`SqlTypeName.DOUBLE`	Approximate number, for example `6.023E-23`.	`BigDecimal`
`SqlTypeName.DATE`	Date, for example `DATE '1969-04'29'`	`Calendar`
`SqlTypeName.TIME`	Time, for example `TIME '18:37:42.567'`	`Calendar`
`SqlTypeName.TIMESTAMP`	Timestamp, for example `TIMESTAMP '1969-04-29 18:37:42.567'`	`Calendar`
`SqlTypeName.CHAR`	Character constant, for example `'Hello, world!'`, `''`, `_N'Bonjour'`, `_ISO-8859-1'It''s superman!' COLLATE SHIFT_JIS$ja_JP$2`. These are always CHAR, never VARCHAR.	`NlsString`
`SqlTypeName.BINARY`	Binary constant, for example `X'ABC'`, `X'7F'`. Note that strings with an odd number of hexits will later become values of the BIT datatype, because they have an incomplete number of bytes. But here, they are all binary constants, because that's how they were written. These constants are always BINARY, never VARBINARY.	`BitString`
`SqlTypeName.SYMBOL`	A symbol is a special type used to make parsing easier; it is not part of the SQL standard, and is not exposed to end-users. It is used to hold a symbol, such as the LEADING flag in a call to the function `TRIM([LEADING\|TRAILING\|BOTH] chars FROM string)`.	A class which implements the `SqlLiteral.SqlSymbol` interface
`SqlTypeName.INTERVAL_DAY_TIME`	Interval, for example `INTERVAL '1:34' HOUR`.	`SqlIntervalLiteral.IntervalValue`.

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static interface SqlLiteral.SqlSymbol
A value must implement this interface if it is to be embedded as a SqlLiteral of type SYMBOL.

Nested Classes
Modifier and Type	Class and Description
`static interface`	`SqlLiteral.SqlSymbol` A value must implement this interface if it is to be embedded as a SqlLiteral of type SYMBOL.

Field Summary

Fields
Modifier and Type Field and Description

protected Object value
The value of this literal.
- Fields inherited from class org.apache.calcite.sql.SqlNode
  EMPTY_ARRAY, pos

Fields
Modifier and Type	Field and Description
`protected Object`	`value` The value of this literal.

Constructor Summary

Constructors
Modifier Constructor and Description

protected SqlLiteral(Object value, SqlTypeName typeName, SqlParserPos pos)
Creates a SqlLiteral.

Constructors
Modifier	Constructor and Description
`protected`	`SqlLiteral(Object value, SqlTypeName typeName, SqlParserPos pos)` Creates a `SqlLiteral`.

Method Summary

Methods
Modifier and Type	Method and Description
`<R> R`	`accept(SqlVisitor<R> visitor)` Accepts a generic visitor.
`BigDecimal`	`bigDecimalValue()` Returns a numeric literal's value as a `BigDecimal`.
`boolean`	`booleanValue()` Returns the value as a boolean.
`SqlNode`	`clone(SqlParserPos pos)` Clones a SqlNode with a different position.
`static SqlNumericLiteral`	`createApproxNumeric(String s, SqlParserPos pos)`
`static SqlBinaryStringLiteral`	`createBinaryString(byte[] bytes, SqlParserPos pos)` Creates a literal like X'ABAB' from an array of bytes.
`static SqlBinaryStringLiteral`	`createBinaryString(String s, SqlParserPos pos)` Creates a literal like X'ABAB'.
`static SqlLiteral`	`createBoolean(boolean b, SqlParserPos pos)` Creates a boolean literal.
`static SqlCharStringLiteral`	`createCharString(String s, SqlParserPos pos)` Creates a string literal in the system character set.
`static SqlCharStringLiteral`	`createCharString(String s, String charSet, SqlParserPos pos)` Creates a string literal, with optional character-set.
`static SqlDateLiteral`	`createDate(Calendar calendar, SqlParserPos pos)`
`static SqlNumericLiteral`	`createExactNumeric(String s, SqlParserPos pos)`
`static SqlIntervalLiteral`	`createInterval(int sign, String intervalStr, SqlIntervalQualifier intervalQualifier, SqlParserPos pos)` Creates an interval literal.
`static SqlNumericLiteral`	`createNegative(SqlNumericLiteral num, SqlParserPos pos)`
`static SqlLiteral`	`createNull(SqlParserPos pos)` Creates a NULL literal.
`static SqlLiteral`	`createSample(SqlSampleSpec sampleSpec, SqlParserPos pos)` Creates a literal which represents a sample specification.
`RelDataType`	`createSqlType(RelDataTypeFactory typeFactory)`
`static SqlLiteral`	`createSymbol(SqlLiteral.SqlSymbol o, SqlParserPos pos)` Creates a literal which represents a parser symbol, for example the `TRAILING` keyword in the call `Trim(TRAILING 'x' FROM 'Hello world!')`.
`static SqlTimeLiteral`	`createTime(Calendar calendar, int precision, SqlParserPos pos)`
`static SqlTimestampLiteral`	`createTimestamp(Calendar calendar, int precision, SqlParserPos pos)`
`static SqlLiteral`	`createUnknown(SqlParserPos pos)`
`boolean`	`equals(Object obj)`
`boolean`	`equalsDeep(SqlNode node, boolean fail)` Returns whether this node is structurally equivalent to another node.
`SqlKind`	`getKind()` Returns the type of node this is, or `SqlKind.OTHER` if it's nothing special.
`SqlMonotonicity`	`getMonotonicity(SqlValidatorScope scope)` Returns whether expression is always ascending, descending or constant.
`String`	`getStringValue()`
`SqlTypeName`	`getTypeName()`
`Object`	`getValue()` Returns the value of this literal.
`int`	`hashCode()`
`int`	`intValue(boolean exact)` Returns the integer value of this literal.
`long`	`longValue(boolean exact)` Returns the long value of this literal.
`static SqlSampleSpec`	`sampleValue(SqlNode node)` Extracts the `SqlSampleSpec` value from a symbol literal.
`int`	`signum()` Returns sign of value.
`static String`	`stringValue(SqlNode node)` Extracts the string value from a string literal, a chain of string literals, or a CAST of a string literal.
`<E extends SqlLiteral.SqlSymbol> E`	`symbolValue()` Returns the value as a symbol.
`String`	`toValue()` For calc program builder - value may be different than `unparse(org.apache.calcite.sql.SqlWriter, int, int)` Typical values: Hello, world! 12.34 {null} 1969-04-29
`static SqlLiteral`	`unchain(SqlNode node)` Converts a chained string literals into regular literals; returns regular literals unchanged.
`SqlLiteral`	`unescapeUnicode(char unicodeEscapeChar)` Transforms this literal (which must be of type character) into a new one in which 4-digit Unicode escape sequences have been replaced with the corresponding Unicode characters.
`void`	`unparse(SqlWriter writer, int leftPrec, int rightPrec)` Writes a SQL representation of this node to a writer.
`void`	`validate(SqlValidator validator, SqlValidatorScope scope)` Validates this node.
`static boolean`	`valueMatchesType(Object value, SqlTypeName typeName)`

Methods inherited from class org.apache.calcite.sql.SqlNode
clone, cloneArray, equalDeep, equalDeep, findValidOptions, getParserPosition, isA, toSqlString, toSqlString, toString, validateExpr

Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - value
```
protected final Object value
```
    The value of this literal. The type of the value must be appropriate for the typeName, as defined by the valueMatchesType(java.lang.Object, org.apache.calcite.sql.type.SqlTypeName) method.
- Constructor Detail
  - SqlLiteral
```
protected SqlLiteral(Object value,
          SqlTypeName typeName,
          SqlParserPos pos)
```
    Creates a SqlLiteral.
- Method Detail
  - getTypeName
```
public SqlTypeName getTypeName()
```
    Returns:
    value of typeName
  - valueMatchesType
```
public static boolean valueMatchesType(Object value,
                       SqlTypeName typeName)
```
    Returns:
    whether value is appropriate for its type (we have rules about these things)
  - clone
```
public SqlNode clone(SqlParserPos pos)
```
    Description copied from class: SqlNode
    
    Clones a SqlNode with a different position.
    
    Overrides:
    
    clone in class SqlNode
  - getKind
```
public SqlKind getKind()
```
    Description copied from class: SqlNode
    
    Returns the type of node this is, or SqlKind.OTHER if it's nothing special.
    
    Overrides:
    
    getKind in class SqlNode
    
    Returns:
    a SqlKind value, never null
    See Also:
    SqlNode.isA(java.util.Set<org.apache.calcite.sql.SqlKind>)
  - getValue
```
public Object getValue()
```
    Returns the value of this literal.
    Try not to use this method! There are so many different kinds of values, it's better to to let SqlLiteral do whatever it is you want to do.
    
    See Also:
    booleanValue(), symbolValue()
  - symbolValue
```
public <E extends SqlLiteral.SqlSymbol> E symbolValue()
```
    Returns the value as a symbol.
  - booleanValue
```
public boolean booleanValue()
```
    Returns the value as a boolean.
  - sampleValue
```
public static SqlSampleSpec sampleValue(SqlNode node)
```
    Extracts the SqlSampleSpec value from a symbol literal.
    
    Throws:
    
    ClassCastException - if the value is not a symbol literal
    See Also:
    createSymbol(SqlSymbol, SqlParserPos)
  - stringValue
```
public static String stringValue(SqlNode node)
```
    Extracts the string value from a string literal, a chain of string literals, or a CAST of a string literal.
  - unchain
```
public static SqlLiteral unchain(SqlNode node)
```
    Converts a chained string literals into regular literals; returns regular literals unchanged.
  - toValue
```
public String toValue()
```
    For calc program builder - value may be different than unparse(org.apache.calcite.sql.SqlWriter, int, int) Typical values:
    - Hello, world!
    - 12.34
    - {null}
    - 1969-04-29
    Returns:
    string representation of the value
  - validate
```
public void validate(SqlValidator validator,
            SqlValidatorScope scope)
```
    Description copied from class: SqlNode
    
    Validates this node.
    The typical implementation of this method will make a callback to the validator appropriate to the node type and context. The validator has methods such as SqlValidator.validateLiteral(org.apache.calcite.sql.SqlLiteral) for these purposes.
    
    Specified by:
    
    validate in class SqlNode
    
    scope - Validator
  - accept
```
public <R> R accept(SqlVisitor<R> visitor)
```
    Description copied from class: SqlNode
    
    Accepts a generic visitor.
    Implementations of this method in subtypes simply call the appropriate visit method on the visitor object.
    The type parameter R must be consistent with the type parameter of the visitor.
    
    Specified by:
    
    accept in class SqlNode
  - equalsDeep
```
public boolean equalsDeep(SqlNode node,
                 boolean fail)
```
    Description copied from class: SqlNode
    Returns whether this node is structurally equivalent to another node. Some examples:
    - 1 + 2 is structurally equivalent to 1 + 2
    - 1 + 2 + 3 is structurally equivalent to (1 + 2) + 3, but not to 1 + (2 + 3), because the '+' operator is left-associative
    Specified by:
    
    equalsDeep in class SqlNode
  - getMonotonicity
```
public SqlMonotonicity getMonotonicity(SqlValidatorScope scope)
```
    Description copied from class: SqlNode
    
    Returns whether expression is always ascending, descending or constant. This property is useful because it allows to safely aggregte infinite streams of values.
    The default implementation returns SqlMonotonicity.NOT_MONOTONIC.
    
    Overrides:
    
    getMonotonicity in class SqlNode
  - createNull
```
public static SqlLiteral createNull(SqlParserPos pos)
```
    Creates a NULL literal.
    There's no singleton constant for a NULL literal. Instead, nulls must be instantiated via createNull(), because different instances have different context-dependent types.
  - createBoolean
```
public static SqlLiteral createBoolean(boolean b,
                       SqlParserPos pos)
```
    Creates a boolean literal.
  - createUnknown
```
public static SqlLiteral createUnknown(SqlParserPos pos)
```
  - createSymbol
```
public static SqlLiteral createSymbol(SqlLiteral.SqlSymbol o,
                      SqlParserPos pos)
```
    Creates a literal which represents a parser symbol, for example the TRAILING keyword in the call Trim(TRAILING 'x' FROM 'Hello world!').
    
    See Also:
    symbolValue()
  - createSample
```
public static SqlLiteral createSample(SqlSampleSpec sampleSpec,
                      SqlParserPos pos)
```
    Creates a literal which represents a sample specification.
  - equals
```
public boolean equals(Object obj)
```
    Overrides:
    
    equals in class Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - intValue
```
public int intValue(boolean exact)
```
    Returns the integer value of this literal.
    
    Parameters:
    exact - Whether the value has to be exact. If true, and the literal is a fraction (e.g. 3.14), throws. If false, discards the fractional part of the value.
    
    Returns:
    Integer value of this literal
  - longValue
```
public long longValue(boolean exact)
```
    Returns the long value of this literal.
    
    Parameters:
    exact - Whether the value has to be exact. If true, and the literal is a fraction (e.g. 3.14), throws. If false, discards the fractional part of the value.
    
    Returns:
    Long value of this literal
  - signum
```
public int signum()
```
    Returns sign of value.
    
    Returns:
    -1, 0 or 1
  - bigDecimalValue
```
public BigDecimal bigDecimalValue()
```
    Returns a numeric literal's value as a BigDecimal.
  - getStringValue
```
public String getStringValue()
```
  - unparse
```
public void unparse(SqlWriter writer,
           int leftPrec,
           int rightPrec)
```
    Description copied from class: SqlNode
    
    Writes a SQL representation of this node to a writer.
    The leftPrec and rightPrec parameters give us enough context to decide whether we need to enclose the expression in parentheses. For example, we need parentheses around "2 + 3" if preceded by "5 *". This is because the precedence of the "*" operator is greater than the precedence of the "+" operator.
    The algorithm handles left- and right-associative operators by giving them slightly different left- and right-precedence.
    If SqlWriter.isAlwaysUseParentheses() is true, we use parentheses even when they are not required by the precedence rules.
    For the details of this algorithm, see SqlCall.unparse(org.apache.calcite.sql.SqlWriter, int, int).
    
    Specified by:
    
    unparse in class SqlNode
    
    Parameters:
    writer - Target writer
    leftPrec - The precedence of the SqlNode immediately preceding this node in a depth-first scan of the parse tree
    rightPrec - The precedence of the SqlNode immediately
  - createSqlType
```
public RelDataType createSqlType(RelDataTypeFactory typeFactory)
```
  - createDate
```
public static SqlDateLiteral createDate(Calendar calendar,
                        SqlParserPos pos)
```
  - createTimestamp
```
public static SqlTimestampLiteral createTimestamp(Calendar calendar,
                                  int precision,
                                  SqlParserPos pos)
```
  - createTime
```
public static SqlTimeLiteral createTime(Calendar calendar,
                        int precision,
                        SqlParserPos pos)
```
  - createInterval
```
public static SqlIntervalLiteral createInterval(int sign,
                                String intervalStr,
                                SqlIntervalQualifier intervalQualifier,
                                SqlParserPos pos)
```
    Creates an interval literal.
    
    Parameters:
    intervalStr - input string of '1:23:04'
    intervalQualifier - describes the interval type and precision
    pos - Parser position
  - createNegative
```
public static SqlNumericLiteral createNegative(SqlNumericLiteral num,
                               SqlParserPos pos)
```
  - createExactNumeric
```
public static SqlNumericLiteral createExactNumeric(String s,
                                   SqlParserPos pos)
```
  - createApproxNumeric
```
public static SqlNumericLiteral createApproxNumeric(String s,
                                    SqlParserPos pos)
```
  - createBinaryString
```
public static SqlBinaryStringLiteral createBinaryString(String s,
                                        SqlParserPos pos)
```
    Creates a literal like X'ABAB'. Although it matters when we derive a type for this beastie, we don't care at this point whether the number of hexits is odd or even.
  - createBinaryString
```
public static SqlBinaryStringLiteral createBinaryString(byte[] bytes,
                                        SqlParserPos pos)
```
    Creates a literal like X'ABAB' from an array of bytes.
    
    Parameters:
    bytes - Contents of binary literal
    pos - Parser position
    
    Returns:
    Binary string literal
  - createCharString
```
public static SqlCharStringLiteral createCharString(String s,
                                    SqlParserPos pos)
```
    Creates a string literal in the system character set.
    
    Parameters:
    s - a string (without the sql single quotes)
    pos - Parser position
  - createCharString
```
public static SqlCharStringLiteral createCharString(String s,
                                    String charSet,
                                    SqlParserPos pos)
```
    Creates a string literal, with optional character-set.
    
    Parameters:
    s - a string (without the sql single quotes)
    charSet - character set name, null means take system default
    pos - Parser position
    
    Returns:
    A string literal
    
    Throws:
    
    UnsupportedCharsetException - if charSet is not null but there is no character set with that name in this environment
  - unescapeUnicode
```
public SqlLiteral unescapeUnicode(char unicodeEscapeChar)
```
    Transforms this literal (which must be of type character) into a new one in which 4-digit Unicode escape sequences have been replaced with the corresponding Unicode characters.
    
    Parameters:
    unicodeEscapeChar - escape character (e.g. backslash) for Unicode numeric sequences; 0 implies no transformation
    
    Returns:
    transformed literal

Class SqlLiteral

Nested Class Summary

Field Summary

Fields inherited from class org.apache.calcite.sql.SqlNode

Constructor Summary

Method Summary

Methods inherited from class org.apache.calcite.sql.SqlNode

Methods inherited from class java.lang.Object

Field Detail

value

Constructor Detail

SqlLiteral

Method Detail

getTypeName

valueMatchesType

clone

getKind

getValue

symbolValue

booleanValue

sampleValue

stringValue

unchain

toValue

validate

accept

equalsDeep

getMonotonicity

createNull

createBoolean

createUnknown

createSymbol

createSample

equals

hashCode

intValue

longValue

signum

bigDecimalValue

getStringValue

unparse

createSqlType

createDate

createTimestamp

createTime

createInterval

createNegative

createExactNumeric

createApproxNumeric

createBinaryString

createBinaryString

createCharString

createCharString

unescapeUnicode