Mapping to data sources

Features become useful when they connect to real data. Data source mapping is how you bring external data — whether embedded in the query or stored in a database — into FeatureQL's feature graph.

Every column-based mapping follows the same pattern: declare columns, bind key columns to inputs, and specify a source via FROM. The operator and source type change, but the shape stays the same.

The general pattern

FEATURE_NAME := <OPERATOR>(
    key_column TYPE BIND TO SOME_INPUT,
    value_column TYPE
    FROM <SOURCE>(...)
)

The BIND TO clause links a key column to an INPUT() feature. The source must return 0 or 1 row per unique input combination. FeatureQL does not check this — duplicate keys fan out, one output row per source row. Verify uniqueness in the source before mapping. Column types and the other facts a mapping assumes are Data contracts . Declare the type the column stores: a value the declared type does not fit is converted by the engine, and backends disagree ( Backend compatibility ).

You access columns of the result using the [] operator:

CUSTOMER_NAME := FEATURE_NAME[value_column]

Column-based mappings

These operators return a ROW. You pick columns from that row with [].

OperatorSourceWhat it does
INLINE_COLUMNS()CSV(), JSON()Embeds data directly in the query — useful for prototyping and tests
EXTERNAL_COLUMNS()TABLE(), SQL()Maps to columns in external database tables or queries
EXTERNAL_COLUMNS()TABLE(source[table])Maps to a table of a database or key-value source (SOURCE_DB(), SOURCE_KV()), read online

The only difference between INLINE_COLUMNS() and EXTERNAL_COLUMNS() is where the data lives. The syntax inside the parentheses is identical. TABLE(table) and SQL() use the query backend's relations; TABLE(source[table]) reads a table of a source configured for serving. That source choice does not change the FeatureQL expressions you can build on top.

Text-based mappings

These operators return a VARCHAR instead of a row. You parse the result yourself (to JSON or whatever format you need).

OperatorWhat it doesDetails
EXTERNAL_KV()Maps to a Redis keySee External Redis
EXTERNAL_HTTP()Maps to an HTTP endpointSee External HTTP

Inline data with CSV

The simplest way to get started: embed the data directly in your query. INLINE_COLUMNS() with CSV() lets you define a small dataset inline — no external tables needed.

FeatureQL
DEFINE
    CUSTOMER_ID := INPUT(BIGINT),
    DIM_CUSTOMERS := INLINE_COLUMNS(
        customer_id BIGINT BIND TO CUSTOMER_ID,
        name VARCHAR
        FROM CSV(
            customer_id,name
            101,Alice
            102,Bob
            103,Charly
            104,Daniel
            105,Elody
            106,Francis
        )
    )
RETURN
    CUSTOMER_ID,
    DIM_CUSTOMERS,
    CUSTOMER_NAME := DIM_CUSTOMERS[name]
FOR
    CUSTOMER_ID := BIND_VALUES(ARRAY[101, 102, 103, 104, 105, 106]);
Result
CUSTOMER_ID BIGINTDIM_CUSTOMERS ROW<customer_id BIGINT, name VARCHAR>CUSTOMER_NAME VARCHAR
101{customer_id: 101, name: Alice}Alice
102{customer_id: 102, name: Bob}Bob
103{customer_id: 103, name: Charly}Charly
104{customer_id: 104, name: Daniel}Daniel
105{customer_id: 105, name: Elody}Elody
106{customer_id: 106, name: Francis}Francis

Inline data with JSON

The same approach works with JSON. This is handy when your data comes from an API response or you prefer JSON syntax over CSV.

FeatureQL
DEFINE
    CUSTOMER_ID := INPUT(BIGINT),
    DIM_CUSTOMERS := INLINE_COLUMNS(
        customer_id BIGINT BIND TO CUSTOMER_ID,
        name VARCHAR
        FROM JSON(
            [
                {"customer_id": 101, "name": "Alice"},
                {"customer_id": 102, "name": "Bob"},
                {"customer_id": 103, "name": "Charly"},
                {"customer_id": 104, "name": "Daniel"},
                {"customer_id": 105, "name": "Elody"},
                {"customer_id": 106, "name": "Francis"}
            ]
        )
    )
