Mapping external data

That is the link with the outside world, where you map your features to values of columns persisted in external databases.

Operator	Purpose / Use Case	Context
`EXTERNAL_COLUMNS()`	Map features to columns in external databases	Analytics
`EXTERNAL_SQL()`	Map features to ORC files in external databases	Analytics
`EXTERNAL_VIEW()`	Map features to views in external databases	Realtime serving
`EXTERNAL_JDBC()`	Map features to JDBC databases	Realtime serving
`EXTERNAL_REDIS()`	Map features to Redis databases	Realtime serving
`EXTERNAL_HTTP()`	Map features to HTTP endpoints	Realtime serving

In terms of modeling, it is absolutely crucial that the result cardinality is 0 or 1 row per unique input combination.

Parameters include a way to explicitly type the columns, that become a field in the resulting feature of type row. You can access the columns of the row using the [] operator.

Example for analytics

In our ecommerce example, we have a table customers that we want to map to features.

You can either use the EXTERNAL_COLUMNS function:

WITH
    CUSTOMERS := ENTITY(),
    CUSTOMER_ID := INPUT(BIGINT#CUSTOMERS),
    CUSTOMER_DATA := EXTERNAL_COLUMNS(
        customer_id BIGINT#CUSTOMERS BOUND TO CUSTOMER_ID,
        name VARCHAR,
        email VARCHAR
        FROM customers
    ),
    CUSTOMER_NAME := CUSTOMER_DATA[name],
    CUSTOMER_EMAIL := CUSTOMER_DATA[email]
SELECT
    CUSTOMER_ID := BIND_VALUES(ARRAY[1, 2]),
    CUSTOMER_NAME,
    CUSTOMER_EMAIL
;

sql

Or the EXTERNAL_SQL function:

WITH
    CUSTOMERS := ENTITY(),
    CUSTOMER_ID := INPUT(BIGINT#CUSTOMERS),
    CUSTOMER_DATA := EXTERNAL_SQL(
        `SELECT name, email FROM customers``
        ON `SELF.customer_id = %CUSTOMER_ID`,
        AS ROW(
            name VARCHAR,
            email VARCHAR
        )
    ),
    CUSTOMER_NAME := CUSTOMER_DATA[name],
    CUSTOMER_EMAIL := CUSTOMER_DATA[email]

sql

EXTERNAL_SQL() is more powerful but requires you to write the SQL query in the target database dialect to map the columns to the features.

Suggest changes to this page

Last update at: 2025/12/05 16:03:14

On this page

Example for analytics