Literals

Literals are fixed values that you can directly write in FeatureQL queries. They represent constant values of different data types and are essential building blocks for feature definitions.

Literal syntax overview

Each literal type follows specific syntax rules:

• Numeric literals: Write numbers directly (1, -42, 3.14)
• String literals: Enclose in single quotes ('text')
• Boolean literals: Use TRUE or FALSE
• Timestamp literals: Use TIMESTAMP keyword with ISO format (TIMESTAMP '2024-10-15 10:04:00')
• Complex literals: Use constructor syntax (ARRAY[...], ROW(...))

Numeric literals

This example demonstrates the different numeric literal types and their automatic type inference:

• Explicit sizing: TINYINT '1', SMALLINT '1', etc. force specific integer sizes
• Default inference: Plain 1 becomes BIGINT (the default integer type)
• Decimal precision: 1.123 becomes DECIMAL(4, 3) with automatic precision/scale detection
• Floating point: FLOAT '1.1', DOUBLE '1.1', or scientific notation 1.1e0

Other scalar literals

Key points for scalar literals:

• Strings: Single quotes only ('A'), not double quotes
• Booleans: TRUE and FALSE (case insensitive)
• Dates: DATE '2024-10-15' for date-only values
• Timestamps: TIMESTAMP '2024-10-15 10:04:00' with optional microsecond precision
• JSON: JSON '"A"' for JSON-formatted string data

Complex type literals

Complex literals allow you to create structured data:

• Arrays: ARRAY[1,2,3] creates a homogeneous array
• Rows/Structs: ROW(1, 'A') creates structured data with multiple fields
• Named fields: ROW(1 as col1, 'A' as col2) provides field names
• Nested structures: ARRAY[ROW(...)] combines arrays and rows for complex data modeling

Special literal values

FeatureQL provides special literal values for handling missing or undefined data:

• EMPTY: Represents explicitly empty values (different from NULL)
• NULL: Standard SQL NULL values
• Type-specific NULLs: NULL(DOUBLE) creates typed NULL values

Key behaviors:

• EMPTY cannot be cast to other types
• EMPTY is used to represent explicitly empty values for optional function parameters
• NULL without type specification is of type UNSPECIFIED
• NULL(DOUBLE) (NULL directly created as DOUBLE) and NULL::DOUBLE (NULL of type UNSPECIFIED casted to DOUBLE) are equivalent