CREATE FUNCTION (Snowpark Container Services)¶

Sintaxe¶

CREATE [ OR REPLACE ] 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 } ]
  SERVICE = <service_name>
  ENDPOINT = <endpoint_name>
  [ COMMENT = '<string_literal>' ]
  [ CONTEXT_HEADERS = ( <context_function_1> [ , <context_function_2> ...] ) ]
  [ MAX_BATCH_ROWS = <integer> ]
  AS '<http_path_to_request_handler>'

Parâmetros obrigatórios¶

name

Especifica o identificador (name) e quaisquer argumentos de entrada para a função.

• O identificador não precisa ser exclusivo para o esquema no qual a função é criada porque as funções são identificadas e resolvidas pela combinação do nome e dos tipos de argumento.

• O identificador deve começar com um caractere alfabético e não pode conter espaços ou caracteres especiais a menos que toda a cadeia de caracteres do identificador esteja entre aspas duplas (por exemplo, “Meu objeto”). Os identificadores delimitados por aspas duplas também diferenciam letras maiúsculas de minúsculas. Consulte Requisitos para identificadores.

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

Especifica os argumentos/entradas para a função de serviço. Eles devem corresponder aos argumentos que o serviço 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 do resultado retornado pela função.

SERVICE = service_name

Especifica o nome do serviço Snowpark Container Services.

ENDPOINT = endpoint_name

Especifica o nome do ponto de extremidade, conforme definido na especificação do serviço.

AS http_path_to_request_handler

Especifica o caminho HTTP para o código de serviço executado quando a função é chamada.

Parâmetros opcionais¶

[ [ NOT ] NULL ]

Especifica se a função pode retornar valores NULL ou deve retornar somente valores NON NULL. O padrão é NULL (ou seja, a função pode retornar NULL).

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

Especifica o comportamento da função quando chamada com entradas nulas. Em contraste com as funções definidas pelo sistema, que sempre retornam nulo quando qualquer entrada é nula, as funções podem manipular 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 manipular tais valores adequadamente.

• 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 ao estado).

• IMMUTABLE: a função assume que a função, quando chamada com as mesmas entradas, sempre retornará o mesmo resultado. Esta garantia não é verificada. Especificar IMMUTABLE para uma função que retorna valores diferentes para a mesma entrada resultará em comportamento indefinido.

Padrão: VOLATILE

[ MAX_BATCH_ROWS = integer ]

Especifica o tamanho do lote ao enviar dados para um serviço para aumentar a simultaneidade

COMMENT = 'string_literal'

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

Padrão: user-defined function

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

Isso 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 prefixa sf-context ao cabeçalho antes de gravá-lo na 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.

Funções de contexto podem gerar caracteres ilegais em valores de cabeçalho HTTP, incluindo (mas não limitado a) o seguinte:

• 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 o seguinte:

select
  /*ÄÎß묱©®*/
  my_service_function(1);

Copy

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

select /* */ my_service_function(1);

Copy

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

No exemplo acima, o valor enviado no cabeçalho codificado em base64 é o resultado da seguinte chamada:

base64_encode('select\n/ÄÎß묱©®/\nmy_service_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 o seguinte:

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 de serviço forem divididas em vários lotes, todos os lotes conterão os mesmos cabeçalhos de contexto e os mesmos cabeçalhos de contexto binário.

Requisitos de controle de acesso¶

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

Observe que operar em qualquer objeto de um esquema também requer o privilégio USAGE no banco de dados e esquema principais.

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¶

• 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.

• 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.

Exemplos¶

No Tutorial-1, você cria a seguinte função de serviço:

CREATE FUNCTION my_echo_udf (InputText VARCHAR)
  RETURNS VARCHAR
  SERVICE=echo_service
  ENDPOINT=echoendpoint
  AS '/echo';

Esta função se conecta ao ENDPOINT específico do SERVICE especificado. Quando você invoca esta função, o Snowflake envia uma solicitação para o caminho /echo dentro do contêiner de serviço.

Observe o seguinte:

• A função my_echo_udf usa uma cadeia de caracteres como entrada e retorna uma cadeia de caracteres.

• A propriedade SERVICE identifica o serviço (echo_service) e a propriedade ENDPOINT identifica o nome do ponto de extremidade amigável (echoendpoint).

• AS '/echo' especifica o caminho para o serviço. Em echo_service.py (veja o código do serviço), o decorador @app.post associa esse caminho à função echo.