Knowledge Base

CALL_MODEL_FUNCTION

Invoking Model Registry Functions in NQL

Overview

CALL_MODEL_FUNCTION is an NQL function that invokes prediction methods on models registered in the Narrative Model Registry. It provides a unified interface for calling any model function—including label prediction, probability distribution, and entropy calculation—directly within your NQL queries.

Syntax

CALL_MODEL_FUNCTION(model_name, version, function_name, features)

Arguments

Argument	Type	Description
model_name	string	The name of the registered model in the Narrative Model Registry (e.g., `'MY_CLASSIFIER'`).
version	string	The model version to use (e.g., `'v1'`, `'v2'`, `'v3'`).
function_name	string	The prediction function to call. See Available Functions below.
features	varies	Input features matching the model's expected schema. Can be individual columns or an array, depending on model configuration.

Return Value

All functions return a JSON-encoded string. Use TRY_PARSE_JSON() to parse the response and extract the relevant fields.

Available Functions

The following function names can be passed to CALL_MODEL_FUNCTION for classifier models:

PREDICT_LABEL

Returns the predicted class as a human-readable string label.

Response Format

{"prediction_label": "category_name"}

Behavior

Maps the model's internal numeric label encoding to original label names stored during training.
Works with binary and multi-class classifiers.
Returns NULL for null or malformed input.

PREDICT_PROBA_LABEL

Returns the full probability distribution with human-readable label names as keys.

Response Format

{"electronics": 0.72, "apparel": 0.18, "home": 0.10}

Behavior

Keys are label names; values are probabilities between 0.0 and 1.0.
Probabilities sum to 1.0.
Works with binary and multi-class classifiers.
Returns NULL for null or malformed input.

PREDICT_ENTROPY

Returns the Shannon entropy of the prediction probability distribution—a measure of prediction uncertainty.

Response Format

{"entropy": 0.8113}

Behavior

Output is a float where 0 = completely certain and log₂(n_classes) = maximum uncertainty.
Calculated as: H(X) = -Σ p(x) × log₂(p(x))
Zero probabilities are excluded to avoid undefined logarithms.
Returns NULL for null or malformed input.

Interpreting Entropy

For a 3-class classifier (max entropy ≈ 1.58):

Entropy	Interpretation	Example Distribution
0.0	Certain	1.0, 0.0, 0.0
~0.5	Confident	0.85, 0.10, 0.05
~1.0	Moderate uncertainty	0.60, 0.25, 0.15
~1.58	Maximum uncertainty	0.33, 0.33, 0.33

For multi-class classifiers, max entropy = log₂(n_classes). A 2-class classifier has max entropy of 1.0; a 10-class classifier has max entropy of ~3.32.

Examples

Example 1: Get Predicted Labels

CREATE MATERIALIZED VIEW MY_PREDICTIONS AS
SELECT
    unique_id,
    TRY_PARSE_JSON(
        CALL_MODEL_FUNCTION(
            'MY_CLASSIFIER',
            'v3',
            'PREDICT_LABEL',
            feature_array
        )
    )['prediction_label'] AS predicted_category
FROM company_data.my_dataset;

Example 2: Get Probability Distribution

CREATE MATERIALIZED VIEW MY_PROBABILITY_PREDICTIONS AS
SELECT
    unique_id,
    CAST(
        TRY_PARSE_JSON(
            CALL_MODEL_FUNCTION(
                'MY_CLASSIFIER',
                'v3',
                'PREDICT_PROBA_LABEL',
                feature_array
            )
        ) AS OBJECT
    ) AS label_probabilities
FROM company_data.my_dataset;

Example 3: Get Prediction with Uncertainty

CREATE MATERIALIZED VIEW PREDICTIONS_WITH_CONFIDENCE AS
SELECT
    unique_id,
    TRY_PARSE_JSON(
        CALL_MODEL_FUNCTION(
            'MY_CLASSIFIER',
            'v3',
            'PREDICT_LABEL',
            feature_array
        )
    )['prediction_label'] AS predicted_category,
    CAST(
        TRY_PARSE_JSON(
            CALL_MODEL_FUNCTION(
                'MY_CLASSIFIER',
                'v3',
                'PREDICT_ENTROPY',
                feature_array
            )
        )['entropy'] AS FLOAT
    ) AS uncertainty
FROM company_data.my_dataset;

Example 4: Filter for High-Confidence Predictions

CREATE MATERIALIZED VIEW HIGH_CONFIDENCE_PREDICTIONS AS
SELECT
    unique_id,
    TRY_PARSE_JSON(
        CALL_MODEL_FUNCTION(
            'MY_CLASSIFIER',
            'v3',
            'PREDICT_LABEL',
            feature_array
        )
    )['prediction_label'] AS predicted_category,
    CAST(
        TRY_PARSE_JSON(
            CALL_MODEL_FUNCTION(
                'MY_CLASSIFIER',
                'v3',
                'PREDICT_ENTROPY',
                feature_array
            )
        )['entropy'] AS FLOAT
    ) AS uncertainty
FROM company_data.my_dataset
WHERE CAST(
    TRY_PARSE_JSON(
        CALL_MODEL_FUNCTION(
            'MY_CLASSIFIER',
            'v3',
            'PREDICT_ENTROPY',
            feature_array
        )
    )['entropy'] AS FLOAT
) < 0.5;

Key Benefits

No Manual Mapping: Label encodings are stored with the model—no need to maintain separate ID-to-label mappings.
Version Alignment: Calling a specific version ensures label mappings match the model that produced them.
Uncertainty Quantification: Entropy enables flagging low-confidence predictions for human review, active learning, or quality filtering.
Consistent Interface: Same calling convention for all classifier functions.

Notes

The model must be registered in the Narrative Model Registry before CALL_MODEL_FUNCTION can invoke it.
Functions inherit access permissions from the registered model.
Always parse responses with TRY_PARSE_JSON() to handle the JSON-encoded output.
Use the NQL Editor to validate queries before execution.
Performance overhead is minimal (<10ms) compared to base predict and predict_proba functions.