CREATE EXTERNAL FUNCTION¶

Consulte também:: ALTER FUNCTION , SHOW EXTERNAL FUNCTIONS , DROP FUNCTION , DESCRIBE FUNCTION , CREATE API INTEGRATION

Sintaxe¶

CREATE [ OR REPLACE ] [ SECURE ] EXTERNAL FUNCTION <name> ( [ <arg_name> <arg_data_type> ] [ , ... ] )
  RETURNS <result_data_type>
  [ [ NOT ] NULL ]
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ { VOLATILE | IMMUTABLE } ]
  [ COMMENT = '<string_literal>' ]
  API_INTEGRATION = <api_integration_name>
  [ HEADERS = ( '<header_1>' = '<value_1>' [ , '<header_2>' = '<value_2>' ... ] ) ]
  [ CONTEXT_HEADERS = ( <context_function_1> [ , <context_function_2> ...] ) ]
  [ MAX_BATCH_ROWS = <integer> ]
  [ COMPRESSION = <compression_type> ]
  [ REQUEST_TRANSLATOR = <request_translator_udf_name> ]
  [ RESPONSE_TRANSLATOR = <response_translator_udf_name> ]
  AS <url_of_proxy_and_resource>;

Copy

Parâmetros obrigatórios¶

name:

Especifica o identificador da função.

O identificador pode conter o nome do esquema e o nome do banco de dados, assim como o nome da função.

O identificador não precisa ser único para o esquema no qual a função é criada, pois as funções são identificadas e resolvidas por seu nome e tipos de argumentos. Entretanto, a assinatura (nome e tipos de dados de argumento) deve ser única dentro do esquema.

O name deve seguir as regras para os identificadores Snowflake. Para obter mais detalhes, consulte Requisitos para identificadores.

A configuração de name igual ao nome do serviço remoto pode tornar a relação mais clara. No entanto, isto não é necessário.

( [ arg_name arg_data_type ] [ , ... ] )

Especifica os argumentos/entradas para a função externa. Eles devem corresponder aos argumentos que o serviço remoto espera.

Se não houver argumentos, incluir os parênteses sem nome(s) de argumento(s) e tipo(s) de dados.

RETURNS result_data_type

Especifica o tipo de dados retornados pela função.

API_INTEGRATION = api_integration_name

Este é o nome do objeto de integração de API que deve ser usado para autenticar a chamada para o serviço de proxy.

AS url_of_proxy_and_resource

Este é o URL de invocação do serviço de proxy (por exemplo, API Gateway ou API Management) e recurso através do qual o Snowflake chama o serviço remoto.

Parâmetros opcionais¶

SECURE

Especifica que a função é segura. Se uma função for segura, o URL, os cabeçalhos HTTP e os cabeçalhos de contexto são ocultados de todos os usuários que não são proprietários da função.

[ [ NOT ] NULL ]

Esta cláusula indica se a função pode retornar valores NULL ou deve retornar somente valores NON NULL. Se NOT NULL for especificado, a função deve retornar somente valores diferentes de NULL. Se NULL for especificado, a função pode retornar valores NULL.

Padrão: o padrão é NULL (ou seja, a função pode retornar os valores NULL).

CALLED ON NULL INPUT ou . { RETURNS NULL ON NULL INPUT | STRICT }

Especifica o comportamento da função quando chamada com entradas nulas. Ao contrário das funções definidas pelo sistema, que sempre retornam nulo quando qualquer entrada é nula, as funções externas podem lidar com entradas nulas, retornando valores não nulos mesmo quando uma entrada é nula:

CALLED ON NULL INPUT sempre chamará a função com entradas nulas. Cabe à função lidar adequadamente com tais valores.

RETURNS NULL ON NULL INPUT (ou seu sinônimo STRICT) não chamará a função se alguma entrada for nula. Em vez disso, um valor nulo será sempre retornado para essa linha. Note que a função ainda pode retornar nulo para entradas não nulas.

