CAST()

All functions > CORE > CAST()

Returns the given expression casted to the given type, or raise an exception if the conversion fails.

Signatures

Returns: The expression converted to the specified type

CAST(expr: T, as_type: DataTypeEnum.TYPE) → U
sql
ParameterTypeRequiredDescription
exprTYesThe expression to convert
as_typeDataTypeEnum.TYPEYesThe target data type compile-time

Notes

  • Converts a value from one data type to another
  • Numeric targets include TINYINT, SMALLINT, INT, BIGINT, DECIMAL, FLOAT, and DOUBLE
  • Also converts between numerics and VARCHAR
  • Special handling for ROW and ARRAY types
  • Conversion may fail if the value cannot be represented in the target type
  • For safe casting that returns NULL on failure, use TRY CAST(expr AS T)
  • NULL values remain NULL after casting
  • Precision may be lost when converting between numeric types
  • Halfway values go away from zero on every numeric family (CAST(2.5 AS BIGINT) is 3, CAST(2.5e0 AS BIGINT) is 3, CAST(-2.5e0 AS BIGINT) is -3). Other magnitudes truncate toward zero. ROUND on DOUBLE is half away from zero for every value
  • FeatureQL does not apply SQL implicit widening: write CAST when you change category or family

See also

Examples

With CAST operator

FeatureQL
RETURN
    -- Integer to double
    f1 := 42::DOUBLE,
    -- Double to integer (truncates)
    f2 := 3.14e0::BIGINT,
    -- String to integer
    f3 := '123'::BIGINT,
    -- Integer to string
    f4 := 42::VARCHAR,
    -- Decimal to string
    f5 := 3.14::VARCHAR,
    -- String to date
    f6 := '2024-01-15'::DATE
;
Result
f1 DECIMALf2 BIGINTf3 BIGINTf4 VARCHARf5 VARCHARf6 TIMESTAMP
42.03123423.142024-01-15

INTERVAL to VARCHAR

FeatureQL
RETURN
    -- One calendar unit uses a singular label
    f1 := CAST(INTERVAL '1 year' AS VARCHAR),
    -- Several of the same unit use a plural label
    f2 := CAST(INTERVAL '2 years' AS VARCHAR),
    -- Mixed units keep singular or plural per component count
    f3 := CAST(INTERVAL '1 day 2 hours' AS VARCHAR),
    -- Same spelling with the :: cast operator
    f4 := (INTERVAL '2 years')::VARCHAR
;
Result
f1 VARCHARf2 VARCHARf3 VARCHARf4 VARCHAR
1 year2 years1 day 2 hours2 years

Postgres style with :: operator

FeatureQL
RETURN
    -- Integer to double
    f1 := 42::DOUBLE,
    -- Double to integer (truncates)
    f2 := 3.14e0::BIGINT,
    -- String to integer
    f3 := '123'::BIGINT,
    -- Integer to string
    f4 := 42::VARCHAR,
    -- Decimal to string
    f5 := 3.14::VARCHAR,
    -- String to date
    f6 := '2024-01-15'::DATE
;
Result
f1 DECIMALf2 BIGINTf3 BIGINTf4 VARCHARf5 VARCHARf6 TIMESTAMP
42.03123423.142024-01-15

NULL and edge conversions

FeatureQL
RETURN
    -- NULL stays NULL with the target type
    f1 := NULL::BIGINT,
    -- String casts often trim surrounding whitespace
    f2 := '  7 '::BIGINT
;
Result
f1 BIGINTf2 BIGINT
NULL7

Last update at: 2026/10/13 08:32:21