Inputs & binding

FeatureQL allows you to declare input features as placeholders that can be bound to values for evaluation. These input features act as primary keys for each row.

Declaring input features

Input features act as typed placeholders in your query:

SELECT
    INPUT(BIGINT) as NUMBER,      -- Declare an input of type BIGINT
    NUMBER * 2 as OTHER_NUMBER    -- Use this input as base for other computations

Key characteristics of inputs:

• Type safety: Inputs must declare their expected data type
• Dependency tracking: Features depending on inputs are automatically resolved
• Flexibility: Inputs can be bound to different values for different evaluations

Bind values to inputs

Input features must be bound to concrete values before query execution.

FeatureQL provides several binding mechanisms for different use cases.

Bind single values

This example shows basic input binding:

• BIND_VALUE('FeatureQL') provides a concrete value for the NAME input
• BIND_VALUE(5) provides a value for the NUMBER input
• Derived features (HELLO, OTHER_NUMBER) are automatically computed using the bound values

Bind intermediate features

You can also bind any intermediate feature, not just direct inputs.

Let's consider a FEATURE4 that is computed as FEATURE3 * 2, and FEATURE3 is computed as FEATURE1 + FEATURE2.

You can naturally bind FEATURE1 and FEATURE2 to values and FEATURE4 will be computed as (FEATURE1 + FEATURE2) * 2.

You can also bind intermediary feature FEATURE3 to a value, and FEATURE4 will be computed as FEATURE3 * 2.

@fql-playground(bind_intermediary_overwritten)

Bind to multiple input sets

For batch processing or analytical workloads, you often need to evaluate features for multiple inputs simultaneously.

FeatureQL provides several operators for batch binding:

• BIND_TABLE(): Transform inline arrays into input sets
• BIND_SQL(): Execute SQL queries to generate input sets
• BIND_KEYSET(): Select entity keys based on criteria (business extension)

Using inline arrays with BIND_TABLE()

The BIND_TABLE() operator transforms arrays into table rows, enabling batch evaluation:

Single feature binding:

This demonstrates:

• BIND_TABLE(ARRAY[1, 3, 5]) creates three rows with different FEATUREF1 values
• Each row produces a corresponding FEATUREFF value (FEATUREF1 + 1)
• Result: 3 rows with computations for values 1, 3, and 5

Multiple features with single binding:

Key insights:

• BIND_TABLE(ARRAY[ROW(1, 2), ROW(3, 4), ROW(5, 6)]) binds both features simultaneously
• Each ROW provides values for (FEATUREF1, FEATUREF2) in a single operation
• Creates exactly 3 rows with coordinated input pairs

Multiple features with separate bindings:

Important difference:

• Separate BIND_TABLE() calls create a Cartesian product
• 3 values × 3 values = 9 total combinations
• Use this pattern when you want all possible input combinations

Using SQL queries with BIND_SQL()

The BIND_SQL() operator executes SQL queries directly on your target system to generate input data. The query must conform to your backend's SQL dialect.

See Backend specific considerations for more details.

Single feature from SQL:

Multiple features from single SQL query:

Multiple features from separate SQL queries:

Using entity keysets with BIND_KEYSET()

BIND_KEYSET() is designed for entity-based feature evaluation where you select keys based on business criteria. This is particularly useful for offline analytics.

Choosing the right binding method

• BIND_VALUE(): Single value testing and simple parameterization
• BIND_TABLE(): Inlined arrays to generate input sets, testing scenarios, small-scale batch processing
• BIND_SQL(): Dynamic input generation, integration with existing data queries
• BIND_KEYSET(): Entity-based analytics, business-driven key selection

Note: In documentation code snippets, we are using BIND_SQL() to generate inlined input sets, so that the FeatureQL query can be self-contained. In real-world usage, you will most likely use apply BIND_SQL() to existing tables or BIND_KEYSET() to generate input sets.