Package org.apache.calcite.sql

Class SqlLiteral

java.lang.Object
org.apache.calcite.sql.SqlNode
org.apache.calcite.sql.SqlLiteral
All Implemented Interfaces:
Cloneable
Direct Known Subclasses:
SqlAbstractDateTimeLiteral, SqlBinaryStringLiteral, SqlCharStringLiteral, SqlIntervalLiteral, SqlNumericLiteral, SqlUnknownLiteral
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 Meaning 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). An Enum
SqlTypeName.INTERVAL_YEAR .. SqlTypeName.INTERVAL_SECOND Interval, for example INTERVAL '1:34' HOUR. SqlIntervalLiteral.IntervalValue.

  • Field Details

  • Constructor Details

  • Method Details

    • getTypeName

      public SqlTypeName getTypeName()
      Returns the value of typeName.

    • valueMatchesType

      public static boolean valueMatchesType(@Nullable Object value, SqlTypeName typeName)
      Returns whether value is appropriate for its type. (We have rules about these things!)

    • clone

      public SqlLiteral clone(SqlParserPos pos)
      Description copied from class: SqlNode
      Clones a SqlNode with a different position.
      Specified by:
      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:

    • getValue

      public @Nullable 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:

    • getValueAs

      public <T> T getValueAs(Class<T> clazz)
      Returns the value of this literal as a given Java type.

      Which type you may ask for depends on typeName. You may always ask for the type where we store the value internally (as defined by valueMatchesType(Object, SqlTypeName)), but may ask for other convenient types.

      For example, numeric literals' values are stored internally as BigDecimal, but other numeric types such as Long and Double are also allowed.

      The result is never null. For the NULL literal, returns a NullSentinel.INSTANCE.

      Type Parameters:
      T - Value type
      Parameters:
      clazz - Desired value type
      Returns:
      Value of the literal in desired type, never null
      Throws:
      AssertionError - if the value type is not supported

    • symbolValue_

      @Deprecated public <E extends Enum<E>> @Nullable E symbolValue_()
      Deprecated.
      Returns the value as a symbol.

    • symbolValue

      public <E extends Enum<E>> @Nullable E symbolValue(Class<E> class_)
      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:

    • value

      public static @Nullable Comparable value(SqlNode node) throws IllegalArgumentException
      Extracts the value from a literal.

      Cases:

      • If the node is a character literal, a chain of string literals, or a CAST of a character literal, returns the value as a NlsString.
      • If the node is a numeric literal, or a negated numeric literal, returns the value as a BigDecimal.
      • If the node is a SqlIntervalQualifier, returns its TimeUnitRange.
      • If the node is INTERVAL_DAY_TIME_ in SqlTypeFamily, returns its sign multiplied by its millisecond equivalent value
      • If the node is INTERVAL_YEAR_MONTH_ in SqlTypeFamily, returns its sign multiplied by its months equivalent value
      • Otherwise throws IllegalArgumentException.
      Throws:
      IllegalArgumentException

    • stringValue

      @Deprecated public static String stringValue(SqlNode node)
      Deprecated.
      Use value(SqlNode)
      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.
      Throws:
      IllegalArgumentException - if node is not a string literal and cannot be unchained.

    • toValue

      public @Nullable 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
      Parameters:
      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(@Nullable SqlNode node, Litmus litmus)
      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 aggregate infinite streams of values.

      The default implementation returns SqlMonotonicity.NOT_MONOTONIC.

      Overrides:
      getMonotonicity in class SqlNode
      Parameters:
      scope - Scope

    • 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(@Nullable Enum<?> 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:

    • createSample

      public static SqlLiteral createSample(SqlSampleSpec sampleSpec, SqlParserPos pos)
      Creates a literal which represents a sample specification.

    • equals

      public boolean equals(@Nullable 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

      @Deprecated public int signum()
      Deprecated.
      Returns sign of value.
      Returns:
      -1, 0 or 1

    • bigDecimalValue

      public @Nullable BigDecimal bigDecimalValue()
      Returns a numeric literal's value as a BigDecimal.

    • getStringValue

      @Deprecated public String getStringValue()
      Deprecated.

    • 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)

    • createUnknown

      public static SqlLiteral createUnknown(String tag, String value, SqlParserPos pos)
      Creates a literal whose type is unknown until validation time. The literal has a tag that looks like a type name, but the tag cannot be resolved until validation time, when we have the mapping from type aliases to types.

      For example,

      TIMESTAMP '1969-07-20 22:56:00'
      calls createUnknown("TIMESTAMP", "1969-07-20 22:56:00"); at validate time, we may discover that "TIMESTAMP" maps to the type "TIMESTAMP WITH LOCAL TIME ZONE".
      Parameters:
      tag - Type name, e.g. "TIMESTAMP", "TIMESTAMP WITH LOCAL TIME ZONE"
      value - String encoding of the value
      pos - Parser position

    • createDate

      @Deprecated public static SqlDateLiteral createDate(Calendar calendar, SqlParserPos pos)
      Deprecated.

    • createDate

      public static SqlDateLiteral createDate(DateString date, SqlParserPos pos)

    • createTimestamp

      @Deprecated public static SqlTimestampLiteral createTimestamp(Calendar calendar, int precision, SqlParserPos pos)
      Deprecated.

    • createTimestamp

      @Deprecated public static SqlTimestampLiteral createTimestamp(TimestampString ts, int precision, SqlParserPos pos)
      Deprecated.

    • createTimestamp

      public static SqlTimestampLiteral createTimestamp(SqlTypeName typeName, TimestampString ts, int precision, SqlParserPos pos)
      Creates a TIMESTAMP or TIMESTAMP WITH LOCAL TIME ZONE literal.

    • createTime

      @Deprecated public static SqlTimeLiteral createTime(Calendar calendar, int precision, SqlParserPos pos)
      Deprecated.

    • createTime

      public static SqlTimeLiteral createTime(TimeString t, 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, @Nullable 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