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) → Usql
| Parameter | Type | Required | Description |
|---|---|---|---|
expr | T | Yes | The expression to convert |
as_type | DataTypeEnum.TYPE | Yes | The target data type |
Notes
- Converts a value from one data type to another
- Supports conversions between numeric types (BIGINT, DECIMAL, DOUBLE)
- Supports conversions between numeric and string types (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
- NULL values remain NULL after casting
- Precision may be lost when converting between numeric types
- Scalar casts use the usual widening, truncation, and parsing rules you expect from SQL-style CAST
See also
Examples
With CAST operator
FeatureQL
SELECT
-- Integer to double
f1 := CAST(42 AS DOUBLE),
-- Double to integer (truncates)
f2 := CAST(3.14e0 AS BIGINT),
-- String to integer
f3 := CAST('123' AS BIGINT),
-- Integer to string
f4 := CAST(42 AS VARCHAR),
-- Decimal to string
f5 := CAST(3.14 AS VARCHAR),
-- String to date
f6 := CAST('2024-01-15' AS DATE)
;Result
| f1 VARCHAR | f2 BIGINT | f3 BIGINT | f4 VARCHAR | f5 VARCHAR | f6 TIMESTAMP |
|---|---|---|---|---|---|
| 42.0 | 3 | 123 | 42 | 3.14 | 2024-01-15 |
INTERVAL to VARCHAR
FeatureQL
SELECT
-- 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 VARCHAR | f2 VARCHAR | f3 VARCHAR | f4 VARCHAR |
|---|---|---|---|
| 1 year | 2 years | 1 day 2 hours | 2 years |
Postgres style with :: operator
FeatureQL
SELECT
-- 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 VARCHAR | f2 BIGINT | f3 BIGINT | f4 VARCHAR | f5 VARCHAR | f6 TIMESTAMP |
|---|---|---|---|---|---|
| 42.0 | 3 | 123 | 42 | 3.14 | 2024-01-15 |
NULL and edge conversions
FeatureQL
SELECT
-- NULL stays NULL with the target type
f1 := CAST(NULL AS BIGINT),
-- String casts often trim surrounding whitespace
f2 := CAST(' 7 ' AS BIGINT)
;Result
| f1 BIGINT | f2 BIGINT |
|---|---|
| NULL | 7 |