RETURN
    CUSTOMER_ID,
    DIM_CUSTOMERS,
    CUSTOMER_NAME := DIM_CUSTOMERS[name]
FOR
    CUSTOMER_ID := BIND_VALUES(ARRAY[101, 102, 103, 104, 105, 106]);
Result
CUSTOMER_ID BIGINTDIM_CUSTOMERS ROW<customer_id BIGINT, name VARCHAR>CUSTOMER_NAME VARCHAR
101{customer_id: 101, name: Alice}Alice
102{customer_id: 102, name: Bob}Bob
103{customer_id: 103, name: Charly}Charly
104{customer_id: 104, name: Daniel}Daniel
105{customer_id: 105, name: Elody}Elody
106{customer_id: 106, name: Francis}Francis

External data with TABLE

When your data lives in a database table, use EXTERNAL_COLUMNS() with TABLE(). The example below assumes this table exists:

FeatureQL
CREATE SCHEMA IF NOT EXISTS ext;
--
DROP TABLE IF EXISTS ext.dim_customers;
--
CREATE TABLE ext.dim_customers AS
SELECT customer_id, name FROM (
    VALUES
    (101, 'Alice'),
    (102, 'Bob'),
    (103, 'Charly'),
    (104, 'Daniel'),
    (105, 'Elody'),
    (106, 'Francis')
) as t(customer_id, name);
--
SELECT CAST(COUNT(*) AS INTEGER) AS Count FROM ext.dim_customers;
Result
Count BIGINT
6

With the table in place, the mapping looks almost identical to the inline version — only the source changes from CSV(...) to TABLE(schema.table):

FeatureQL
DEFINE
    CUSTOMER_ID := INPUT(BIGINT),
    DIM_CUSTOMERS := EXTERNAL_COLUMNS(
        customer_id BIGINT BIND TO CUSTOMER_ID,
        name VARCHAR
        FROM TABLE(ext.dim_customers)
    )
RETURN
    CUSTOMER_ID,
    DIM_CUSTOMERS,
    CUSTOMER_NAME := DIM_CUSTOMERS[name]
FOR
    CUSTOMER_ID := BIND_VALUES(ARRAY[101, 102, 103, 104, 105, 106]);
Result
CUSTOMER_ID BIGINTDIM_CUSTOMERS ROW<customer_id BIGINT, name VARCHAR>CUSTOMER_NAME VARCHAR
101{customer_id: 101, name: Alice}Alice
102{customer_id: 102, name: Bob}Bob
103{customer_id: 103, name: Charly}Charly
104{customer_id: 104, name: Daniel}Daniel
105{customer_id: 105, name: Elody}Elody
106{customer_id: 106, name: Francis}Francis

External data with SQL

When you need to transform or filter data before mapping, use SQL() instead of TABLE(). This lets you write a SQL subquery as the source:

FeatureQL
DEFINE
    CUSTOMER_ID := INPUT(BIGINT),
    DIM_CUSTOMERS := EXTERNAL_COLUMNS(
        customer_id BIGINT BIND TO CUSTOMER_ID,
        name VARCHAR
        FROM SQL(SELECT customer_id, name FROM ext.dim_customers)
    )
RETURN
    CUSTOMER_ID,
    DIM_CUSTOMERS,
    CUSTOMER_NAME := DIM_CUSTOMERS[name]
FOR
    CUSTOMER_ID := BIND_VALUES(ARRAY[101, 102, 103, 104, 105, 106]);
