Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.narrative.io/llms.txt

Use this file to discover all available pages before exploring further.

​
AI and ML functions

These functions run AI and machine learning operations directly within your query, enabling LLM inference, custom model predictions, and AI-powered data enrichment at scale.
AI and ML functions are currently available on Snowflake data planes only. They are not supported on AWS-hosted data planes.

​
AI_COMPLETE

Sends a prompt to a large language model and returns the response as a JSON string. Use AI_COMPLETE to enrich, classify, or extract structured data from text columns without leaving NQL. Syntax: 
AI_COMPLETE(model, prompt, model_parameters, response_format, show_details)
Parameters:
ParameterTypeDescription
modelSTRINGThe model identifier to use (e.g., 'openai-gpt-5'). Available models depend on your Snowflake Cortex configuration.
promptcolumn referenceA column containing the prompt text. Must be a column reference—string literals are not supported. Build prompts in a CTE or subquery first.
model_parametersSTRINGA JSON string of model configuration options. Use '{}' for defaults. Supports keys like temperature and max_tokens.
response_formatSTRINGA JSON string defining the expected output structure. Contains a type field and a schema field with a standard JSON Schema definition.
show_detailsBOOLEANWhen TRUE, the response includes a structured_output array with the full typed response. When FALSE, returns a plain string response.
Returns: STRING — A JSON string containing the model’s response. When show_details is TRUE, the returned JSON has this structure: 
{
  "structured_output": [
    {
      "raw_message": {
        // Fields matching your response_format schema
      },
      "type": "json"
    }
  ]
}
Examples: Classify a text column using structured output: 
SELECT
  AI_COMPLETE(
    'openai-gpt-5',
    company_data."my_dataset".prompt_text,
    '{}',
    '{"type": "json", "schema": {"type": "object", "properties": {"category": {"type": "string"}, "confidence": {"type": "number"}}, "required": ["category", "confidence"], "additionalProperties": false}}',
    TRUE
  ) AS result
FROM company_data."my_dataset"
Parse the structured output into individual columns: 
SELECT
  CAST(
    PARSE_JSON(result)['structured_output'][0]['raw_message']['category'] AS STRING
  ) AS category,
  CAST(
    PARSE_JSON(result)['structured_output'][0]['raw_message']['confidence'] AS DOUBLE
  ) AS confidence
FROM company_data."enriched_results"
Use model parameters to control response behavior: 
SELECT
  AI_COMPLETE(
    'openai-gpt-5',
    company_data."my_dataset".prompt_text,
    '{"temperature": 0, "max_tokens": 4096}',
    '{"type": "json", "schema": {"type": "object", "properties": {"summary": {"type": "string"}}, "required": ["summary"], "additionalProperties": false}}',
    TRUE
  ) AS result
FROM company_data."my_dataset"
The prompt parameter must be a column reference. To build dynamic prompts from multiple columns, use a CTE to concatenate values into a single prompt column, then pass that column to AI_COMPLETE. See the data enrichment cookbook for a complete example.
Because AI_COMPLETE runs within your Snowflake data plane, your data never leaves your infrastructure. No external API calls are made to model providers. See Data Privacy in Model Inference for details.
Setup requirements: Before AI_COMPLETE can run, the customer’s Snowflake account must grant the Cortex role to the Narrative application and enable cross-region model access. See the data enrichment cookbook for the exact GRANT statements. Common errors:
ErrorCauseResolution
Insufficient privileges to operate on database role 'CORTEX_USER'The Narrative application has not been granted snowflake.cortex_user.Run the grant from the cookbook setup.
Function AI_COMPLETE does not existQuery was run against a non-Snowflake data plane.AI_COMPLETE is Snowflake-only. Use a Model Inference job on other data planes.
Model '<id>' not available in this regionCross-region Cortex access is not enabled.Set CORTEX_ENABLED_CROSS_REGION = 'ANY_REGION' on the account (see cookbook setup).
When to use AI_COMPLETE vs a Model Inference job:
Use AI_COMPLETE when…Use a Model Inference job when…
You need row-level inference inline in NQLYou are calling inference from the SDK or API, not a query
Your data plane is SnowflakeYou need to run on a non-Snowflake data plane
You want to materialize enriched results as a view or tableYou need a single on-demand completion (not a batch)
Related: Model Inference Overview, Structured Output, Data Enrichment Cookbook

​
CALL_MODEL_FUNCTION

Invokes a function on a custom model registered in the Snowflake ML Model Registry. Use CALL_MODEL_FUNCTION to run predictions, embeddings, or other operations from your own trained models directly within NQL. Syntax: 
CALL_MODEL_FUNCTION(model_name, model_version, model_function [, arg0, arg1, ...])
Parameters:
ParameterTypeDescription
model_nameSTRINGThe model identifier, optionally schema-qualified. Use 'schema.model_name' or '"schema"."model_name"' to specify a schema. If no schema is provided, defaults to the MODELS schema.
model_versionSTRING or NULLThe model version to invoke. Pass NULL to use the default version.
model_functionSTRINGThe name of the function to call on the model (e.g., 'PREDICT').
arg0, arg1, ...anyZero or more arguments passed to the model function. Typically column references containing the input data.
Returns: STRING — A JSON string containing the model function’s output. The return format depends on the model’s function signature. Custom models typically return JSON objects: 
{"OUTPUT": "predicted_value"}
Examples: Call a custom model’s predict function with a single input column: 
SELECT
  CALL_MODEL_FUNCTION(
    'my_schema.product_classifier',
    'v2',
    'PREDICT',
    company_data."products".product_name
  ) AS prediction
FROM company_data."products"
Use the default model version by passing NULL: 
SELECT
  CALL_MODEL_FUNCTION(
    'sentiment_model',
    NULL,
    'PREDICT',
    company_data."reviews".review_text
  ) AS sentiment
FROM company_data."reviews"
Parse the model output into typed columns: 
WITH predictions AS (
  SELECT
    company_data."products".product_id,
    CALL_MODEL_FUNCTION(
      'my_schema.product_classifier',
      'v2',
      'PREDICT',
      company_data."products".product_name
    ) AS raw_prediction
  FROM company_data."products"
)
SELECT
  predictions.product_id,
  CAST(PARSE_JSON(predictions.raw_prediction)['OUTPUT'] AS STRING) AS predicted_category
FROM predictions
Compare outputs across model versions: 
SELECT
  company_data."products".product_id,
  CALL_MODEL_FUNCTION(
    'my_schema.classifier',
    'v1',
    'PREDICT',
    company_data."products".product_name
  ) AS v1_prediction,
  CALL_MODEL_FUNCTION(
    'my_schema.classifier',
    'v2',
    'PREDICT',
    company_data."products".product_name
  ) AS v2_prediction
FROM company_data."products"
When no schema is specified in the model name, the function defaults to the MODELS schema. To reference a model in a different schema, use dot notation: 'my_schema.model_name' or quoted identifiers: '"MY_SCHEMA"."MODEL_NAME"'.
Related: AI_COMPLETE, Model Inference Overview

​
Related content

Data Enrichment with AI

Complete cookbook for enriching data using AI_COMPLETE

Model Inference

How AI inference works within your data plane

Structured Output

JSON Schema for predictable AI responses

All Functions

Browse all function categories