Padrão: CALLED ON NULL INPUT

{ VOLATILE | IMMUTABLE }

Especifica o comportamento da função ao retornar resultados:

VOLATILE: a função pode retornar valores diferentes para linhas diferentes, mesmo para a mesma entrada (por exemplo, devido ao não determinismo e estado).

IMMUTABLE: a função sempre retorna o mesmo resultado quando chamada com a mesma entrada. O Snowflake não verifica ou garante isto; o serviço remoto deve ser projetado para comportar-se desta maneira. Especificar IMMUTABLE para uma função que realmente retorna valores diferentes para a mesma entrada resultará em comportamento indefinido.

Padrão: VOLATILE

O Snowflake recomenda que você defina isto explicitamente em vez de aceitar o padrão. Esta configuração reduz explicitamente a chance de erro e diz aos usuários como a função se comporta. (O comando SHOW EXTERNAL FUNCTIONS mostra se uma função é volátil ou imutável).

Para informações adicionais importantes sobre funções externas VOLATILE vs. IMMUTABLE, consulte Categorizar sua função como volátil ou imutável.

COMMENT = 'string_literal'

Especifica um comentário para a função, que é exibido na coluna DESCRIPTION na saída SHOW FUNCTIONS e SHOW EXTERNAL FUNCTIONS na saída.

Padrão: user-defined function

HEADERS = ( 'header_1' = 'value_1' [ , 'header_2' = 'value_2' ... ] )

Esta cláusula permite aos usuários especificar os metadados de valor chave que são enviados com cada solicitação. O criador da função externa decide o que vai para os cabeçalhos, e o chamador não tem nenhum controle sobre ele. O Snowflake preenche todos os nomes de cabeçalho especificados com o prefixo “sf-custom-”, e os envia como cabeçalhos HTTP.

O valor deve ser uma cadeia de caracteres constante, não uma expressão.

Aqui está um exemplo:

HEADERS = (
    'volume-measure' = 'liters',
    'distance-measure' = 'kilometers'
)

Copy

Isto faz com que o Snowflake acrescente 2 cabeçalhos HTTP a cada solicitação HTTPS: sf-custom-volume-measure e sf-custom-distance-measure, com seus valores correspondentes.

As regras para nomes de cabeçalho são diferentes das regras para os identificadores do banco de dados do Snowflake. Os nomes de cabeçalho podem ser compostos por caracteres padrão ASCII mais visíveis (decimal 32 - 126), exceto os seguintes:

o caractere de espaço
(
)
,
/
:
;
<
>
=
"
?
@
[
]
\
{
}
_

Observe especificamente que o caractere sublinhado não é permitido em nomes de cabeçalho.

O nome e o valor do cabeçalho são delimitados por aspas simples, portanto, quaisquer aspas simples no nome ou valor do cabeçalho precisavam de um caractere de escape com a barra invertida.

Se o caractere de barra invertida for usado como um caractere literal dentro de um valor de cabeçalho, ele deve ter um caractere de escape.

Nos valores de cabeçalho, são permitidos tanto espaços como tabulações, mas os valores de cabeçalho não devem conter mais de um caractere de espaço em branco em uma linha. Esta restrição se aplica a combinações de caracteres do espaço em branco (por exemplo, um espaço seguido por uma tabulação), bem como a caracteres individuais do espaço em branco (por exemplo, dois espaços em linha).

Se o criador da função marcar a função como segura (com CREATE SECURE EXTERNAL FUNCTION...), então os cabeçalhos, os cabeçalhos de contexto, os cabeçalhos de contexto binário e o URL não são visíveis para os usuários da função.

A soma dos tamanhos dos nomes de cabeçalho e valores de cabeçalho para uma função externa deve ser menor ou igual a 8 KB.

CONTEXT_HEADERS = ( context_function_1 [ , context_function_2 ...] )

