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 [].
| Operator | Source | What 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).
| Operator | What it does | Details |
|---|---|---|
EXTERNAL_KV() | Maps to a Redis key | See External Redis |
EXTERNAL_HTTP() | Maps to an HTTP endpoint | See 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.
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]);| CUSTOMER_ID BIGINT | DIM_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.
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]);| CUSTOMER_ID BIGINT | DIM_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:
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;| 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):
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]);| CUSTOMER_ID BIGINT | DIM_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:
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]);| CUSTOMER_ID BIGINT | DIM_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:
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
;| CUSTOMER_ID BIGINT#CUSTOMERS | DYNAMIC_PARTITION VARCHAR | ALL_ARE_EQUAL BOOLEAN | SOURCE_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> |
|---|---|---|---|---|---|---|
| 1 | 2025-01-05 | true | {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} |
| 1 | 2025-01-06 | true | {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} |
| 2 | 2025-01-05 | true | {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} |
| 3 | 2025-01-05 | true | {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 .