Skip to main content

External LLM Integration

Snowflake's External Access Integration framework allows UDFs and stored procedures to call external APIs — including LLM providers like OpenAI and Anthropic — directly from SQL. This enables scenarios where Cortex built-in models do not meet specific requirements.

When to Use External LLMs vs Cortex​

FactorCortex Built-InExternal LLM
SetupZero configurationNetwork rules, secrets, integrations required
Data residencyData stays in SnowflakeData sent to external API
Model selectionSnowflake-supported modelsAny API-accessible model
CostSnowflake credit-based pricingExternal API billing
LatencyLow (in-platform)Higher (network round-trip)
Fine-tuningCortex Fine-TuningProvider's fine-tuning service

Use external LLMs when you need a specific model not available in Cortex, must match an existing provider integration, or require capabilities not yet offered by Cortex.

Architecture Overview​

External API calls from Snowflake require three objects:

  1. Network Rule — specifies the allowed external endpoint.
  2. Secret — stores the API key securely.
  3. External Access Integration — binds the network rule and secret into a reusable policy.

Step 1: Create a Network Rule​

CREATE OR REPLACE NETWORK RULE OPENAI_NETWORK_RULE
MODE = EGRESS
TYPE = HOST_PORT
VALUE_LIST = ('api.openai.com:443');

Step 2: Store the API Key as a Secret​

CREATE OR REPLACE SECRET OPENAI_API_KEY
TYPE = GENERIC_STRING
SECRET_STRING = 'sk-...your-key-here...';

Never hard-code API keys in UDF source code. The secret object encrypts the value and restricts access through RBAC.

Step 3: Create the External Access Integration​

CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION OPENAI_INTEGRATION
ALLOWED_NETWORK_RULES = (OPENAI_NETWORK_RULE)
ALLOWED_AUTHENTICATION_SECRETS = (OPENAI_API_KEY)
ENABLED = TRUE;

Step 4: Create a UDF That Calls the API​

CREATE OR REPLACE FUNCTION CALL_OPENAI(prompt STRING)
RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = '3.11'
HANDLER = 'call_openai'
EXTERNAL_ACCESS_INTEGRATIONS = (OPENAI_INTEGRATION)
SECRETS = ('api_key' = OPENAI_API_KEY)
PACKAGES = ('requests')
AS
$$
import requests
import json
import _snowflake

def call_openai(prompt):
api_key = _snowflake.get_generic_secret_string('api_key')

response = requests.post(
'https://api.openai.com/v1/chat/completions',
headers={
'Authorization': f'Bearer {api_key}',
'Content-Type': 'application/json'
},
json={
'model': 'gpt-4o',
'messages': [{'role': 'user', 'content': prompt}],
'max_tokens': 512,
'temperature': 0.0
},
timeout=30
)
response.raise_for_status()
return response.json()['choices'][0]['message']['content']
$$;

Calling the UDF​

-- Single call
SELECT CALL_OPENAI('Summarize the key terms of a standard NDA.');

-- Batch over a table
SELECT
DOC_ID,
CALL_OPENAI('Extract the renewal date from: ' || DOC_TEXT) AS renewal_date
FROM CONTRACTS
LIMIT 50;

Calling Anthropic (Claude)​

The same pattern works for any REST API. Adjust the network rule and UDF accordingly.

CREATE OR REPLACE NETWORK RULE ANTHROPIC_NETWORK_RULE
MODE = EGRESS
TYPE = HOST_PORT
VALUE_LIST = ('api.anthropic.com:443');

CREATE OR REPLACE SECRET ANTHROPIC_API_KEY
TYPE = GENERIC_STRING
SECRET_STRING = 'sk-ant-...your-key...';

CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION ANTHROPIC_INTEGRATION
ALLOWED_NETWORK_RULES = (ANTHROPIC_NETWORK_RULE)
ALLOWED_AUTHENTICATION_SECRETS = (ANTHROPIC_API_KEY)
ENABLED = TRUE;
CREATE OR REPLACE FUNCTION CALL_CLAUDE(prompt STRING)
RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = '3.11'
HANDLER = 'call_claude'
EXTERNAL_ACCESS_INTEGRATIONS = (ANTHROPIC_INTEGRATION)
SECRETS = ('api_key' = ANTHROPIC_API_KEY)
PACKAGES = ('requests')
AS
$$
import requests
import _snowflake

def call_claude(prompt):
api_key = _snowflake.get_generic_secret_string('api_key')

response = requests.post(
'https://api.anthropic.com/v1/messages',
headers={
'x-api-key': api_key,
'anthropic-version': '2023-06-01',
'Content-Type': 'application/json'
},
json={
'model': 'claude-sonnet-4-20250514',
'max_tokens': 512,
'messages': [{'role': 'user', 'content': prompt}]
},
timeout=30
)
response.raise_for_status()
return response.json()['content'][0]['text']
$$;

Error Handling and Rate Limiting​

External APIs can fail or throttle requests. Build resilience into your UDF.

import time
import requests
import _snowflake

def call_openai_with_retry(prompt):
api_key = _snowflake.get_generic_secret_string('api_key')
max_retries = 3

for attempt in range(max_retries):
try:
response = requests.post(
'https://api.openai.com/v1/chat/completions',
headers={
'Authorization': f'Bearer {api_key}',
'Content-Type': 'application/json'
},
json={
'model': 'gpt-4o',
'messages': [{'role': 'user', 'content': prompt}],
'max_tokens': 512
},
timeout=30
)
if response.status_code == 429:
time.sleep(2 ** attempt)
continue
response.raise_for_status()
return response.json()['choices'][0]['message']['content']
except requests.exceptions.Timeout:
if attempt == max_retries - 1:
return 'ERROR: Request timed out'
except Exception as e:
return f'ERROR: {str(e)}'

return 'ERROR: Rate limited after retries'

Security Best Practices​

PracticeReason
Use SECRET objects for API keysKeys are encrypted and governed by RBAC
Restrict network rules to specific hostsMinimizes data exfiltration surface
Grant integration usage to specific rolesControls who can call external APIs
Audit external access via ACCESS_HISTORYTrack which queries send data externally
Apply row limits in batch callsAvoid unexpected API costs

Access Control​

-- Allow a role to use the integration
GRANT USAGE ON INTEGRATION OPENAI_INTEGRATION TO ROLE DATA_SCIENCE;

-- Allow a role to use the secret
GRANT READ ON SECRET OPENAI_API_KEY TO ROLE DATA_SCIENCE;

-- Allow a role to call the UDF
GRANT USAGE ON FUNCTION CALL_OPENAI(STRING) TO ROLE DATA_SCIENCE;

Key Takeaways​

  • External Access Integration enables Snowflake UDFs to call any external REST API securely.
  • Three objects are required: a network rule, a secret, and an integration.
  • Use _snowflake.get_generic_secret_string() to access API keys inside UDF code — never hard-code them.
  • Build retry logic and timeouts into UDFs that call external services.
  • Prefer Cortex built-in functions for simplicity and data residency; use external LLMs when specific models or capabilities are required.