Isso é semelhante a HEADERS, mas em vez de usar cadeias de caracteres constantes, vincula os resultados da função de contexto do Snowflake aos cabeçalhos HTTP. (Para obter mais informações sobre as funções de contexto do Snowflake, consulte: Funções de contexto).

Nem todas as funções de contexto são suportadas em cabeçalhos de contexto. São suportados os seguintes itens:

CURRENT_ACCOUNT()
CURRENT_CLIENT()
CURRENT_DATABASE()
CURRENT_DATE()
CURRENT_IP_ADDRESS()
CURRENT_REGION()
CURRENT_ROLE()
CURRENT_SCHEMA()
CURRENT_SCHEMAS()
CURRENT_SESSION()
CURRENT_STATEMENT()
CURRENT_TIME()
CURRENT_TIMESTAMP()
CURRENT_TRANSACTION()
CURRENT_USER()
CURRENT_VERSION()
CURRENT_WAREHOUSE()
LAST_QUERY_ID()
LAST_TRANSACTION()
LOCALTIME()
LOCALTIMESTAMP()

Quando os nomes das funções são listados na cláusula CONTEXT_HEADERS, os nomes das funções não devem ficar entre aspas.

O Snowflake anexa sf-context ao cabeçalho antes de ser escrito para a solicitação HTTP.

Exemplo:

CONTEXT_HEADERS = (current_timestamp)

Copy

Neste exemplo, o Snowflake escreve o cabeçalho sf-context-current-timestamp na solicitação de HTTP.

Os caracteres permitidos nos nomes e valores de cabeçalho de contexto são os mesmos que os caracteres permitidos em nomes e valores de cabeçalho personalizados.

Funções de contexto podem gerar caracteres que são ilegais em valores de cabeçalho HTTP, incluindo (sem se limitar):

nova linha
Ä
Î
ß
ë
¬
±
©
®

O Snowflake substitui cada sequência de um ou mais caracteres ilegais por um caractere de espaço. (A substituição é por sequência, não por caractere).

Por exemplo, suponha que a função de contexto CURRENT_STATEMENT() retorne:

select
  /*ÄÎßë¬±©®*/
  my_external_function(1);

Copy

O valor enviado em sf-context-current-statement é:

select /* */ my_external_function(1);

Copy

Para garantir que os serviços remotos possam acessar o resultado original (com caracteres ilegais) da função de contexto mesmo que os caracteres ilegais tenham sido substituídos, o Snowflake também envia um cabeçalho de contexto binário que contém o resultado da função de contexto codificado em base64.

No exemplo acima, o valor enviado no cabeçalho de Base64 é o resultado da chamada:

base64_encode('select\n/ÄÎßë¬±©®/\nmy_external_function(1)')

Copy

O serviço remoto é responsável pela decodificação do valor de Base64, se necessário.

Cada um desses cabeçalhos de Base64 é nomeado de acordo com a seguinte convenção:

sf-context-<context-function>-base64

Copy

No exemplo acima, o nome do cabeçalho seria

sf-context-current-statement-base64

Copy

Se nenhum cabeçalho de contexto for enviado, então nenhum cabeçalho de contexto de Base64 será enviado.

Se as linhas enviadas para uma função externa forem divididas em vários lotes, então todos os lotes contêm os mesmos cabeçalhos de contexto e os mesmos cabeçalhos de contexto binário.

MAX_BATCH_ROWS = integer

Isto especifica o número máximo de linhas em cada lote enviado ao serviço de proxy.

O objetivo deste parâmetro é limitar os tamanhos dos lotes para serviços remotos que têm restrições de memória ou outras limitações. Este parâmetro não é um parâmetro de ajuste de desempenho. Este parâmetro especifica um tamanho máximo, não um tamanho recomendado.

Se você não especificar MAX_BATCH_ROWS, o Snowflake estima o tamanho ideal do lote e o utiliza.

O Snowflake recomenda deixar este parâmetro sem ajuste, a menos que o serviço remoto exija um limite.

COMPRESSION = compression_type

