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
f1 := CAST(42 AS DOUBLE), -- Integer to double
f2 := CAST(3.14E0 AS BIGINT), -- Double to integer (truncates)
f3 := CAST('123' AS BIGINT), -- String to integer
f4 := CAST(42 AS VARCHAR), -- Integer to string
f5 := CAST(3.14 AS VARCHAR), -- Decimal to string
f6 := CAST('2024-01-15' AS DATE) -- String to 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
f1 := CAST(INTERVAL '1 year' AS VARCHAR), -- One calendar unit uses a singular label
f2 := CAST(INTERVAL '2 years' AS VARCHAR), -- Several of the same unit use a plural label
f3 := CAST(INTERVAL '1 day 2 hours' AS VARCHAR), -- Mixed units keep singular or plural per component count
f4 := (INTERVAL '2 years')::VARCHAR -- Same spelling with the :: cast operator
;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
f1 := 42::DOUBLE, -- Integer to double
f2 := 3.14E0::BIGINT, -- Double to integer (truncates)
f3 := '123'::BIGINT, -- String to integer
f4 := 42::VARCHAR, -- Integer to string
f5 := 3.14::VARCHAR, -- Decimal to string
f6 := '2024-01-15'::DATE -- String to 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
f1 := CAST(NULL AS BIGINT), -- NULL stays NULL with the target type
f2 := CAST(' 7 ' AS BIGINT) -- String casts often trim surrounding whitespace
;Result
| f1 BIGINT | f2 BIGINT |
|---|---|
| NULL | 7 |