Skip to main content
Last updated on

Type Conversion

In Doris, each expression has a type, such as 1, col1, and from_unixtime(col2) in the expression select 1, col1, from_unixtime(col2) from table1. The process of converting an expression from one type to another is called "type conversion."

Type conversion occurs in two cases: explicit conversion and implicit conversion.

All type conversions follow specific rules. We describe the related rules according to the target type of the conversion. For example, converting from INT to DOUBLE and converting from STRING to DOUBLE are both described in the Conversion to FLOAT/DOUBLE document.

Whether a conversion can occur and whether the result is a nullable type depends on whether strict mode is enabled (session variable enable_strict_cast). Generally, when strict mode is enabled, data that fails conversion will immediately cause an error and result in SQL failure. When strict mode is disabled, data rows that fail conversion will result in NULL.

See UUID conversion for parsing and migration rules. Strings can be cast to UUID, and UUID can be cast to strings or VARIANT, but not directly to numeric, date/time, or IP types.

Explicit Conversion​

Explicit conversion is done through the CAST function, for example:

CAST(1.23 as INT) converts the number 1.23 to INT type.

CAST(colA as DATETIME(6)) converts the column/expression colA to DATETIME(6) type (i.e., a DATETIME type with microsecond precision).

The following describes the type conversion relationships between different types under strict mode (enable_strict_cast = true) and non-strict mode (enable_strict_cast = false), including the following four cases:

SymbolMeaning
xNot allowed to convert
PThe return type will be Nullable only when the input parameter is already a Nullable type, i.e., the conversion will not convert non-Null values to Null
AThe return type is always Nullable. The conversion may convert non-Null values to Null
OThe return type is Nullable when the conversion from input type to output type may cause overflow. For non-Null input values, if the conversion actually causes overflow, the conversion result may be Null

The specific type conversion rules and Nullable properties, please check the type conversion documents in the current directory.

Strict Mode​

From\Tobooltinyintsmallintintbigintlargeintfloatdoubledecimaldatedatetimetimestamp_nstimeIPv4IPv6charvarcharstringbitmaphlljsonarraymapstructvariantUUID
boolPPPPPPPPOxxxxxxxxPxxxx
tinyintPPPPPPPPOAAAAxxxxPxxxx
smallintPAPPPPPPOAAAAxxxxPxxxx
intPAAPPPPPOAAAAxxxxPxxxx
bigintPAAAPPPPOAAAAxxxxPxxxx
largeintPAAAAPPPOAAAAxxxxPxxxx
floatPAAAAAPPAAAAAxxxxPxxxx
doublePAAAAAPPAAAAAxxxxPxxxx
decimalPOOOOOPPOAAAAxxxxPxxxx
datexxxPPPxxxPPAxxxxxxxxxx
datetimexxxxPPxxxPAAPxxxxxxxxx
timestamp_nsxxxxPPxxxPPPPxxPPPxxxxxxPx
timexAAAPPxxxPPPAxxxxxxxxx
IPv4xxxxxxxxxxxxxPPxxxxxxx
IPv6xxxxxxxxxxxxxxPxxxxxxx
charAAAAAAAAAAAAAAAxxAAAAA
varcharAAAAAAAAAAAAAAAxxAAAAA
stringAAAAAAAAAAAAAAAxxAAAAA
bitmapxxxxxxxxxxxxxxxxxxPxxxxxx
hllxxxxxxxxxxxxxxxxxxxPxxxxx
jsonAAAAAAAAAxxxxxxAAAxxPAxAx
arrayxxxxxxxxxxxxxxxxxPPxxx
mapxxxxxxxxxxxxxxxxxxxPxx
structxxxxxxxxxxxxxxxxxPxxPx
variantAA
UUIDxxxxxxxxxxxxxxxPPPxxxxxxPP

Non-strict Mode​

From\Tobooltinyintsmallintintbigintlargeintfloatdoubledecimaldatedatetimetimestamp_nstimeIPv4IPv6charvarcharstringbitmaphlljsonarraymapstructvariantUUID
boolPPPPPPPPOxxxxxxxxPxxxx
tinyintPPPPPPPPOAAAAxxxxPxxxx
smallintPAPPPPPPOAAAAxxxxPxxxx
intPAAPPPPPOAAAAxxxxPxxxx
bigintPAAAPPPPOAAAAxxxxPxxxx
largeintPAAAAPPPOAAAAxxxxPxxxx
floatPAAAAAPPAAAAAxxxxPxxxx
doublePAAAAAPPAAAAAxxxxPxxxx
decimalPOOOOOPPOAAAAxxxxPxxxx
datexxxPPPPPxPPAxxxxxxxxxx
datetimexxxxPPPPxPAAPxxxxxxxxx
timestamp_nsxxxxPPPPxPPPPxxPPPxxxxxxPx
timexAAAPPPPxPPPAxxxxxxxxx
IPv4xxxxxxxxxxxxxPPxxxxxxx
IPv6xxxxxxxxxxxxxxPxxxxxxx
charAAAAAAAAAAAAAAAxxAAAAA
varcharAAAAAAAAAAAAAAAxxAAAAA
stringAAAAAAAAAAAAAAAxxAAAAA
bitmapxxxxxxxxxxxxxxxxxxPxxxxxx
hllxxxxxxxxxxxxxxxxxxxPxxxxx
jsonAAAAAAAAAxxxxxxAAAxxPAxAx
arrayxxxxxxxxxxxxxxxxxPPxxx
mapxxxxxxxxxxxxxxxxxxxPxx
structxxxxxxxxxxxxxxxxxPxxPx
variantAA
UUIDxxxxxxxxxxxxxxxPPPxxxxxxPP

For detailed TIMESTAMP_NS conversion rules, see Cast to TIMESTAMP_NS. TIMESTAMPTZ is not included in the matrices above; conversion between TIMESTAMP_NS and TIMESTAMPTZ is supported in both strict and non-strict modes.

Implicit Conversion​

Implicit conversion occurs in certain situations where the input SQL does not explicitly specify, but Doris automatically plans the CAST expression. It mainly occurs in scenarios such as:

  1. When a function call is made, the type of the actual parameter does not match the type of the function signature.

  2. When the types on both sides of a mathematical expression are inconsistent.

etc.

Conversion matrix​

TODO

Common Type​

When an implicit conversion is required due to the operands being used as mathematical operations, the first step is to determine the common type. If the operands on both sides are not consistent with the common type, each will plan a CAST expression to the common type.

When a string and UUID require a common type in comparisons, CASE, COALESCE, or set operations, the common type is UUID and the string is parsed as UUID text. Invalid strings follow CAST rules. UUID does not participate in numeric arithmetic common-type inference.

Report issue
ASF
Resources
Community
Join the community
Copyright © 2026 The Apache Software Foundation,Licensed under the Apache License, Version 2.0. Apache, Doris, Apache Doris, the Apache feather logo and the Apache Doris logo are trademarks of The Apache Software Foundation.