Se esta cláusula for especificada, a carga de JSON é comprimida quando enviada do Snowflake para o serviço de proxy, e quando enviada de volta do serviço de proxy para o Snowflake.

Os valores válidos são:

NONE.
GZIP.
DEFLATE.
AUTO.
- Em AWS, AUTO é equivalente a GZIP.
- No Azure, AUTO é equivalente a NONE.
- Em GCP, AUTO é equivalente a NONE.

O Amazon API Gateway compacta/descompacta automaticamente as solicitações. Para obter mais informações sobre a compactação e descompactação do Amazon API Gateway, consulte: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-gzip-compression-decompression.html

Para obter mais informações sobre compressão e descompressão para outros serviços de proxy de plataformas de nuvem, consulte a documentação para essas plataformas de nuvem.

Padrão: o padrão é AUTO.

REQUEST_TRANSLATOR = request_translator_udf_name

Isto especifica o nome da função do tradutor de solicitação. Para obter mais informações, consulte Uso de tradutores de solicitação e resposta com dados para um serviço remoto.

RESPONSE_TRANSLATOR = response_translator_udf_name

Isto especifica o nome da função do tradutor de resposta. Para obter mais informações, consulte Uso de tradutores de solicitação e resposta com dados para um serviço remoto.

Requisitos de controle de acesso¶

Uma função usada para executar este comando SQL deve ter os seguintes privilégios no mínimo:

Privilégio	Objeto	Notas
CREATE EXTERNAL FUNCTION	Esquema	Operating on functions also requires the USAGE privilege on the parent database and schema.
Ou OWNERSHIP ou USAGE	Integração de API	Exigido para criar funções externas que façam referência a uma integração de API.

Para instruções sobre como criar uma função personalizada com um conjunto específico de privilégios, consulte Criação de funções personalizadas.

Para informações gerais sobre concessões de funções e privilégios para executar ações de SQL em objetos protegíveis, consulte Visão geral do controle de acesso.

Notas de uso¶

Quando a compactação é usada, o Snowflake define os cabeçalhos HTTP como “Codificação de conteúdo” e “Codificação da aceitação”.
O(s) tipo(s) de argumento(s) e o tipo de retorno não pode(m) ser GEOGRAPHY.
Em relação aos metadados:

Atenção

Os clientes devem garantir que nenhum dado pessoal (exceto para um objeto do usuário), dados sensíveis, dados controlados por exportação ou outros dados regulamentados sejam inseridos como metadados ao usar o serviço Snowflake. Para obter mais informações, consulte Campos de metadados no Snowflake.
Instruções CREATE OR REPLACE <object> são atômicas. Ou seja, quando um objeto é substituído, o objeto antigo é excluído e o novo objeto é criado em uma única transação.

Exemplos¶

O exemplo seguinte mostra uma instrução CREATE EXTERNAL FUNCTION que é chamada por um serviço de proxy Amazon API Gateway:

CREATE OR REPLACE EXTERNAL FUNCTION local_echo(string_col VARCHAR)
  RETURNS VARIANT
  API_INTEGRATION = demonstration_external_api_integration_01
  AS 'https://xyz.execute-api.us-west-2.amazonaws.com/prod/remote_echo';

Copy

Neste exemplo:

local_echo é o nome chamado a partir de uma instrução SQL (por exemplo, você pode executar SELECT local_echo(varchar_column) ...;.)
string_col VARCHAR contém o nome e o tipo de dados do(s) parâmetro(s) de entrada. Uma função externa pode ter 0 ou mais parâmetros de entrada.
variant é o tipo de dados do valor retornado pela função externa.
O nome demonstration_external_api_integration_01 é o nome da integração de API criada anteriormente na instrução CREATE API INTEGRATION.
O URL https://xyz.execute-api.us-west-2.amazonaws.com/prod/remote_echo é a cadeia de caracteres que identifica o serviço e o recurso de proxy. Um comando HTTP POST é enviado para este URL.