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:

Redis
HMGET serving_slt:customer_hash:1 customer_id last_order_id
Result
CUSTOMER_ID BIGINTLAST_ORDER_ID BIGINT
1101

Creating a Redis source

Before querying Redis, create a persistent connection with SOURCE_KV():

FeatureQL
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:*']
        )
    );
Result
feature_name VARCHARstatus VARCHARmessage VARCHAR
FM.TUTORIALS.EXTERNAL.REDIS_SRCCREATEDFeature 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:

FeatureQL
REFRESH SERVING;
Result
FEATURE VARCHARKIND VARCHARSTATUS VARCHARMESSAGE VARCHARSINCE VARCHAR
FM.TUTORIALS.EXTERNAL.REDIS_SRCSOURCE_KVLOADED

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:

FeatureQL
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]
;
Result
CUSTOMER_ID BIGINTLAST_ORDER_ID BIGINT
1101

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:

FeatureQL
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
    )
;
Result
CUSTOMER_ID BIGINTLAST_ORDER_ID VARCHAR
1101

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:

FeatureQL
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
    )
;
Result
CUSTOMER_ID BIGINTLAST_ORDER_ID VARCHAR
1202

Reading options

EXTERNAL_KV() takes options in a WITH (...) clause after the source:

OptionValuesEffect
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:

FeatureQL
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)
    )
;
Result
CUSTOMER_ID BIGINTTIER VARCHARVISITS BIGINTEMBEDDING ARRAY(DOUBLE)
1gold42[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}'
null

PURCHASES is an array of rows like any other. The purchases of the 30 days before REQ_TS are a filter on time_create:

FeatureQL
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'])
;
Result
CUSTOMER_ID BIGINTN_30D BIGINTTOTAL_30D DOUBLEORDER_IDS ARRAY(BIGINT)
1237.5[12, 13]
20NULL[]

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 ON field: a TIMESTAMP field 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: FIELD is refused with INDEXED 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:

FeatureQL
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'])
;
Result
CUSTOMER_ID BIGINTAT TIMESTAMPTIER VARCHAR
12026-01-15 00:00:00silver
12026-02-05 00:00:00gold

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.

TIP

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:

FeatureQL
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]
;
Result
REDIS_KEY VARCHARCUSTOMER_ID BIGINTLAST_ORDER_ID BIGINT
serving_slt:customer_hash:11101

Or join on field values within the hashes:

FeatureQL
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]
;
Result
CUSTOMER_ID BIGINTLAST_ORDER_ID BIGINT
1101

Performance

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'
)