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
| Factor | Cortex Built-In | External LLM |
|---|---|---|
| Setup | Zero configuration | Network rules, secrets, integrations required |
| Data residency | Data stays in Snowflake | Data sent to external API |
| Model selection | Snowflake-supported models | Any API-accessible model |
| Cost | Snowflake credit-based pricing | External API billing |
| Latency | Low (in-platform) | Higher (network round-trip) |
| Fine-tuning | Cortex Fine-Tuning | Provider'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:
- Network Rule — specifies the allowed external endpoint.
- Secret — stores the API key securely.
- 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
| Practice | Reason |
|---|---|
Use SECRET objects for API keys | Keys are encrypted and governed by RBAC |
| Restrict network rules to specific hosts | Minimizes data exfiltration surface |
| Grant integration usage to specific roles | Controls who can call external APIs |
Audit external access via ACCESS_HISTORY | Track which queries send data externally |
| Apply row limits in batch calls | Avoid 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.