Key-value sources
SOURCE_KV() connects FeatureQL to a key-value store, Redis today, and EXTERNAL_KV() reads its values by key for low-latency feature retrieval. Redis is typically the fastest option for real-time serving — ideal for cached profiles, feature flags, and precomputed aggregates.
Inspect a hash fixture directly
The Redis SLT executor can read selected hash fields with HMGET and assert them as typed query columns:
HMGET serving_slt:customer_hash:1 customer_id last_order_id| CUSTOMER_ID BIGINT | LAST_ORDER_ID BIGINT |
|---|---|
| 1 | 101 |
Creating a Redis source
Before querying Redis, create a persistent connection with SOURCE_KV():
CREATE OR REPLACE FEATURE FM.TUTORIALS.EXTERNAL.REDIS_SRC AS
SOURCE_KV(
'redis://host.docker.internal:26379'
WITH (
timeout='500ms',
key_patterns=ARRAY['serving_slt:customer_hash:*']
)
);| feature_name VARCHAR | status VARCHAR | message VARCHAR |
|---|---|---|
| FM.TUTORIALS.EXTERNAL.REDIS_SRC | CREATED | Feature created as not exists |
The connection string follows the standard redis://host:port format. The timeout parameter controls both connection and operation timeouts. key_patterns is an optimization hint that tells FeatureMesh which keys this source will access.
The serving engine picks up new definitions at its next registry sync (every 30 seconds). To use the source right away, refresh the serving engine:
REFRESH SERVING;| FEATURE VARCHAR | KIND VARCHAR | STATUS VARCHAR | MESSAGE VARCHAR | SINCE VARCHAR |
|---|---|---|---|---|
| FM.TUTORIALS.EXTERNAL.REDIS_SRC | SOURCE_KV | LOADED |
REFRESH SERVING runs that sync at once and waits for connector reconciliation to finish. Afterwards the engine holds exactly the sources and prepared statements of the registry. A source that cannot connect is listed with status ERROR and the error in MESSAGE; SHOW SERVING STATUS LIKE 'FM.TUTORIALS.EXTERNAL.%' shows the same at any time (see Prepared statements ).
JSON key retrieval
The simplest pattern fetches a Redis key containing a JSON object, then parses it into a typed row:
DEFINE
CUSTOMER_ID := INPUT(BIGINT),
REDIS_KEY := 'serving_slt:customer:' || CUSTOMER_ID::VARCHAR,
CUSTOMER_DETAILS_JSON := EXTERNAL_KV(KEY REDIS_KEY FROM FM.TUTORIALS.EXTERNAL.REDIS_SRC),
CUSTOMER_DETAILS := JSON_PARSE_AS(
CUSTOMER_DETAILS_JSON AS ROW(customer_id BIGINT, last_order_id BIGINT)
),
RETURN
CUSTOMER_ID := BIND_VALUE(1),
LAST_ORDER_ID := CUSTOMER_DETAILS[last_order_id]
;| CUSTOMER_ID BIGINT | LAST_ORDER_ID BIGINT |
|---|---|
| 1 | 101 |
The key expression 'customer:' || CUSTOMER_ID::VARCHAR builds a dynamic key per input. EXTERNAL_KV(KEY ...) returns the raw JSON string, and JSON_PARSE_AS() converts it to a structured row with type safety. From there, bracket notation extracts individual fields like CUSTOMER_DETAILS[last_order_id].
This pattern works well for complex objects — customer profiles, product catalogs, configuration records.
Hash field access
When your data lives in Redis hashes, you can skip JSON parsing entirely and fetch individual fields directly:
DEFINE
CUSTOMER_ID := INPUT(BIGINT),
REDIS_KEY := 'serving_slt:customer_hash:' || CUSTOMER_ID::VARCHAR,
RETURN
CUSTOMER_ID := BIND_VALUE(1),
LAST_ORDER_ID := EXTERNAL_KV(
KEY REDIS_KEY
FIELD 'last_order_id'
FROM FM.TUTORIALS.EXTERNAL.REDIS_SRC
)
;| CUSTOMER_ID BIGINT | LAST_ORDER_ID VARCHAR |
|---|---|
| 1 | 101 |
The FIELD keyword tells FeatureQL to issue an HGET instead of a GET. This is more efficient than fetching the entire object when you only need one or two fields — less data over the wire, no parsing overhead.
Serving reads the current Redis value rather than a snapshot captured at refresh time. After changing the hash field, the same query immediately returns the new value:
DEFINE
CUSTOMER_ID := INPUT(BIGINT),
REDIS_KEY := 'serving_slt:customer_hash:' || CUSTOMER_ID::VARCHAR,
RETURN
CUSTOMER_ID := BIND_VALUE(1),
LAST_ORDER_ID := EXTERNAL_KV(
KEY REDIS_KEY
FIELD 'last_order_id'
FROM FM.TUTORIALS.EXTERNAL.REDIS_SRC
)
;| CUSTOMER_ID BIGINT | LAST_ORDER_ID VARCHAR |
|---|---|
| 1 | 202 |
Reading options
EXTERNAL_KV() takes options in a WITH (...) clause after the source:
| Option | Values | Effect |
|---|---|---|
FORMAT | 'text' (default), 'json', 'msgpack', 'float32' | How the value is stored. Binary formats are decoded to JSON text |
COMPRESSION | 'none' (default), 'lz4' | An LZ4 block, its size first as a little-endian 32-bit integer, decompressed before FORMAT |
Without a type, EXTERNAL_KV() returns VARCHAR. Declare the type of the value with AS after the source, and the value (JSON text, after FORMAT) comes back in that type, as JSON_PARSE_AS() would return it:
PROFILE := EXTERNAL_KV(
KEY 'profile:' || CUSTOMER_ID::VARCHAR
FROM REDIS_SRC
AS ROW<tier VARCHAR, visits BIGINT>
WITH (FORMAT = 'msgpack')
)
Binary values
Writers that serialize for size or speed store MessagePack objects or raw float vectors (embeddings) rather than JSON. FORMAT decodes them to JSON text, so the rest of the feature is the same as for a JSON value:
DEFINE
CUSTOMER_ID := INPUT(BIGINT),
PROFILE := JSON_PARSE_AS(
EXTERNAL_KV(
KEY 'serving_slt:profile_mp:' || CUSTOMER_ID::VARCHAR
FROM FM.TUTORIALS.EXTERNAL.REDIS_SRC
WITH (FORMAT = 'msgpack')
) AS ROW(tier VARCHAR, visits BIGINT)
),
RETURN
CUSTOMER_ID := BIND_VALUE(1),
TIER := PROFILE[tier],
VISITS := PROFILE[visits],
EMBEDDING := JSON_PARSE_AS(
EXTERNAL_KV(
KEY 'serving_slt:embedding:' || CUSTOMER_ID::VARCHAR
FROM FM.TUTORIALS.EXTERNAL.REDIS_SRC
WITH (FORMAT = 'float32')
) AS ARRAY(DOUBLE)
)
;| CUSTOMER_ID BIGINT | TIER VARCHAR | VISITS BIGINT | EMBEDDING ARRAY(DOUBLE) |
|---|---|---|---|
| 1 | gold | 42 | [0.5, -1.25, 2.0] |
'msgpack'decodes any MessagePack value: a map becomes a JSON object, an array a JSON array.'float32'reads the value as consecutive little-endian 32-bit floats and returns a JSON array of numbers. An embedding of 768 dimensions is 3 KB in Redis instead of about 8 KB of JSON text.
Add COMPRESSION = 'lz4' when the writer compresses its values with LZ4 (block format, prefixed with the uncompressed size).
Histories in sorted sets
A sorted set holds members ordered by a score. With the score set to a time, one sorted set per key is a history: the same array of rows that historical functions read. Declare it with AS ARRAY<ROW<...>> INDEXED ON field: each member is a row, and its score is field. Here, customer 1 has three purchases, scored on 2026-01-01, 2026-01-20 and 2026-02-03:
ZADD serving_slt:purchases:1 1767225600 '{"order_id":11,"amount":40.0}'
1768867200 '{"order_id":12,"amount":15.5}'
1770076800 '{"order_id":13,"amount":22.0}' PURCHASES is an array of rows like any other. The purchases of the 30 days before REQ_TS are a filter on time_create:
DEFINE
CUSTOMER_ID := INPUT(BIGINT),
REQ_TS := INPUT(TIMESTAMP),
PURCHASES := EXTERNAL_KV(
KEY 'serving_slt:purchases:' || CUSTOMER_ID::VARCHAR
FROM FM.TUTORIALS.EXTERNAL.REDIS_SRC
AS ARRAY(ROW(time_create TIMESTAMP, order_id BIGINT, amount DOUBLE)) INDEXED ON time_create
WITH (FORMAT = 'json')
),
LAST_30D := PURCHASES.CARRY(REQ_TS AS req_ts).TRANSFORM(
RETURN * WHERE time_create > req_ts - INTERVAL '30 days' AND time_create <= req_ts
),
RETURN
CUSTOMER_ID,
N_30D := ARRAY_COUNT(LAST_30D),
TOTAL_30D := ARRAY_SUM(LAST_30D[amount]),
ORDER_IDS := LAST_30D[order_id]
FOR CROSS
CUSTOMER_ID := BIND_VALUES(ARRAY[1, 2]),
REQ_TS := BIND_VALUES(ARRAY[TIMESTAMP '2026-02-05 00:00:00'])
;| CUSTOMER_ID BIGINT | N_30D BIGINT | TOTAL_30D DOUBLE | ORDER_IDS ARRAY(BIGINT) |
|---|---|---|---|
| 1 | 2 | 37.5 | [12, 13] |
| 2 | 0 | NULL | [] |
With REQ_TS on 2026-02-05, the window starts on 2026-01-06: purchases 12 and 13 are in it, purchase 11 is not.
- The rows come in score order. The score fills the
INDEXED ONfield: aTIMESTAMPfield is scored in Unix seconds (UTC), a number field takes the score as is. - A member decoded to a JSON object (per
FORMAT) fills the other fields by name. Any other member, such as text, fills the one other field of the row. - A missing key reads as an empty array, so customer 2 counts 0 purchases.
- A sorted set has no fields:
FIELDis refused withINDEXED ON.
A history of one value has the shape ROW_AT_TIME() reads: the score is time_update, the member is value. ROW_AT_TIME() on it reads only the last member at or before the point in time from Redis (ZRANGE ... BYSCORE REV LIMIT 0 1), however long the history:
DEFINE
CUSTOMER_ID := INPUT(BIGINT),
AT := INPUT(TIMESTAMP),
TIER_HISTORY := EXTERNAL_KV(
KEY 'serving_slt:tier_history:' || CUSTOMER_ID::VARCHAR
FROM FM.TUTORIALS.EXTERNAL.REDIS_SRC
AS ARRAY(ROW(time_update TIMESTAMP, value VARCHAR)) INDEXED ON time_update
),
RETURN
CUSTOMER_ID,
AT,
TIER := ROW_AT_TIME(TIER_HISTORY, AT)[value]
FOR CROSS
CUSTOMER_ID := BIND_VALUES(ARRAY[1]),
AT := BIND_VALUES(ARRAY[TIMESTAMP '2026-01-15 00:00:00', TIMESTAMP '2026-02-05 00:00:00'])
;| CUSTOMER_ID BIGINT | AT TIMESTAMP | TIER VARCHAR |
|---|---|---|
| 1 | 2026-01-15 00:00:00 | silver |
| 1 | 2026-02-05 00:00:00 | gold |
ROWS_AT_TIME() on a history indexed on time_create reads only the members created up to its point in time.
A TRANSFORM() whose WHERE compares the INDEXED ON field reads only the members between those bounds, like the window above: from REQ_TS - INTERVAL '30 days' to REQ_TS. A bound can be a literal, a carried value, or either of them plus or minus an INTERVAL. Other conditions still apply to the rows read, and any other use of the array reads the whole set.
In a prepared statement, bind REQ_TS := NOW() and the window ends at the time of each call. The writer side is up to you: ZADD each event as it happens, and trim old members with ZREMRANGEBYSCORE so the set does not grow forever.
Redis keeps one copy of each member: adding a member that is already there only moves its score. Two identical purchases, or a status that comes back to an earlier value, collapse into one row. Put something unique in each member, an order ID or an event ID, when that matters.
For history kept in a database instead, see Aggregations over a key's history .
Table-style access with EXTERNAL_COLUMNS()
For more advanced patterns, EXTERNAL_COLUMNS(... FROM TABLE(KV[key_pattern])) treats Redis keys as rows in a virtual table. This lets you join on the key itself:
DEFINE
REDIS_KEY := INPUT(VARCHAR),
REDIS_VIEW := EXTERNAL_COLUMNS(
key VARCHAR BIND TO REDIS_KEY,
customer_id BIGINT,
last_order_id BIGINT
FROM TABLE(FM.TUTORIALS.EXTERNAL.REDIS_SRC[serving_slt:customer_hash:*])
),
RETURN
REDIS_KEY := BIND_VALUE('serving_slt:customer_hash:1'),
CUSTOMER_ID := REDIS_VIEW[customer_id],
LAST_ORDER_ID := REDIS_VIEW[last_order_id]
;| REDIS_KEY VARCHAR | CUSTOMER_ID BIGINT | LAST_ORDER_ID BIGINT |
|---|---|---|
| serving_slt:customer_hash:1 | 1 | 101 |
Or join on field values within the hashes:
DEFINE
CUSTOMER_ID := INPUT(BIGINT),
REDIS_VIEW := EXTERNAL_COLUMNS(
key VARCHAR,
customer_id BIGINT BIND TO CUSTOMER_ID,
last_order_id BIGINT
FROM TABLE(FM.TUTORIALS.EXTERNAL.REDIS_SRC[serving_slt:customer_hash:*])
),
RETURN
CUSTOMER_ID := BIND_VALUE(1),
LAST_ORDER_ID := REDIS_VIEW[last_order_id]
;| CUSTOMER_ID BIGINT | LAST_ORDER_ID BIGINT |
|---|---|
| 1 | 101 |
Table-style access scans all keys matching the pattern. Reserve this for small datasets — it is significantly slower than direct key or hash field lookups.
Error handling
Redis operations return NULL when they fail — whether from network issues, missing keys, timeouts, or JSON parsing errors. Use COALESCE() to provide fallback values:
CUSTOMER_TIER := COALESCE(
EXTERNAL_KV(KEY 'customer_hash:' || CUSTOMER_ID::VARCHAR FIELD 'tier' FROM REDIS_SRC),
'standard'
)