Functions Advanced
Disambiguating Operator and Function Forms
In FeatureQL, some operations can be written using either an operator-style syntax or a function-style syntax. However, certain names like FLATTEN, MERGE, or COALESCE can be ambiguous because they may refer to either an operator or a function, depending on the context and argument types.
For example, consider FLATTEN(ARRAY['a', 'b']). Is this calling the operator that flattens the array ['a', 'b'], or is it invoking the function that flattens multiple features of type ARRAY named "a" and "b"? Ideally, the system would resolve this based on the argument types, but since type inference occurs after parsing, this is not currently possible.
To resolve this ambiguity, FeatureQL introduces a clear convention: append _FUNC to the operator name. This makes your intent explicit and ensures the correct behavior, regardless of argument types.
Below is a summary of the operator and function forms for commonly ambiguous operations:
| Operator Form | Function Form |
|---|---|
FLATTEN(expr1, expr2, ...) | FLATTEN_FUNC(ARRAY[expr1, expr2, ...]) |
MERGE(expr1, expr2, ...) | MERGE_FUNC(ARRAY[expr1, expr2, ...]) |
ARRAY_MERGE(expr1, expr2, ...) | ARRAY_MERGE_FUNC(ARRAY[expr1, expr2, ...]) |
ZIP(expr1, expr2, ...) | ZIP_FUNC(ARRAY[expr1, expr2, ...]) |
ARRAY_CONCAT(expr1, expr2, ...) | ARRAY_CONCAT_FUNC(ARRAY[expr1, expr2, ...]) |
ALL(expr1, expr2, ...) | ALL_FUNC(ARRAY[expr1, expr2, ...]) |
ANY(expr1, expr2, ...) | ANY_FUNC(ARRAY[expr1, expr2, ...]) |
NONE(expr1, expr2, ...) | NONE_FUNC(ARRAY[expr1, expr2, ...]) |
GREATEST(expr1, expr2, ...) | GREATEST_FUNC(ARRAY[expr1, expr2, ...]) |
LEAST(expr1, expr2, ...) | LEAST_FUNC(ARRAY[expr1, expr2, ...]) |
COALESCE(expr1, expr2, ...) | COALESCE_FUNC(ARRAY[expr1, expr2, ...]) |
CONCAT(expr1, expr2, ...) | CONCAT_FUNC(ARRAY[expr1, expr2, ...]) |
CONCAT_WS(separator, expr1, ...) | CONCAT_WS_FUNC(separator, ARRAY[expr1, expr2, ...]) |
Tip:
- Use the operator form for simple, direct expressions.
- Use the
_FUNCform when you want to pass an array of expressions or need to avoid ambiguity.
This convention ensures your FeatureQL code is both clear and robust, regardless of how complex your expressions become.
Array-based evaluation modes
Some functions support array-based evaluation for more dynamic behavior:
This example demonstrates how CASE_WHEN() can process arrays of conditions and values, where each row can have different evaluation paths based on the array contents.
Static vs. dynamic arrays
Functions have requirements about array shapes that must be validated at compile time:
Key constraint: Some function parameters require "static arrays" (arrays with fixed, compile-time known structure) rather than dynamic arrays generated at runtime.