Skip to main content

External Function

Configuration can be provided to Snowflake Object Lifecycle Engine for the following operation with External Function:

  • Manage Lifecycle of new and existing External Function
  • Manage Grants of a External Function

Supported Parameters​

The engine supports the parameters listed below.

  • API_INTEGRATION: The name of the API integration object that should be used to authenticate the call to the proxy service.
    • REQUIRED
    • Configuration Key: api_integration
    • Data Type: String
  • RETURN_BEHAVIOR: Specifies the behavior of the external function when returning results
    • REQUIRED
    • Configuration Key: return_behavior
    • Data Type: String
  • RETURN_TYPE: Specifies the data type returned by the external function.
    • REQUIRED
    • Configuration Key: return_type
    • Data Type: String
  • URL_OF_PROXY_AND_RESOURCE: This is the invocation URL of the proxy service and resource through which Snowflake calls the remote service.
    • REQUIRED
    • Configuration Key: url_of_proxy_and_resource
    • Data Type: String
  • ARG: Specifies the arguments/inputs for the external function. These should correspond to the arguments that the remote service expects.
    • Configuration Key: arg
    • Data Type: Object. See here for definition of Argument
  • COMMENT: A description of the external function.
    • Configuration Key: comment
    • Data Type: String
  • COMPRESSION: If specified, the JSON payload is compressed when sent from Snowflake to the proxy service, and when sent back from the proxy service to Snowflake.
    • Configuration Key: compression
    • Data Type: String
  • CONTEXT_HEADERS: Binds Snowflake context function results to HTTP headers.
    • Configuration Key: context_headers
    • Data Type: List of String
  • HEADER: Allows users to specify key-value metadata that is sent with every request as HTTP headers.
    • Configuration Key: header
    • Data Type: Object. See here for definition of Argument
  • MAX_BATCH_ROWS: This specifies the maximum number of rows in each batch sent to the proxy service.
    • Configuration key: max_batch_rows
    • Data Type: Integer
  • NULL_INPUT_BEHAVIOUR: Specifies the behavior of the external function when called with null inputs.
    • Configuration key: null_input_behavior
    • Data Type: String
  • RETURN_NULL_ALLOWED: Indicates whether the function can return NULL values or must return only NON-NULL values.
    • Configuration key: return_null_allowed
    • Data Type: Boolean
  • MANAGE_MODE: Configures what properties to manage for the external function.
    • Configuration key: manage_mode
    • Data Type: String
    • Possible Values:
      • none
      • grants
      • all(Default)
  • GRANTS: List of Privileges and Roles to which privileges are granted on the current external function.
    • Configuration key: grants
    • Data Type: Map
caution

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

Arg​

In the arg parameter, users 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:

  • TYPE: Data-type of the Column
    • REQUIRED
    • Configuration key: type
    • Data Type: String

Example​

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

In the header parameter, users 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:

  • TYPE: Data-type of the Column
    • REQUIRED
    • Configuration key: value
    • Data Type: String

Example​

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

Basic syntax​

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

Supported External Function Grants to Roles​

Following is the list of Privilege Grants to Roles that can be specified 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"
Last updated on