Result
CUSTOMER_ID BIGINTDIM_CUSTOMERS ROW<customer_id BIGINT, name VARCHAR>CUSTOMER_NAME VARCHAR
101{customer_id: 101, name: Alice}Alice
102{customer_id: 102, name: Bob}Bob
103{customer_id: 103, name: Charly}Charly
104{customer_id: 104, name: Daniel}Daniel
105{customer_id: 105, name: Elody}Elody
106{customer_id: 106, name: Francis}Francis

Multiple keys and source forms

A mapping can bind more than one source column to inputs. This example binds both an entity key and a date partition, then shows that equivalent SQL, CSV, and JSON sources produce the same mapped rows:

FeatureQL
DEFINE
    CUSTOMERS := ENTITY(),
    CUSTOMER_ID := INPUT(BIGINT#CUSTOMERS),
    DYNAMIC_PARTITION := INPUT(VARCHAR),
    SOURCE_CUSTOMER_BASE := EXTERNAL_COLUMNS(
        customer_id BIGINT#CUSTOMERS BIND TO CUSTOMER_ID,
        ds VARCHAR BIND TO DYNAMIC_PARTITION,
        attribute1 VARCHAR
        FROM SQL(
            SELECT * FROM (VALUES
                (1, '2025-01-05', '1-5'),
                (2, '2025-01-05', '2-5'),
                (3, '2025-01-05', '3-5'),
                (1, '2025-01-06', '1-6'),
                (2, '2025-01-06', '2-6'),
                (3, '2025-01-06', '3-6')
            ) AS t(customer_id, ds, attribute1)
        )
    ),
    -- ** SQL source version (same mapping as SOURCE_CUSTOMER_BASE) **
    SOURCE_CUSTOMER_SQL := EXTERNAL_COLUMNS(
        customer_id BIGINT#CUSTOMERS BIND TO CUSTOMER_ID,
        ds VARCHAR BIND TO DYNAMIC_PARTITION,
        attribute1 VARCHAR
        FROM SQL(
            SELECT * FROM (VALUES
                (1, '2025-01-05', '1-5'),
                (2, '2025-01-05', '2-5'),
                (3, '2025-01-05', '3-5'),
                (1, '2025-01-06', '1-6'),
                (2, '2025-01-06', '2-6'),
                (3, '2025-01-06', '3-6')
            ) AS t(customer_id, ds, attribute1)
        )
    ),
    -- ** CSV source version (headers required) **
    SOURCE_CUSTOMER_CSV := INLINE_COLUMNS(
        customer_id BIGINT#CUSTOMERS BIND TO CUSTOMER_ID,
        ds VARCHAR BIND TO DYNAMIC_PARTITION,
        attribute1 VARCHAR
        FROM CSV(
  			customer_id,ds,attribute1
			1,2025-01-05,1-5
			2,2025-01-05,2-5
			3,2025-01-05,3-5
			1,2025-01-06,1-6
			2,2025-01-06,2-6
			3,2025-01-06,3-6
        )
    ),
    -- ** JSON source version (array of objects) **
    SOURCE_CUSTOMER_JSON := INLINE_COLUMNS(
        customer_id BIGINT#CUSTOMERS BIND TO CUSTOMER_ID,
        ds VARCHAR BIND TO DYNAMIC_PARTITION,
        attribute1 VARCHAR
        FROM JSON([
            {"customer_id": 1, "ds": "2025-01-05", "attribute1": "1-5"},
            {"customer_id": 2, "ds": "2025-01-05", "attribute1": "2-5"},
            {"customer_id": 3, "ds": "2025-01-05", "attribute1": "3-5"},
            {"customer_id": 1, "ds": "2025-01-06", "attribute1": "1-6"},
            {"customer_id": 2, "ds": "2025-01-06", "attribute1": "2-6"},
            {"customer_id": 3, "ds": "2025-01-06", "attribute1": "3-6"}
        ])
    ),
RETURN
    (CUSTOMER_ID, DYNAMIC_PARTITION) := BIND_VALUES(ARRAY[
        ROW(1, '2025-01-05'),
        ROW(2, '2025-01-05'),
        ROW(3, '2025-01-05'),
        ROW(1, '2025-01-06')
    ]),
    ALL(
        SOURCE_CUSTOMER_BASE=SOURCE_CUSTOMER_SQL,
        SOURCE_CUSTOMER_BASE=SOURCE_CUSTOMER_CSV,
        SOURCE_CUSTOMER_BASE=SOURCE_CUSTOMER_JSON
    ) as all_are_equal,
    SOURCE_CUSTOMER_BASE,
    SOURCE_CUSTOMER_SQL,
    SOURCE_CUSTOMER_CSV,
    SOURCE_CUSTOMER_JSON
;
Result
CUSTOMER_ID BIGINT#CUSTOMERSDYNAMIC_PARTITION VARCHARALL_ARE_EQUAL BOOLEANSOURCE_CUSTOMER_BASE ROW<customer_id BIGINT#CUSTOMERS, ds VARCHAR, attribute1 VARCHAR>SOURCE_CUSTOMER_SQL ROW<customer_id BIGINT#CUSTOMERS, ds VARCHAR, attribute1 VARCHAR>SOURCE_CUSTOMER_CSV ROW<customer_id BIGINT#CUSTOMERS, ds VARCHAR, attribute1 VARCHAR>SOURCE_CUSTOMER_JSON ROW<customer_id BIGINT#CUSTOMERS, ds VARCHAR, attribute1 VARCHAR>
12025-01-05true{customer_id: 1, ds: 2025-01-05, attribute1: 1-5}{customer_id: 1, ds: 2025-01-05, attribute1: 1-5}{customer_id: 1, ds: 2025-01-05, attribute1: 1-5}{customer_id: 1, ds: 2025-01-05, attribute1: 1-5}
12025-01-06true{customer_id: 1, ds: 2025-01-06, attribute1: 1-6}{customer_id: 1, ds: 2025-01-06, attribute1: 1-6}{customer_id: 1, ds: 2025-01-06, attribute1: 1-6}{customer_id: 1, ds: 2025-01-06, attribute1: 1-6}
22025-01-05true{customer_id: 2, ds: 2025-01-05, attribute1: 2-5}{customer_id: 2, ds: 2025-01-05, attribute1: 2-5}{customer_id: 2, ds: 2025-01-05, attribute1: 2-5}{customer_id: 2, ds: 2025-01-05, attribute1: 2-5}
32025-01-05true{customer_id: 3, ds: 2025-01-05, attribute1: 3-5}{customer_id: 3, ds: 2025-01-05, attribute1: 3-5}{customer_id: 3, ds: 2025-01-05, attribute1: 3-5}{customer_id: 3, ds: 2025-01-05, attribute1: 3-5}

DYNAMIC_PARTITION is part of the source lookup key. This pattern works for any evaluation profile when a source is partitioned by date, tenant, region, or another request input.

A source's table

TABLE(source[table]) has the same column-mapping shape as TABLE(table): the source feature in front of the brackets says the table lives in an operational database rather than in the query backend. It is common in serving graphs that fetch operational data directly:

DEFINE
    PG := SOURCE_DB('postgresql://app-db:5432/crm' WITH (tables = ARRAY('v_dim_customers'))),
    CUSTOMER_ID := INPUT(BIGINT),
    DIM_CUSTOMERS := EXTERNAL_COLUMNS(
        customer_id BIGINT BIND TO CUSTOMER_ID,
        name VARCHAR
        FROM TABLE(PG[v_dim_customers])
    )
RETURN
    CUSTOMER_ID,
    DIM_CUSTOMERS,
    CUSTOMER_NAME := DIM_CUSTOMERS[name]
FOR
    CUSTOMER_ID := BIND_VALUES(ARRAY(101, 102, 103, 104, 105, 106));

For more on real-time connectors (key-value stores, databases, HTTP), see Real-time serving context .