# EXTERNAL FUNCTION

Config path: `/<database>/<schema>/external_function/<name>(<dtypes>).yaml`

Example:

```yaml
arguments:
  string_col: VARCHAR(255)

returns: VARIANT

api_integration: test_api_integration
url: https://xyz.execute-api.us-west-2.amazonaws.com/production/remote_echo
```

## Schema

* **arguments** (dict)
  * *{key}* (ident) - argument name
  * *{value}* (str) - argument data type
* <mark style="background-color:red;">**returns**</mark> (str) - for single return value, return data type
* <mark style="background-color:red;">**api\_integration**</mark> (ident) - name of API integration
* <mark style="background-color:red;">**url**</mark> (str) - invocation URL of proxy service
* **is\_secure** (bool) - is function SECURE
* **is\_strict** (bool) - is function STRICT (always returns NULL on NULL input)
* **is\_immutable** (bool) - is function IMMUTABLE (same input always produced the same output)
* **headers** (dict)
  * *{key}* (str) - header name
  * *{value}* (str) - header value
* **context\_headers** (list)
  * *{items}* (ident) - context function name
* **max\_batch\_rows** (int) - maximum number of rows in each batch sent to the proxy service
* **comment** (str)

## Usage notes

1. Snowflake supports [overloading](https://docs.snowflake.com/en/sql-reference/udf-overview.html#overloading-of-udf-names) of function names. Multiple functions may have the same name as long as they have different arguments. It is required to use comma-separated base data types of arguments in config names.\
   \
   For example: `my_function(number).yaml`, `my_function(varchar,number).yaml`
2. API integration should be [created and granted](/guides/other-guides/integrations.md) to SnowDDL admin role manually prior to execution.

## Additional privileges

In order for `EXTERNAL FUNCTION` objects to operate properly, the following additional grants should be added to OWNER role in [schema config](/basic/yaml-configs/schema.md):

* `owner_integration_usage` - please specify names of API INTEGRATION objects used by external functions. Functions may work without explicit INTEGRATION USAGE grant to OWNER role, but it is not guaranteed for Snowflake keep it this way forever.

## Links

* [CREATE EXTERNAL FUNCTION](https://docs.snowflake.com/en/sql-reference/sql/create-external-function.html)
* [SHOW EXTERNAL FUNCTIONS](https://docs.snowflake.com/en/sql-reference/sql/show-external-functions.html)
* [CREATE API INTEGRATION](https://docs.snowflake.com/en/sql-reference/sql/create-api-integration.html)
* [Parser & JSON Schema (GitHub)](https://github.com/littleK0i/SnowDDL/blob/master/snowddl/parser/external_function.py)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.snowddl.com/basic/yaml-configs/external-function.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.