Skip to main content

External Function

You can provide configuration to Snowflake Object Lifecycle Engine for the following operations with external function:

  • Manage the lifecycle of new and existing external functions
  • Manage grants of an external function

Usage

note

We have introduced SOLE for Data Products as a new framework for SOLE to help you easily build an ecosystem of data products. The major difference is in how you define Snowflake objects in the configuration file. Rather than having a grouped collection of objects, SOLE for Data Products goes for modular, self-describing, and explicit object definition.
Learn more about SOLE for Data Products, currently available as a private preview.

We have also introduced Data products as an extra layer on top of the data product platform capabilities making managing data products easier than ever. Learn more about Data Products, currently available as a private preview.

databases:
<database-name>:
schemas:
<schema-name>:
external_functions:
<external-function-name>:
<configuration-key>: <value>
grants:
<privilege>:
- <role-name>
- <role-name>

Supported parameters

The engine supports the parameters listed below.

Configuration KeyRequired/OptionalData Types and ValuesDescription
api_integrationRequiredStringSpecifies the name of the API integration object that should be used to authenticate the call to the proxy service
return_behaviorRequiredStringSpecifies the behavior of the external function when returning results
return_typeRequiredStringSpecifies the data type returned by the external function
url_of_proxy_and_resourceRequiredStringThe invocation URL of the proxy service and resource through which Snowflake calls the remote service
argOptionalObject: See here for a definition of argSpecifies the arguments/inputs for the external function. These should correspond to the arguments that the remote service expects.
commentOptionalStringA description of the external function
compressionOptionalStringIf specified, the JSON payload is compressed when sent from Snowflake to the proxy service, and back from the proxy service to Snowflake
context_headersOptionalList of StringBinds Snowflake context function results to HTTP headers
deletedOptionalBoolean: True enables deletion prevention, False does nothingSpecifies what objects are allowed to be deleted
headerOptionalObject: See here for a definition of headerAllows you to specify key-value metadata that is sent with every request as HTTP header
grantsOptionalMap: See Supported External Function Grants to RolesLists Privileges and Roles to which privileges are granted on the current external function
manage_modeOptionalString: all (default), none, grantsConfigures what properties to manage for the external function.
See Changing Manage Mode before changing the value.
max_batch_rowsOptionalIntegerSpecifies the maximum number of rows in each batch sent to the proxy service
null_input_behaviorOptionalStringSpecifies the behavior of the external function when called with null inputs
return_null_allowedOptionalBooleanIndicates whether the function can return NULL values or must return only NON-NULL values
warning

During subsequent pipeline runs a force-replacement behavior might be observed in PLAN and APPLY phases for a few parameters like comment, max_batch_rows, null_input_behavior, return_behavior, etc.

arg parameter

You can specify the arguments for the external function.

Multiples arguments in an object format can be listed in the arg parameter, with each having the following supported parameters:

Configuration KeyRequired/OptionalData Types and ValuesDescription
typeRequiredStringData-type of the Column

Example

arg:
ARG_1:
type: VARCHAR
ARG_2:
type: DATE

header parameter

You can specify the header value for the external function.

Multiple values in an object format can be listed in the header parameter with each having the following supported parameters:

Configuration KeyRequired/OptionalData Types and ValuesDescription
valueRequiredStringData-type of the Column

Example

header:
HEADER1:
value: "Header_value_1"
HEADER2:
value: "Header_value_2"

Supported external function grants to roles

Following are the privileges you can grant to roles in the external function definition:

  • USAGE
  • OWNERSHIP

Examples

databases:
EXT_DATABASE:
schemas:
EXT_SCHEMA:
external_functions:
EXT_1:
grants:
USAGE:
- ACCOUNTADMIN
- ROLE_1
api_integration: "EXT_API"
return_behavior: "IMMUTABLE"
return_type: "VARCHAR"
url_of_proxy_and_resource: "https://123456.execute-api.us-west-2.amazonaws.com/prod/"
header:
Header1:
value: "Test_Header"
EXT_1|2:
grants:
USAGE:
- ACCOUNTADMIN
- ROLE_1
api_integration: "EXT_API"
return_behavior: "IMMUTABLE"
return_type: "VARCHAR"
url_of_proxy_and_resource: "https://123456.execute-api.us-west-2.amazonaws.com/prod/"
arg:
ARG_1:
type: VARCHAR(16777216)
header:
Header1:
value: "Test_Header"
EXT_1|VARCHAR(16777216)|DATE:
grants:
USAGE:
- ACCOUNTADMIN
- ROLE_1
api_integration: "EXT_API"
return_behavior: "IMMUTABLE"
return_type: "VARCHAR"
url_of_proxy_and_resource: "https://123456.execute-api.us-west-2.amazonaws.com/prod/"
arg:
ARG_1:
type: VARCHAR(16777216)
ARG_2:
type: DATE
header:
Header1:
value: "Test_Header"